test(artwork): use renamed ArtworkWorkerConcurrency in e2e tests

- 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).

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 {

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

cmd/pls.go

@@ -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, core.NewImageUploadService(ds))
 
 	for _, file := range files {
 		absPath, err := filepath.Abs(file)

cmd/scan.go

@@ -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, core.NewImageUploadService(ds))
 
 	// Parse targets from command line or file
 	var scanTargets []model.ScanTarget

cmd/wire_gen.go

@@ -65,21 +65,14 @@ func CreateNativeAPIRouter(ctx context.Context) *nativeapi.Router {
 	sqlDB := db.Db()
 	dataStore := persistence.New(sqlDB)
 	share := core.NewShare(dataStore)
-	imageUploadService := core.NewImageUploadService()
+	imageUploadService := core.NewImageUploadService(dataStore)
 	playlistsPlaylists := playlists.NewPlaylists(dataStore, imageUploadService)
 	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)
@@ -91,29 +84,29 @@ func CreateSubsonicAPIRouter(ctx context.Context) *subsonic.Router {
 	sqlDB := db.Db()
 	dataStore := persistence.New(sqlDB)
 	fileCache := artwork.GetImageCache()
+	imageStore := artwork.ProvideImageStore()
 	fFmpeg := ffmpeg.New()
+	service := artwork.NewService(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()
+	imageUploadService := core.NewImageUploadService(dataStore)
 	playlistsPlaylists := playlists.NewPlaylists(dataStore, imageUploadService)
-	modelScanner := scanner.New(ctx, dataStore, cacheWarmer, broker, playlistsPlaylists, metricsMetrics)
+	modelScanner := scanner.New(ctx, dataStore, broker, playlistsPlaylists, metricsMetrics)
 	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)
+	router := subsonic.New(dataStore, service, mediaStreamer, archiver, players, provider, modelScanner, broker, playlistsPlaylists, playTracker, share, playbackServer, metricsMetrics, lyricsLyrics, transcodeDecider, sonicSonic)
 	return router
 }
 
@@ -121,24 +114,25 @@ func CreateJellyfinAPIRouter(ctx context.Context) *jellyfin.Router {
 	sqlDB := db.Db()
 	dataStore := persistence.New(sqlDB)
 	fileCache := artwork.GetImageCache()
+	imageStore := artwork.ProvideImageStore()
 	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)
+	service := artwork.NewService(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()
+	imageUploadService := core.NewImageUploadService(dataStore)
 	playlistsPlaylists := playlists.NewPlaylists(dataStore, imageUploadService)
+	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)
+	router := jellyfin.New(dataStore, service, mediaStreamer, transcodeDecider, players, playTracker, playlistsPlaylists, provider, sonicSonic, lyricsLyrics, broker)
 	return router
 }
 
@@ -146,19 +140,14 @@ func CreatePublicRouter() *public.Router {
 	sqlDB := db.Db()
 	dataStore := persistence.New(sqlDB)
 	fileCache := artwork.GetImageCache()
+	imageStore := artwork.ProvideImageStore()
 	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)
+	service := artwork.NewService(dataStore, fileCache, imageStore, fFmpeg)
 	transcodingCache := stream.GetTranscodingCache()
 	mediaStreamer := stream.NewMediaStreamer(dataStore, fFmpeg, transcodingCache)
 	share := core.NewShare(dataStore)
 	archiver := core.NewArchiver(mediaStreamer, dataStore, share)
-	router := public.New(dataStore, artworkArtwork, mediaStreamer, share, archiver)
+	router := public.New(dataStore, service, mediaStreamer, share, archiver)
 	return router
 }
 
@@ -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()
-	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()
+	imageUploadService := core.NewImageUploadService(dataStore)
 	playlistsPlaylists := playlists.NewPlaylists(dataStore, imageUploadService)
-	modelScanner := scanner.New(ctx, dataStore, cacheWarmer, broker, playlistsPlaylists, metricsMetrics)
+	metricsMetrics := metrics.GetPrometheusInstance(dataStore)
+	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()
-	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()
+	imageUploadService := core.NewImageUploadService(dataStore)
 	playlistsPlaylists := playlists.NewPlaylists(dataStore, imageUploadService)
-	modelScanner := scanner.New(ctx, dataStore, cacheWarmer, broker, playlistsPlaylists, metricsMetrics)
+	metricsMetrics := metrics.GetPrometheusInstance(dataStore)
+	modelScanner := scanner.New(ctx, dataStore, broker, playlistsPlaylists, metricsMetrics)
 	watcher := scanner.GetWatcher(dataStore, modelScanner)
 	return watcher
 }
@@ -244,10 +217,9 @@ func CreateArtworkWorker() *artwork.Worker {
 	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)
 	fFmpeg := ffmpeg.New()
-	worker := artwork.NewWorker(dataStore, imageStore, provider, fFmpeg)
+	fileCache := artwork.GetImageCache()
+	worker := artwork.NewWorker(dataStore, imageStore, agentsAgents, fFmpeg, broker, fileCache)
 	return worker
 }
 

core/agents/agents.go

@@ -124,6 +124,50 @@ 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() {
+		ag := a.getAgent(ea)
+		if ag == nil {
+			continue
+		}
+		if retriever, ok := ag.(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() {
+		ag := a.getAgent(ea)
+		if ag == nil {
+			continue
+		}
+		if retriever, ok := ag.(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:

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
+}

core/artwork/agent_images.go

@@ -0,0 +1,123 @@
+package artwork
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/url"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/core/agents"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/utils/str"
+)
+
+// externalName applies the DevPreserveUnicodeInExternalCalls normalization the aggregate
+// provider used, so agent searches match the same way (typographic quotes/dashes cleared
+// unless preserved).
+func externalName(name string) string {
+	if conf.Server.DevPreserveUnicodeInExternalCalls {
+		return name
+	}
+	return str.Clear(name)
+}
+
+// gateFunc gates one named external fetch (rate limit + circuit breaker per name).
+// resolveItem defaults to passthroughGate; the worker injects the per-agent gate.
+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()
+}
+
+// denyGate refuses every external fetch with a definitive not-found, so local-only
+// resolution never runs a network step even if an external branch is reached.
+func denyGate(_ string, _ func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error) {
+	return nil, "", model.ErrNotFound
+}
+
+// bestImageURL returns the largest-Size image URL, skipping empty or unparseable
+// URLs; nil when none qualifies. Parsing happens per candidate so a malformed largest
+// URL never shadows a valid smaller one.
+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 {
+			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, each under its own gate.
+// Returns the winning reader + agent name; extErr is true only when NO agent succeeded and
+// at least one failed transiently (a later success beats an earlier agent error).
+func fetchArtistImage(ctx context.Context, ag *agents.Agents, gate gateFunc, ar model.Artist) (r io.ReadCloser, agentName string, extErr bool) {
+	// Synthetic artists have no real external image; mirror Agents.GetArtistImages' guard so a
+	// direct retriever call can't assign an unrelated result to Unknown/Various Artists.
+	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 // includes errBreakerOpen and download failures: retry via the next agent
+		}
+	}
+	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
+		}
+	}
+	return nil, "", extErr
+}
+
+// isTransientExternal reports whether an external step failed in a way 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)
+}

core/artwork/agent_images_test.go

@@ -0,0 +1,217 @@
+package artwork
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"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/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
+}
+
+func (f *fakeImageAgent) AgentName() string { return f.name }
+
+func (f *fakeImageAgent) GetArtistImages(_ context.Context, _, name, _ string) ([]agents.ExternalImage, error) {
+	f.artistCalls++
+	f.gotArtistName = name
+	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 (ignoring the DataStore) and
+// enables them in order, returning the process-wide Agents. Because the fakes ignore
+// ds, reusing the 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())
+		})
+	})
+
+	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"}))
+		})
+	})
+})

core/artwork/artwork.go

@@ -1,134 +0,0 @@
-package artwork
-
-import (
-	"context"
-	"errors"
-	_ "image/gif"
-	"io"
-	"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"
-	"github.com/navidrome/navidrome/utils/cache"
-	_ "golang.org/x/image/webp"
-)
-
-var ErrUnavailable = errors.New("artwork unavailable")
-
-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)
-}
-
-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}
-}
-
-type artwork struct {
-	ds       model.DataStore
-	cache    cache.FileCache
-	ffmpeg   ffmpeg.FFmpeg
-	provider external.Provider
-}
-
-type artworkReader interface {
-	cache.Item
-	LastUpdated() time.Time
-	Reader(ctx context.Context) (io.ReadCloser, string, error)
-}
-
-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)
-	if err == nil {
-		reader, lastUpdate, err = a.Get(ctx, artID, size, square)
-	}
-	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 reader, lastUpdate, 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
-	}
-
-	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
-	}
-	return r, artReader.LastUpdated(), nil
-}
-
-type coverArtGetter interface {
-	CoverArtID() model.ArtworkID
-}
-
-func (a *artwork) getArtworkId(ctx context.Context, id string) (model.ArtworkID, error) {
-	if id == "" {
-		return model.ArtworkID{}, ErrUnavailable
-	}
-	artID, err := model.ParseArtworkID(id)
-	if 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)
-	if err != nil {
-		return model.ArtworkID{}, err
-	}
-	if e, ok := entity.(coverArtGetter); ok {
-		artID = e.CoverArtID()
-	}
-	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
-}
-
-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
-		}
-	}
-	return artReader, err
-}

core/artwork/artwork_internal_test.go

@@ -1,628 +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{{
-					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
-}

core/artwork/artwork_suite_test.go

@@ -28,9 +28,6 @@ func TestArtwork(t *testing.T) {
 		goleak.IgnoreTopFunction("github.com/rjeczalik/notify.(*recursiveTree).dispatch"),
 		goleak.IgnoreTopFunction("github.com/rjeczalik/notify.(*nonrecursiveTree).dispatch"),
 		goleak.IgnoreTopFunction("github.com/rjeczalik/notify.(*nonrecursiveTree).internal"),
-		// The old cache_warmer.go starts a goroutine per NewCacheWarmer call with
-		// no shutdown path (dark-launch target for Phase 2, not touched here).
-		goleak.IgnoreTopFunction("github.com/navidrome/navidrome/core/artwork.(*cacheWarmer).waitSignal"),
 	)
 
 	tests.Init(t, false)
@@ -40,7 +37,7 @@ 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.
+// ReadTags is not exercised by these tests, 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 }

core/artwork/artwork_test.go

@@ -1,57 +0,0 @@
-package artwork_test
-
-import (
-	"context"
-	"io"
-
-	"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/onsi/ginkgo/v2"
-	. "github.com/onsi/gomega"
-)
-
-var _ = Describe("Artwork", func() {
-	var aw artwork.Artwork
-	var ds model.DataStore
-	var ffmpeg *tests.MockFFmpeg
-
-	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)
-	})
-
-	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())
-
-				ph, err := resources.FS().Open(consts.PlaceholderAlbumArt)
-				Expect(err).ToNot(HaveOccurred())
-				phBytes, err := io.ReadAll(ph)
-				Expect(err).ToNot(HaveOccurred())
-
-				result, err := io.ReadAll(r)
-				Expect(err).ToNot(HaveOccurred())
-
-				Expect(result).To(Equal(phBytes))
-			})
-		})
-	})
-	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))
-			})
-		})
-	})
-})

core/artwork/benchmark_e2e_test.go

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

core/artwork/cache_warmer.go

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

core/artwork/cache_warmer_test.go

@@ -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)
-}

core/artwork/disc.go

@@ -2,26 +2,22 @@ package artwork
 
 import (
 	"context"
-	"crypto/md5"
 	"fmt"
 	"io"
 	"path"
 	"path/filepath"
 	"strconv"
 	"strings"
-	"time"
 
 	"github.com/Masterminds/squirrel"
-	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/core/ffmpeg"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
-	"github.com/navidrome/navidrome/utils"
 )
 
+// 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 +25,26 @@ type discArtworkReader struct {
 	isMultiFolder  bool
 	firstTrackRel  string // library-relative; for fromTag / ffmpeg via lib.Abs
 	lib            libraryView
-	updatedAt      *time.Time
 }
 
-func newDiscArtworkReader(ctx context.Context, a *artwork, artID model.ArtworkID) (*discArtworkReader, error) {
+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, _, err := loadAlbumFoldersPaths(ctx, ds, *al)
 	if err != nil {
 		return nil, err
 	}
 
 	// Query mediafiles for this album + disc to find folder associations and first track
-	mfs, err := a.ds.MediaFile(ctx).GetAll(model.QueryOptions{
+	mfs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
 		Sort:    "track_number",
 		Order:   "ASC",
 		Filters: squirrel.Eq{"album_id": albumID, "disc_number": discNumber},
@@ -58,7 +53,7 @@ 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
 	}
@@ -80,7 +75,7 @@ func newDiscArtworkReader(ctx context.Context, a *artwork, artID model.ArtworkID
 		for id := range allFolderIDs {
 			folderIDs = append(folderIDs, id)
 		}
-		folders, err := a.ds.Folder(ctx).GetAll(model.QueryOptions{
+		folders, err := ds.Folder(ctx).GetAll(model.QueryOptions{
 			Filters: squirrel.Eq{"folder.id": folderIDs},
 		})
 		if err != nil {
@@ -92,46 +87,15 @@ func newDiscArtworkReader(ctx context.Context, a *artwork, artID model.ArtworkID
 		}
 	}
 
-	isMultiFolder := len(al.FolderIDs) > 1
-
-	r := &discArtworkReader{
-		a:              a,
+	return &discArtworkReader{
 		album:          *al,
 		discNumber:     discNumber,
 		imgFiles:       imgFiles,
 		discFoldersRel: discFoldersRel,
-		isMultiFolder:  isMultiFolder,
+		isMultiFolder:  len(al.FolderIDs) > 1,
 		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...)
+	}, nil
 }
 
 func (d *discArtworkReader) fromDiscArtPriority(ctx context.Context, ffmpeg ffmpeg.FFmpeg, priority string) []sourceFunc {

core/artwork/e2e/acquire_serve_test.go

@@ -0,0 +1,226 @@
+package e2e
+
+import (
+	"context"
+	"errors"
+	"io"
+	"os"
+
+	"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"
+)
+
+// These specs wire the real Worker and Service over the same ImageStore and mock repositories,
+// then drive the full enqueue → drain → serve loop. They assert the integration of the chain, not
+// the per-source resolution rules (which the unit suites in package artwork already cover).
+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.Service
+		worker     *artwork.Worker
+		coverBytes []byte
+	)
+
+	// itemFound reports whether the worker has persisted a resolved (hash-bearing) state row.
+	itemFound := func(kind, id string) func() bool {
+		return func() bool {
+			ia, err := artRepo.GetItemArtwork(kind, id, model.ImageTypePrimary)
+			return err == nil && ia.Hash != ""
+		}
+	}
+	itemAbsent := func(kind, id string) func() bool {
+		return func() bool {
+			ia, err := artRepo.GetItemArtwork(kind, id, model.ImageTypePrimary)
+			return err == nil && ia.Hash == ""
+		}
+	}
+
+	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" // upload wins first; kept offline as a safety net
+		conf.Server.EnableMediaFileCoverArt = true
+		conf.Server.ArtworkWorkerConcurrency = 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 and never touch the resize cache, so this reader is a
+		// compile-time stand-in only; the resize path is covered by the package's serving_test.
+		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.NewService(ds, imgCache, store, ffm)
+		worker = artwork.NewWorker(ds, store, agents.GetAgents(ds, nil), ffm, events.NoopBroker(), imgCache)
+	})
+
+	// seedFolderAlbum wires an album backed by the real fixture folder cover, shared by the album
+	// and playlist-grid scenarios.
+	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")
+		worker.Bump("al", "al1")
+		runWorkerUntil(ctx, worker, itemFound("al", "al1"))
+
+		ia, err := artRepo.GetItemArtwork("al", "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}})
+		worker.Bump("ar", "ar1")
+		runWorkerUntil(ctx, worker, itemFound("ar", "ar1"))
+
+		ia, err := artRepo.GetItemArtwork("ar", "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"}}
+		worker.Bump("pl", "pl1")
+		runWorkerUntil(ctx, worker, itemFound("pl", "pl1"))
+
+		ia, err := artRepo.GetItemArtwork("pl", "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))
+		// The generated grid is a fresh PNG placed in the content-addressed store.
+		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}
+		worker.Bump("ra", "ra1")
+		runWorkerUntil(ctx, worker, itemFound("ra", "ra1"))
+
+		ia, err := artRepo.GetItemArtwork("ra", "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,
+		}})
+
+		// First read: no state row yet → extract embedded art provisionally and enqueue the track.
+		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("mf", "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 and confirm the persisted hash matches.
+		runWorkerUntil(ctx, worker, itemFound("mf", "mf1"))
+		ia, err := artRepo.GetItemArtwork("mf", "mf1", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(ia.Source).To(Equal("embedded"))
+		Expect(ia.Hash).To(Equal(provisional.Hash))
+
+		// Second read: now served from the persisted state row / store, same bytes.
+		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("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}})
+		worker.Bump("al", "alx")
+		runWorkerUntil(ctx, worker, itemAbsent("al", "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())
+	})
+})

core/artwork/e2e/album_test.go

@@ -1,469 +0,0 @@
-package artworke2e_test
-
-import (
-	"testing/fstest"
-
-	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/model"
-	. "github.com/onsi/ginkgo/v2"
-	. "github.com/onsi/gomega"
-)
-
-const (
-	defaultCoverPriority = "cover.*, folder.*, front.*, embedded, external"
-	defaultDiscPriority  = "disc*.*, cd*.*, cover.*, folder.*, front.*, discsubtitle, embedded"
-)
-
-var _ = Describe("Album artwork resolution", func() {
-	BeforeEach(func() {
-		setupHarness()
-	})
-
-	When("an album has a single folder with cover.jpg at the album root", func() {
-		// Artist/
-		// └── Album/
-		//     ├── 01 - Track.mp3
-		//     └── cover.jpg            ← matched by cover.*
-		It("returns the album-root cover", func() {
-			conf.Server.CoverArtPriority = defaultCoverPriority
-			setLayout(fstest.MapFS{
-				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
-				"Artist/Album/cover.jpg":      imageFile("album-root"),
-			})
-			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("album-root")))
-		})
-	})
-
-	// https://github.com/navidrome/navidrome/issues/5376
-	// cover.* basenames tie across album-root and per-disc folders;
-	// compareImageFiles must prefer shallower paths.
-	When("a multi-disc album has a cover.jpg at the album root and per-disc covers", func() {
-		// Artist/
-		// └── Album/
-		//     ├── CD1/
-		//     │   ├── 01 - Track.mp3
-		//     │   └── cover.jpg        ← should not win
-		//     ├── CD2/
-		//     │   ├── 01 - Track.mp3
-		//     │   └── cover.jpg
-		//     └── cover.jpg            ← should win (album-root fallback)
-		It("prefers the album-root cover over per-disc covers", func() {
-			conf.Server.CoverArtPriority = defaultCoverPriority
-			setLayout(fstest.MapFS{
-				"Artist/Album/CD1/01 - Track.mp3": trackFile(1, "Track CD1"),
-				"Artist/Album/CD2/01 - Track.mp3": trackFile(1, "Track CD2"),
-				"Artist/Album/cover.jpg":          imageFile("album-root"),
-				"Artist/Album/CD1/cover.jpg":      imageFile("disc1"),
-				"Artist/Album/CD2/cover.jpg":      imageFile("disc2"),
-			})
-			scan()
-
-			al := firstAlbum()
-			Expect(al.FolderIDs).To(HaveLen(2),
-				"sanity check: scanner should treat the two disc subfolders as one multi-disc album")
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("album-root")))
-		})
-	})
-
-	// https://github.com/navidrome/navidrome/issues/5376
-	// folder.jpg basenames tie across album-root and per-disc folders;
-	// compareImageFiles must prefer shallower paths.
-	When("a multi-disc album has folder.jpg at the album root AND in each disc subfolder", func() {
-		// Artist/
-		// └── Album/
-		//     ├── CD1/
-		//     │   ├── 01 - Track.mp3
-		//     │   └── folder.jpg       ← should not win
-		//     ├── CD2/
-		//     │   ├── 01 - Track.mp3
-		//     │   └── folder.jpg
-		//     └── folder.jpg           ← should win (album-root fallback)
-		It("prefers the album-root folder.jpg over per-disc folder.jpg", func() {
-			conf.Server.CoverArtPriority = defaultCoverPriority
-			setLayout(fstest.MapFS{
-				"Artist/Album/CD1/01 - Track.mp3": trackFile(1, "Track CD1"),
-				"Artist/Album/CD2/01 - Track.mp3": trackFile(1, "Track CD2"),
-				"Artist/Album/folder.jpg":         imageFile("album-root"),
-				"Artist/Album/CD1/folder.jpg":     imageFile("disc1"),
-				"Artist/Album/CD2/folder.jpg":     imageFile("disc2"),
-			})
-			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("album-root")))
-		})
-	})
-
-	// https://github.com/navidrome/navidrome/issues/5376
-	// Single-subfolder albums must still consider the parent folder's images.
-	When("an album lives entirely under a single disc subfolder with cover.jpg at the parent", func() {
-		// Artist/
-		// └── Album/
-		//     ├── disc1/
-		//     │   └── 01 - Track.mp3
-		//     └── cover.jpg            ← should win (parent-folder fallback)
-		It("uses the parent-folder cover for single-disc-subfolder albums", func() {
-			conf.Server.CoverArtPriority = defaultCoverPriority
-			setLayout(fstest.MapFS{
-				"Artist/Album/disc1/01 - Track.mp3": trackFile(1, "Track"),
-				"Artist/Album/cover.jpg":            imageFile("album-root"),
-			})
-			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("album-root")))
-		})
-	})
-
-	// https://github.com/navidrome/navidrome/issues/5456
-	When("a top-level multi-disc album has cover.jpg at the album root and per-disc folder.jpg", func() {
-		// Album/                        (top-level folder, Path=".")
-		// ├── CD1/
-		// │   ├── 01 - Track.mp3
-		// │   └── folder.jpg
-		// ├── CD2/
-		// │   ├── 01 - Track.mp3
-		// │   └── folder.jpg
-		// └── cover.jpg                ← should win (album-root)
-		It("prefers the album-root cover.jpg", func() {
-			conf.Server.CoverArtPriority = defaultCoverPriority
-			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"),
-			})
-			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("album-root")))
-		})
-	})
-
-	When("CoverArtPriority puts embedded first and the album has both embedded and external art", func() {
-		// Artist/
-		// └── Album/
-		//     ├── 01 - Track.mp3      ← has embedded picture (wins via "embedded")
-		//     └── cover.jpg
-		It("returns the embedded image", func() {
-			conf.Server.CoverArtPriority = "embedded, cover.*, folder.*, front.*, external"
-			setLayout(fstest.MapFS{
-				"Artist/Album/01 - Track.mp3": trackFile(1, "Track", map[string]any{"has_picture": "true"}),
-				"Artist/Album/cover.jpg":      imageFile("external"),
-			})
-			scan()
-			// Swap in real MP3 bytes so libFS.Open returns a taglib-readable stream.
-			replaceWithRealMP3("Artist/Album/01 - Track.mp3")
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(embeddedArtBytes))
-		})
-	})
-
-	When("CoverArtPriority lists external first but no external file is present", func() {
-		// Artist/
-		// └── Album/
-		//     └── 01 - Track.mp3      ← has embedded picture (falls through to "embedded")
-		It("falls through to embedded artwork", func() {
-			conf.Server.CoverArtPriority = "external, embedded"
-			setLayout(fstest.MapFS{
-				"Artist/Album/01 - Track.mp3": trackFile(1, "Track", map[string]any{"has_picture": "true"}),
-			})
-			scan()
-			replaceWithRealMP3("Artist/Album/01 - Track.mp3")
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(embeddedArtBytes))
-		})
-	})
-
-	When("the only cover file uses uppercase extension and a different case in its name", func() {
-		// Artist/
-		// └── Album/
-		//     ├── 01 - Track.mp3
-		//     └── Cover.JPG            ← matched case-insensitively by cover.*
-		It("matches case-insensitively against cover.*", func() {
-			conf.Server.CoverArtPriority = "cover.*, folder.*"
-			setLayout(fstest.MapFS{
-				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
-				"Artist/Album/Cover.JPG":      imageFile("case-insensitive"),
-			})
-			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("case-insensitive")))
-		})
-	})
-
-	When("two cover files have basenames that tie under the natural-sort tiebreaker", func() {
-		// Artist/
-		// └── Album/
-		//     ├── 01 - Track.mp3
-		//     ├── cover.jpg            ← wins (no numeric suffix)
-		//     └── cover.1.jpg
-		It("prefers the file without a numeric suffix", func() {
-			conf.Server.CoverArtPriority = "cover.*"
-			setLayout(fstest.MapFS{
-				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
-				"Artist/Album/cover.jpg":      imageFile("primary"),
-				"Artist/Album/cover.1.jpg":    imageFile("secondary"),
-			})
-			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("primary")))
-		})
-	})
-
-	When("the album has no cover and CoverArtPriority lists only file patterns", func() {
-		// Artist/
-		// └── Album/
-		//     └── 01 - Track.mp3       (no image files — returns ErrUnavailable)
-		It("returns ErrUnavailable", func() {
-			conf.Server.CoverArtPriority = "cover.*, folder.*"
-			setLayout(fstest.MapFS{
-				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
-			})
-			scan()
-
-			al := firstAlbum()
-			_, err := readArtworkOrErr(model.NewArtworkID(model.KindAlbumArtwork, al.ID, &al.UpdatedAt))
-			Expect(err).To(HaveOccurred())
-		})
-	})
-
-	// Doc scenarios from:
-	// https://www.navidrome.org/docs/usage/library/artwork/#albums
-	// Default CoverArtPriority is "cover.*, folder.*, front.*, embedded, external".
-	When("only folder.jpg is present (cover.* and front.* missing)", func() {
-		// Artist/
-		// └── Album/
-		//     ├── 01 - Track.mp3
-		//     └── folder.jpg           ← matched by folder.*
-		It("falls through to folder.jpg", func() {
-			conf.Server.CoverArtPriority = defaultCoverPriority
-			setLayout(fstest.MapFS{
-				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
-				"Artist/Album/folder.jpg":     imageFile("folder"),
-			})
-			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("folder")))
-		})
-	})
-
-	When("only front.jpg is present (cover.* and folder.* missing)", func() {
-		// Artist/
-		// └── Album/
-		//     ├── 01 - Track.mp3
-		//     └── front.jpg            ← matched by front.*
-		It("falls through to front.jpg", func() {
-			conf.Server.CoverArtPriority = defaultCoverPriority
-			setLayout(fstest.MapFS{
-				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
-				"Artist/Album/front.jpg":      imageFile("front"),
-			})
-			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("front")))
-		})
-	})
-
-	When("cover.*, folder.*, and front.* all exist in the same folder", func() {
-		// Artist/
-		// └── Album/
-		//     ├── 01 - Track.mp3
-		//     ├── cover.jpg            ← wins (cover.* is first in priority)
-		//     ├── folder.jpg
-		//     └── front.jpg
-		It("prefers cover.* (first in CoverArtPriority)", func() {
-			conf.Server.CoverArtPriority = defaultCoverPriority
-			setLayout(fstest.MapFS{
-				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
-				"Artist/Album/cover.jpg":      imageFile("cover"),
-				"Artist/Album/folder.jpg":     imageFile("folder"),
-				"Artist/Album/front.jpg":      imageFile("front"),
-			})
-			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("cover")))
-		})
-	})
-
-	When("only folder.* and front.* exist (priority order check)", func() {
-		// Artist/
-		// └── Album/
-		//     ├── 01 - Track.mp3
-		//     ├── folder.jpg           ← wins (folder.* comes before front.*)
-		//     └── front.jpg
-		It("prefers folder.* over front.*", func() {
-			conf.Server.CoverArtPriority = defaultCoverPriority
-			setLayout(fstest.MapFS{
-				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
-				"Artist/Album/folder.jpg":     imageFile("folder"),
-				"Artist/Album/front.jpg":      imageFile("front"),
-			})
-			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("folder")))
-		})
-	})
-
-	When("three cover files tie by basename and differ only by numeric suffix", func() {
-		// Artist/
-		// └── Album/
-		//     ├── 01 - Track.mp3
-		//     ├── cover.jpg            ← wins (no numeric suffix)
-		//     ├── cover.1.jpg
-		//     └── cover.2.jpg
-		It("selects the unsuffixed file first regardless of numeric-suffix order", func() {
-			conf.Server.CoverArtPriority = "cover.*"
-			setLayout(fstest.MapFS{
-				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
-				"Artist/Album/cover.2.jpg":    imageFile("second"),
-				"Artist/Album/cover.jpg":      imageFile("primary"),
-				"Artist/Album/cover.1.jpg":    imageFile("first"),
-			})
-			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("primary")))
-		})
-	})
-
-	When("CoverArtPriority contains an unknown pattern before a matching one", func() {
-		// Artist/
-		// └── Album/
-		//     ├── 01 - Track.mp3
-		//     └── cover.jpg            ← wins (unknown "bogus.*" is skipped)
-		It("skips the unknown pattern and falls through to the matching one", func() {
-			conf.Server.CoverArtPriority = "bogus.*, cover.*"
-			setLayout(fstest.MapFS{
-				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
-				"Artist/Album/cover.jpg":      imageFile("cover"),
-			})
-			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("cover")))
-		})
-	})
-
-	// Regression introduced in v0.62.0 (#5451 + #5457): the parent-folder
-	// fallback can pick up images from the ARTIST folder, serving the artist
-	// thumbnail as album art for any album without its own image files.
-	When("an album has no images and the artist folder has folder.jpg", func() {
-		// Artist/
-		// ├── folder.jpg               ← artist thumbnail, must NOT become album art
-		// ├── Album A/
-		// │   └── 01 - Track.mp3       (no images)
-		// └── Album B/
-		//     ├── 01 - Track.mp3
-		//     └── cover.jpg
-		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/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"),
-			})
-			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")))
-		})
-	})
-
-	When("a single-disc album is spread across sibling folders under the artist folder", func() {
-		// Artist/
-		// ├── folder.jpg               ← artist thumbnail, must NOT become album art
-		// ├── Album A/
-		// │   └── 01 - Track.mp3       (album: "Album A")
-		// ├── Album A bonus/
-		// │   └── 02 - Track.mp3       (album: "Album A" — same album, second folder)
-		// └── Album B/
-		//     ├── 01 - Track.mp3
-		//     └── cover.jpg
-		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/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"),
-			})
-			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")
-		})
-	})
-
-	When("a spread album has its own front.jpg but the artist folder has cover.jpg", func() {
-		// Artist/
-		// ├── cover.jpg                ← artist image; matches cover.* (first pattern),
-		// │                              must NOT shadow the album's own front.jpg
-		// ├── Album A/
-		// │   ├── 01 - Track.mp3       (album: "Album A")
-		// │   └── front.jpg            ← should win
-		// ├── Album A bonus/
-		// │   └── 02 - Track.mp3       (album: "Album A")
-		// └── Album B/
-		//     └── 01 - Track.mp3
-		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/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 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"}),
-			})
-			scan()
-
-			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")))
-		})
-	})
-
-	When("embedded is first in CoverArtPriority but the track has no embedded art", func() {
-		// Artist/
-		// └── Album/
-		//     ├── 01 - Track.mp3       (no embedded picture)
-		//     └── cover.jpg            ← wins (embedded skipped, falls through)
-		It("falls through to the next priority entry", func() {
-			conf.Server.CoverArtPriority = "embedded, cover.*"
-			setLayout(fstest.MapFS{
-				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
-				"Artist/Album/cover.jpg":      imageFile("cover"),
-			})
-			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("cover")))
-		})
-	})
-})

core/artwork/e2e/artist_test.go

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

core/artwork/e2e/disc_test.go

@@ -1,371 +0,0 @@
-package artworke2e_test
-
-import (
-	"fmt"
-	"testing/fstest"
-
-	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/model"
-	. "github.com/onsi/ginkgo/v2"
-	. "github.com/onsi/gomega"
-)
-
-var _ = Describe("Disc artwork resolution", func() {
-	BeforeEach(func() {
-		setupHarness()
-	})
-
-	When("the album is single-disc with a disc1.jpg in the only folder", func() {
-		// Artist/
-		// └── Album/
-		//     ├── 01 - Track.mp3
-		//     └── disc1.jpg            ← matched by disc*.*
-		It("returns the disc1.jpg image (matched as disc*.*)", func() {
-			conf.Server.DiscArtPriority = "disc*.*, cd*.*, cover.*, folder.*, front.*, embedded"
-			setLayout(fstest.MapFS{
-				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
-				"Artist/Album/disc1.jpg":      imageFile("disc1-image"),
-			})
-			scan()
-
-			al := firstAlbum()
-			discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, 1), &al.UpdatedAt)
-			Expect(readArtwork(discID)).To(Equal(imageBytes("disc1-image")))
-		})
-	})
-
-	When("the album has no per-disc image and no album cover", func() {
-		// Artist/
-		// └── Album/
-		//     └── 01 - Track.mp3       (no disc or album art — returns ErrUnavailable)
-		It("returns ErrUnavailable for the disc lookup", func() {
-			conf.Server.DiscArtPriority = "disc*.*, cd*.*"
-			conf.Server.CoverArtPriority = "cover.*, folder.*"
-			setLayout(fstest.MapFS{
-				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
-			})
-			scan()
-
-			al := firstAlbum()
-			discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, 1), &al.UpdatedAt)
-			_, err := readArtworkOrErr(discID)
-			Expect(err).To(HaveOccurred())
-		})
-	})
-
-	When("the album has no per-disc image but has an album cover", func() {
-		// Artist/
-		// └── Album/
-		//     ├── 01 - Track.mp3
-		//     └── cover.jpg            ← album-level fallback (no disc art present)
-		It("falls back to the album cover", func() {
-			conf.Server.DiscArtPriority = "disc*.*, cd*.*"
-			conf.Server.CoverArtPriority = defaultCoverPriority
-			setLayout(fstest.MapFS{
-				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
-				"Artist/Album/cover.jpg":      imageFile("album-cover"),
-			})
-			scan()
-
-			al := firstAlbum()
-			discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, 1), &al.UpdatedAt)
-			Expect(readArtwork(discID)).To(Equal(imageBytes("album-cover")))
-		})
-	})
-
-	When("multiple disc images exist in the same folder (disc1 vs disc10)", func() {
-		// Artist/
-		// └── Album/
-		//     ├── 01 - Track.mp3
-		//     ├── disc1.jpg            ← matches request for disc 1
-		//     └── disc10.jpg
-		It("matches the requested disc number, not a higher-numbered one", func() {
-			conf.Server.DiscArtPriority = "disc*.*"
-			setLayout(fstest.MapFS{
-				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
-				"Artist/Album/disc1.jpg":      imageFile("disc-one"),
-				"Artist/Album/disc10.jpg":     imageFile("disc-ten"),
-			})
-			scan()
-
-			al := firstAlbum()
-			discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, 1), &al.UpdatedAt)
-			Expect(readArtwork(discID)).To(Equal(imageBytes("disc-one")))
-		})
-	})
-
-	When("a multi-disc album has per-disc covers", func() {
-		// Artist/
-		// └── Album/
-		//     ├── CD1/
-		//     │   ├── 01 - Track.mp3
-		//     │   └── disc1.jpg        ← matches request for disc 1
-		//     └── CD2/
-		//         ├── 01 - Track.mp3
-		//         └── disc2.jpg        ← matches request for disc 2
-		It("returns the requested disc's image", func() {
-			conf.Server.DiscArtPriority = "disc*.*"
-			setLayout(fstest.MapFS{
-				"Artist/Album/CD1/01 - Track.mp3": trackFile(1, "T1", map[string]any{"disc": "1"}),
-				"Artist/Album/CD2/01 - Track.mp3": trackFile(1, "T2", map[string]any{"disc": "2"}),
-				"Artist/Album/CD1/disc1.jpg":      imageFile("disc-1"),
-				"Artist/Album/CD2/disc2.jpg":      imageFile("disc-2"),
-			})
-			scan()
-
-			al := firstAlbum()
-			discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, 2), &al.UpdatedAt)
-			Expect(readArtwork(discID)).To(Equal(imageBytes("disc-2")))
-		})
-	})
-
-	// Doc scenarios from:
-	// https://www.navidrome.org/docs/usage/library/artwork/#disc-cover-art
-	// Default DiscArtPriority is "disc*.*, cd*.*, cover.*, folder.*, front.*, discsubtitle, embedded".
-	When("a disc subfolder has a cd2.png image", func() {
-		// Artist/
-		// └── Album/
-		//     ├── CD1/
-		//     │   ├── 01 - Track.mp3
-		//     │   └── disc1.jpg
-		//     └── CD2/
-		//         ├── 01 - Track.mp3
-		//         └── cd2.png          ← matched by cd*.* for disc 2
-		It("matches via the cd*.* pattern", func() {
-			conf.Server.DiscArtPriority = defaultDiscPriority
-			setLayout(fstest.MapFS{
-				"Artist/Album/CD1/01 - Track.mp3": trackFile(1, "T1", map[string]any{"disc": "1"}),
-				"Artist/Album/CD2/01 - Track.mp3": trackFile(1, "T2", map[string]any{"disc": "2"}),
-				"Artist/Album/CD1/disc1.jpg":      imageFile("disc-1"),
-				"Artist/Album/CD2/cd2.png":        imageFile("cd-2"),
-			})
-			scan()
-
-			al := firstAlbum()
-			discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, 2), &al.UpdatedAt)
-			Expect(readArtwork(discID)).To(Equal(imageBytes("cd-2")))
-		})
-	})
-
-	When("a disc subfolder has cover.jpg but no disc*.*/cd*.* image", func() {
-		// Artist/
-		// └── Album/
-		//     ├── CD1/
-		//     │   ├── 01 - Track.mp3
-		//     │   └── cover.jpg        ← matched by cover.* inside disc folder
-		//     └── CD2/
-		//         ├── 01 - Track.mp3
-		//         └── cover.jpg
-		It("falls through to cover.* inside the disc folder", func() {
-			conf.Server.DiscArtPriority = defaultDiscPriority
-			setLayout(fstest.MapFS{
-				"Artist/Album/CD1/01 - Track.mp3": trackFile(1, "T1", map[string]any{"disc": "1"}),
-				"Artist/Album/CD2/01 - Track.mp3": trackFile(1, "T2", map[string]any{"disc": "2"}),
-				"Artist/Album/CD1/cover.jpg":      imageFile("disc1-cover"),
-				"Artist/Album/CD2/cover.jpg":      imageFile("disc2-cover"),
-			})
-			scan()
-
-			al := firstAlbum()
-			discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, 1), &al.UpdatedAt)
-			Expect(readArtwork(discID)).To(Equal(imageBytes("disc1-cover")))
-		})
-	})
-
-	When("DiscArtPriority is the empty string", func() {
-		// Artist/
-		// └── Album/
-		//     ├── CD1/
-		//     │   ├── 01 - Track.mp3
-		//     │   └── disc1.jpg        (ignored — DiscArtPriority is empty)
-		//     ├── CD2/
-		//     │   ├── 01 - Track.mp3
-		//     │   └── cd2.png          (ignored — DiscArtPriority is empty)
-		//     └── cover.jpg            ← used for every disc (album-level fallback)
-		It("skips every disc-level source and returns the album cover", func() {
-			conf.Server.DiscArtPriority = ""
-			conf.Server.CoverArtPriority = defaultCoverPriority
-			setLayout(fstest.MapFS{
-				"Artist/Album/CD1/01 - Track.mp3": trackFile(1, "T1", map[string]any{"disc": "1"}),
-				"Artist/Album/CD2/01 - Track.mp3": trackFile(1, "T2", map[string]any{"disc": "2"}),
-				"Artist/Album/CD1/disc1.jpg":      imageFile("disc-1"),
-				"Artist/Album/CD2/cd2.png":        imageFile("cd-2"),
-				"Artist/Album/cover.jpg":          imageFile("album-cover"),
-			})
-			scan()
-
-			al := firstAlbum()
-			for _, n := range []int{1, 2} {
-				discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, n), &al.UpdatedAt)
-				Expect(readArtwork(discID)).To(Equal(imageBytes("album-cover")),
-					"disc %d should use the album cover when DiscArtPriority is empty", n)
-			}
-		})
-	})
-
-	When("the documented multi-disc layout is used (disc1.jpg + cd2.png + album-root cover.jpg)", func() {
-		// Artist/
-		// └── Album/
-		//     ├── disc1/
-		//     │   ├── disc1.jpg        ← matched by disc*.* for disc 1
-		//     │   ├── 01 - Track.mp3
-		//     │   └── 02 - Track.mp3
-		//     ├── disc2/
-		//     │   ├── cd2.png          ← matched by cd*.* for disc 2
-		//     │   ├── 01 - Track.mp3
-		//     │   └── 02 - Track.mp3
-		//     └── cover.jpg            (album-level fallback, unused here)
-		It("matches the per-disc image for each disc", func() {
-			conf.Server.DiscArtPriority = defaultDiscPriority
-			conf.Server.CoverArtPriority = defaultCoverPriority
-			setLayout(fstest.MapFS{
-				"Artist/Album/disc1/01 - Track.mp3": trackFile(1, "T1", map[string]any{"disc": "1"}),
-				"Artist/Album/disc1/02 - Track.mp3": trackFile(2, "T2", map[string]any{"disc": "1"}),
-				"Artist/Album/disc2/01 - Track.mp3": trackFile(1, "T3", map[string]any{"disc": "2"}),
-				"Artist/Album/disc2/02 - Track.mp3": trackFile(2, "T4", map[string]any{"disc": "2"}),
-				"Artist/Album/disc1/disc1.jpg":      imageFile("disc-1"),
-				"Artist/Album/disc2/cd2.png":        imageFile("cd-2"),
-				"Artist/Album/cover.jpg":            imageFile("album-root"),
-			})
-			scan()
-
-			al := firstAlbum()
-			disc1ID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, 1), &al.UpdatedAt)
-			disc2ID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, 2), &al.UpdatedAt)
-			Expect(readArtwork(disc1ID)).To(Equal(imageBytes("disc-1")))
-			Expect(readArtwork(disc2ID)).To(Equal(imageBytes("cd-2")))
-		})
-	})
-
-	When("discsubtitle keyword matches an image whose stem equals the disc's subtitle", func() {
-		// Artist/
-		// └── Album/
-		//     ├── 01 - Track.mp3       (discsubtitle="Bonus Tracks")
-		//     └── Bonus Tracks.jpg     ← matched by "discsubtitle" keyword
-		It("selects the subtitle-named image", func() {
-			conf.Server.DiscArtPriority = "discsubtitle"
-			setLayout(fstest.MapFS{
-				"Artist/Album/01 - Track.mp3":   trackFile(1, "T1", map[string]any{"disc": "1", "discsubtitle": "Bonus Tracks"}),
-				"Artist/Album/Bonus Tracks.jpg": imageFile("bonus-tracks"),
-			})
-			scan()
-
-			al := firstAlbum()
-			discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, 1), &al.UpdatedAt)
-			Expect(readArtwork(discID)).To(Equal(imageBytes("bonus-tracks")))
-		})
-	})
-
-	// Reproduces https://github.com/navidrome/navidrome/issues/5456
-	// Deeply nested layout matching the reporter's actual structure.
-	When("a deeply nested multi-disc album has cover.jpg and per-disc folder.jpg", func() {
-		// Genre/Artist/Album/                 ← album root with cover.jpg
-		// ├── cover.jpg                       ← album-level cover
-		// ├── Disc 01 (Subtitle)/
-		// │   ├── 01 - Track.mp3
-		// │   └── folder.jpg                  ← disc 1 art
-		// ├── Disc 02 (Subtitle)/
-		// │   ├── 01 - Track.mp3
-		// │   └── folder.jpg
-		// └── ... (12 discs)
-		It("uses album-root cover.jpg for album art and per-disc folder.jpg for each disc", func() {
-			conf.Server.DiscArtPriority = defaultDiscPriority
-			conf.Server.CoverArtPriority = defaultCoverPriority
-			discNames := []string{
-				"Disc 01 (Birth of the Dead - The Studio Sides)",
-				"Disc 02 (Birth of the Dead - The Live Sides)",
-				"Disc 03 (The Grateful Dead)",
-				"Disc 04 (Anthem of the Sun)",
-				"Disc 05 (Aoxomoxoa)",
-				"Disc 06 (Live; Dead)",
-				"Disc 07 (Workingman's Dead)",
-				"Disc 08 (American Beauty)",
-				"Disc 09 (Grateful Dead)",
-				"Disc 10 (Europe '72)",
-				"Disc 11 (Europe '72)",
-				"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"),
-			}
-			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))
-			}
-			setLayout(layout)
-			scan()
-
-			al := firstAlbum()
-
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("album-root-cover")))
-
-			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)
-			}
-		})
-	})
-
-	// https://github.com/navidrome/navidrome/issues/5456
-	// Top-level album variant — album folder at library root (Path=".").
-	When("a top-level multi-disc album has cover.jpg and per-disc folder.jpg", func() {
-		// Album/                       (top-level, Path=".")
-		// ├── cover.jpg                ← album-level cover
-		// ├── Disc 01/
-		// │   ├── 01 - Track.mp3
-		// │   └── folder.jpg           ← disc 1 art
-		// ├── Disc 02/
-		// │   ├── 01 - Track.mp3
-		// │   └── folder.jpg
-		// └── Disc 03/
-		//     ├── 01 - Track.mp3
-		//     └── folder.jpg
-		It("uses album-root cover.jpg for album art and per-disc folder.jpg for each disc", func() {
-			conf.Server.DiscArtPriority = defaultDiscPriority
-			conf.Server.CoverArtPriority = defaultCoverPriority
-			layout := fstest.MapFS{
-				"Album/cover.jpg": imageFile("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))
-			}
-			setLayout(layout)
-			scan()
-
-			al := firstAlbum()
-
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("album-root-cover")))
-
-			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)
-			}
-		})
-	})
-
-	When("discsubtitle is set but no image filename matches the subtitle", func() {
-		// Artist/
-		// └── Album/
-		//     ├── 01 - Track.mp3       (discsubtitle="Bonus Tracks")
-		//     └── cover.jpg            ← wins (discsubtitle has no match, falls through)
-		It("falls through to the next priority entry", func() {
-			conf.Server.DiscArtPriority = "discsubtitle, cover.*"
-			setLayout(fstest.MapFS{
-				"Artist/Album/01 - Track.mp3": trackFile(1, "T1", map[string]any{"disc": "1", "discsubtitle": "Bonus Tracks"}),
-				"Artist/Album/cover.jpg":      imageFile("cover"),
-			})
-			scan()
-
-			al := firstAlbum()
-			discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, 1), &al.UpdatedAt)
-			Expect(readArtwork(discID)).To(Equal(imageBytes("cover")))
-		})
-	})
-})

core/artwork/e2e/e2e_suite_test.go

@@ -0,0 +1,92 @@
+// Package e2e exercises the artwork pipeline end to end: it enqueues real entities, drives the
+// real Worker to drain the queue, and serves the result through the real Service, 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"
+)
+
+// readFixture returns the raw bytes of a project-relative fixture file.
+func readFixture(rel string) []byte {
+	GinkgoHelper()
+	data, err := os.ReadFile(rel)
+	Expect(err).ToNot(HaveOccurred(), "reading fixture %q", rel)
+	return data
+}
+
+// readAll drains an artwork image to bytes and closes it.
+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
+}
+
+// runWorkerUntil starts the real worker loop, waits for a condition, then cancels and joins it,
+// mirroring how cmd drives Worker.Run in production.
+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()))
+}
+
+// fakeFolderRepo is the minimal FolderRepository the album/playlist resolution chains touch:
+// GetAll yields the seeded folders and the album-root parent lookup finds nothing.
+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 }
+
+// writeUpload copies a fixture into the per-entity upload folder under the data dir and returns
+// the bare filename UploadedImagePath expects.
+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
+}

core/artwork/e2e/helpers_test.go

@@ -1,187 +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, int) (model.MediaFiles, error) {
-	return nil, nil
-}
-func (n *noopProvider) ArtistImage(context.Context, string) (*url.URL, error) {
-	return nil, model.ErrNotFound
-}
-func (n *noopProvider) ArtistImageResult(context.Context, string) (*url.URL, error) {
-	return nil, model.ErrNotFound
-}
-func (n *noopProvider) AlbumImage(context.Context, string) (*url.URL, error) {
-	return nil, model.ErrNotFound
-}
-
-var _ external.Provider = (*noopProvider)(nil)

core/artwork/e2e/mediafile_test.go

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

core/artwork/e2e/playlist_test.go

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

core/artwork/e2e/radio_test.go

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

core/artwork/e2e/suite_test.go

@@ -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{}
-}

core/artwork/folders_album.go

@@ -3,106 +3,18 @@ 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"
 )
 
-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, albums ...model.Album) ([]string, []string, *time.Time, error) {
 	var folderIDs []string
 	for _, album := range albums {

core/artwork/folders_artist.go

@@ -2,7 +2,6 @@ package artwork
 
 import (
 	"context"
-	"crypto/md5"
 	"fmt"
 	"io"
 	"io/fs"
@@ -14,9 +13,7 @@ import (
 	"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/str"
@@ -28,127 +25,6 @@ const (
 	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 := loadAlbumFoldersPaths(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 {
@@ -262,29 +138,6 @@ func loadArtistFolder(ctx context.Context, ds model.DataStore, albums model.Albu
 	return folderPath, folders[0].ImagesUpdatedAt, nil
 }
 
-func (a *artistReader) fromArtistImageFolder(ctx context.Context) sourceFunc {
-	return func() (io.ReadCloser, string, error) {
-		folder := conf.Server.ArtistImageFolder
-		if folder == "" {
-			return nil, "", nil
-		}
-		// Use cached path from newArtistArtworkReader if available,
-		// avoiding a second directory scan.
-		path := a.imgFolderImgPath
-		if path == "" {
-			path = findImageInArtistFolder(folder, a.artist.MbzArtistID, a.artist.Name)
-		}
-		if path == "" {
-			return nil, "", fmt.Errorf("no image found for artist %q in %s", a.artist.Name, folder)
-		}
-		f, err := os.Open(path)
-		if err != nil {
-			return nil, "", err
-		}
-		return f, path, nil
-	}
-}
-
 // findImageInArtistFolder scans a folder for an image file matching the artist's MBID or name
 // (case-insensitive). Returns the full path, or empty string if not found.
 func findImageInArtistFolder(folder, mbzArtistID, artistName string) string {

core/artwork/image_cache.go

@@ -2,29 +2,21 @@ package artwork
 
 import (
 	"context"
-	"fmt"
 	"io"
 	"time"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
-	"github.com/navidrome/navidrome/model"
 	"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
+	LastUpdated() time.Time
+	Reader(ctx context.Context) (io.ReadCloser, string, error)
 }
 
 type imageCache struct {

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
 }

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())

core/artwork/playlist_cover.go

@@ -0,0 +1,86 @@
+package artwork
+
+import (
+	"context"
+	"image"
+	"image/draw"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+	xdraw "golang.org/x/image/draw"
+)
+
+const tileSize = 600
+
+// 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 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
+}

core/artwork/processor.go

@@ -10,11 +10,12 @@ import (
 	"io"
 	"time"
 
+	"github.com/navidrome/navidrome/core/agents"
 	"github.com/navidrome/navidrome/core/artwork/blurhash"
-	"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/cache"
 	xdraw "golang.org/x/image/draw"
 )
 
@@ -42,14 +43,15 @@ const maxImageBytes = 20 << 20
 // huge canvas that image.Decode would expand into gigabytes (decompression bomb).
 const maxImagePixels = 64 << 20
 
-// workerDeps are the collaborators processItem needs; extGate is set by NewWorker in
+// workerDeps are the collaborators processItem needs; gate is set by NewWorker in
 // production and nil only in tests, where resolveItem falls back to a plain passthrough.
 type workerDeps struct {
-	ds      model.DataStore
-	store   *ImageStore
-	prov    external.Provider
-	ffmpeg  ffmpeg.FFmpeg
-	extGate extGateFunc
+	ds     model.DataStore
+	store  *ImageStore
+	agents *agents.Agents
+	ffmpeg ffmpeg.FFmpeg
+	cache  cache.FileCache
+	gate   gateFunc
 }
 
 // processItem resolves one queue item end to end: find an image, hash/decode/
@@ -57,7 +59,7 @@ type workerDeps struct {
 func processItem(ctx context.Context, deps *workerDeps, item model.ArtworkQueueItem) outcome {
 	repo := deps.ds.Artwork(ctx)
 
-	res, err := resolveItem(ctx, deps.ds, deps.prov, deps.ffmpeg, item, deps.extGate)
+	res, err := resolveItem(ctx, deps.ds, deps.agents, deps.ffmpeg, item, deps.gate)
 	if err != nil {
 		log.Warn(ctx, "artwork: could not resolve item", "kind", item.ItemKind, "id", item.ItemID, err)
 		return outcomeFailed

core/artwork/processor_test.go

@@ -5,13 +5,15 @@ import (
 	"encoding/binary"
 	"errors"
 	"hash/crc32"
-	"net/url"
+	"net/http"
+	"net/http/httptest"
 	"os"
 	"path/filepath"
 	"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"
@@ -40,7 +42,7 @@ var _ = Describe("processItem", func() {
 		folderRepo *fakeFolderRepo
 		libRepo    *tests.MockLibraryRepo
 		ffm        *tests.MockFFmpeg
-		prov       *fakeExternalProvider
+		ag         *agents.Agents
 		store      *ImageStore
 		artRepo    *tests.MockArtworkRepo
 		repoRoot   string
@@ -58,7 +60,7 @@ var _ = Describe("processItem", func() {
 		libRepo = &tests.MockLibraryRepo{}
 		libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(repoRoot)}})
 		ffm = tests.NewMockFFmpeg("")
-		prov = &fakeExternalProvider{}
+		ag = agents.GetAgents(&tests.MockDataStore{}, nil)
 		artRepo = tests.CreateMockArtworkRepo()
 		ds = &tests.MockDataStore{
 			MockedFolder:  folderRepo,
@@ -67,7 +69,7 @@ var _ = Describe("processItem", func() {
 		}
 		ds.MockedAlbum = tests.CreateMockAlbumRepo()
 		store = NewImageStore(GinkgoT().TempDir())
-		deps = &workerDeps{ds: ds, store: store, prov: prov, ffmpeg: ffm}
+		deps = &workerDeps{ds: ds, store: store, agents: ag, ffmpeg: ffm}
 
 		conf.Server.CoverArtPriority = "cover.jpg, embedded"
 	})
@@ -141,9 +143,7 @@ var _ = Describe("processItem", func() {
 		ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
 			{ID: "al4", Name: "Album"},
 		})
-		prov.albumImage = func(context.Context, string) (*url.URL, error) {
-			return nil, errors.New("agent timed out")
-		}
+		imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
 
 		out := processItem(ctx, deps, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al4"})
 		Expect(out).To(Equal(outcomeFailed))
@@ -161,9 +161,7 @@ var _ = Describe("processItem", func() {
 		ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
 			{ID: "alstale", Name: "Album", FolderIDs: []string{"f1"}},
 		})
-		prov.albumImage = func(context.Context, string) (*url.URL, error) {
-			return nil, errors.New("agent timed out")
-		}
+		imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
 
 		out := processItem(ctx, deps, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alstale"})
 		Expect(out).To(Equal(outcomeFoundStale))
@@ -174,6 +172,34 @@ var _ = Describe("processItem", func() {
 		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 := processItem(ctx, deps, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alext"})
+		Expect(out).To(Equal(outcomeFound))
+
+		ia, err := artRepo.GetItemArtwork("al", "alext", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(ia.Source).To(Equal("external:deezerFake"))
+		Expect(ia.Hash).ToNot(BeEmpty())
+
+		// External art is content-addressed into the store, not file-backed.
+		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",
@@ -231,7 +257,7 @@ var _ = Describe("processItem", func() {
 		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(int64(1000)))
+		Expect(iaA.RefMtime).To(Equal(time.Unix(1000, 0).UnixNano()))
 
 		// Poison the shared row's blurhash: the second item must dedup on hash, not re-decode.
 		poisoned := artRepo.Data[iaA.Hash]
@@ -244,13 +270,13 @@ var _ = Describe("processItem", func() {
 		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(int64(2000)))
+		Expect(iaB.RefMtime).To(Equal(time.Unix(2000, 0).UnixNano()))
 
 		// The first item's provenance survives the second item processing identical bytes.
 		iaAafter, err := artRepo.GetItemArtwork("al", "alA", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(filepath.ToSlash(iaAafter.SourcePath)).To(HaveSuffix("album-a/cover.jpg"))
-		Expect(iaAafter.RefMtime).To(Equal(int64(1000)))
+		Expect(iaAafter.RefMtime).To(Equal(time.Unix(1000, 0).UnixNano()))
 
 		// One shared artwork row, and dedup preserved it untouched.
 		Expect(artRepo.Data).To(HaveLen(1))

core/artwork/reader_album_test.go

@@ -1,454 +0,0 @@
-package artwork
-
-import (
-	"context"
-	"errors"
-	"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("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))
-		})
-	})
-})

core/artwork/reader_artist_test.go

@@ -1,748 +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("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
-	}
-}

core/artwork/reader_mediafile.go

@@ -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...)
-}

core/artwork/reader_playlist.go

@@ -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
-}

core/artwork/reader_radio.go

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

core/artwork/reader_radio_test.go

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

core/artwork/reader_resized_test.go

@@ -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
-}

core/artwork/resize.go

@@ -10,12 +10,11 @@ import (
 	"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"
-	"github.com/navidrome/navidrome/model"
 	xdraw "golang.org/x/image/draw"
 )
 
@@ -41,84 +40,14 @@ var bufPool = sync.Pool{
 	},
 }
 
-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)
-	}
-
+// 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) {
 	// Preserve animation for animated images
 	if isAnimatedGIF(data) {
-		if a.a.ffmpeg.IsAvailable() {
+		if ffm.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)
+			r, err := ffm.ConvertAnimatedImage(ctx, bytes.NewReader(data), size, conf.Server.CoverArtQuality)
 			if err == nil {
 				return r, 0, nil
 			}
@@ -129,7 +58,7 @@ func (a *resizedArtworkReader) resizeImage(ctx context.Context, reader io.Reader
 		return bytes.NewReader(data), 0, nil
 	}
 
-	return resizeStaticImage(data, a.size, a.square)
+	return resizeStaticImage(data, size, square)
 }
 
 // toFastScaleType converts images whose concrete type has no optimized scaler
@@ -207,3 +136,12 @@ func resizeStaticImage(data []byte, size int, square bool) (io.Reader, int, erro
 	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)
+}

core/artwork/resolve.go

@@ -19,7 +19,7 @@ import (
 	"github.com/Masterminds/squirrel"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
-	"github.com/navidrome/navidrome/core/external"
+	"github.com/navidrome/navidrome/core/agents"
 	"github.com/navidrome/navidrome/core/ffmpeg"
 	"github.com/navidrome/navidrome/model"
 )
@@ -29,34 +29,38 @@ 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         // mtime of sourcePath at resolution time; 0 when no sourcePath
+	refMtime   int64         // sourcePath mtime (unix-nanoseconds) at resolution; 0 when no sourcePath
 	// external source errored/timed out. With no reader: forces failed (never absent).
 	// On a hit: a higher-priority external step failed—serve this, but retry later.
 	extError bool
 }
 
-// extGateFunc is an alias for the external-step wrapper the worker injects (rate
-// limiter + circuit breaker); resolveItem defaults to a plain passthrough.
-type extGateFunc = func(func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error)
-
-func passthroughExtGate(f func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error) {
-	return f()
+// resolveItem walks the kind's priority chain and returns the first hit.
+func resolveItem(ctx context.Context, ds model.DataStore, ag *agents.Agents, ffmpeg ffmpeg.FFmpeg, item model.ArtworkQueueItem, gate gateFunc) (resolution, error) {
+	return resolveItemMode(ctx, ds, ag, ffmpeg, item, gate, false)
 }
 
-// resolveItem walks the kind's priority chain and returns the first hit.
-func resolveItem(ctx context.Context, ds model.DataStore, prov external.Provider, ffmpeg ffmpeg.FFmpeg, item model.ArtworkQueueItem, extGate extGateFunc) (resolution, error) {
-	if extGate == nil {
-		extGate = passthroughExtGate
+// resolveItemLocal resolves using only local sources for the serving path's provisional
+// read-through: external steps are skipped and the worker-built playlist grid is not assembled.
+func resolveItemLocal(ctx context.Context, ds model.DataStore, ffmpeg ffmpeg.FFmpeg, item model.ArtworkQueueItem) (resolution, error) {
+	return resolveItemMode(ctx, ds, nil, ffmpeg, item, denyGate, true)
+}
+
+func resolveItemMode(ctx context.Context, ds model.DataStore, ag *agents.Agents, ffmpeg ffmpeg.FFmpeg, item model.ArtworkQueueItem, gate gateFunc, localOnly bool) (resolution, error) {
+	if gate == nil {
+		gate = passthroughGate
 	}
 	switch item.ItemKind {
 	case "al":
-		return resolveAlbum(ctx, ds, prov, ffmpeg, item.ItemID, extGate)
+		return resolveAlbum(ctx, ds, ag, ffmpeg, item.ItemID, gate, localOnly)
 	case "ar":
-		return resolveArtist(ctx, ds, prov, ffmpeg, item.ItemID, extGate)
+		return resolveArtist(ctx, ds, ag, ffmpeg, item.ItemID, gate, localOnly)
 	case "pl":
-		return resolvePlaylist(ctx, ds, prov, ffmpeg, item.ItemID, extGate)
+		return resolvePlaylist(ctx, ds, ag, ffmpeg, item.ItemID, gate, localOnly)
 	case "ra":
 		return resolveRadio(ctx, ds, item.ItemID)
+	case "mf":
+		return resolveMediaFile(ctx, ds, ffmpeg, item.ItemID)
 	default:
 		return resolution{}, fmt.Errorf("resolveItem: kind %q is not resolvable by the worker", item.ItemKind)
 	}
@@ -64,7 +68,7 @@ func resolveItem(ctx context.Context, ds model.DataStore, prov external.Provider
 
 // resolveAlbum ports the folder/embedded/external selection from
 // reader_album.go, walking conf.Server.CoverArtPriority.
-func resolveAlbum(ctx context.Context, ds model.DataStore, prov external.Provider, ffm ffmpeg.FFmpeg, albumID string, extGate extGateFunc) (resolution, error) {
+func resolveAlbum(ctx context.Context, ds model.DataStore, ag *agents.Agents, ffm ffmpeg.FFmpeg, albumID string, gate gateFunc, localOnly bool) (resolution, error) {
 	al, err := ds.Album(ctx).Get(albumID)
 	if err != nil {
 		return resolution{}, err
@@ -88,8 +92,11 @@ func resolveAlbum(ctx context.Context, ds model.DataStore, prov external.Provide
 				return res, nil
 			}
 		case pattern == "external":
-			if res, ok, isErr := resolveExternalStep(extGate, fromAlbumExternalSource(ctx, *al, prov)); ok {
-				return res, nil
+			if localOnly {
+				continue
+			}
+			if r, name, isErr := fetchAlbumImage(ctx, ag, gate, *al); r != nil {
+				return resolution{reader: r, source: "external:" + name}, nil
 			} else if isErr {
 				extErr = true
 			}
@@ -105,7 +112,7 @@ func resolveAlbum(ctx context.Context, ds model.DataStore, prov external.Provide
 
 // resolveArtist ports the upload/folder/external selection from
 // reader_artist.go: upload always wins, then conf.Server.ArtistArtPriority.
-func resolveArtist(ctx context.Context, ds model.DataStore, prov external.Provider, ffm ffmpeg.FFmpeg, artistID string, extGate extGateFunc) (resolution, error) {
+func resolveArtist(ctx context.Context, ds model.DataStore, ag *agents.Agents, ffm ffmpeg.FFmpeg, artistID string, gate gateFunc, localOnly bool) (resolution, error) {
 	ar, err := ds.Artist(ctx).Get(artistID)
 	if err != nil {
 		return resolution{}, err
@@ -145,8 +152,11 @@ func resolveArtist(ctx context.Context, ds model.DataStore, prov external.Provid
 		pattern = strings.TrimSpace(pattern)
 		switch {
 		case pattern == "external":
-			if res, ok, isErr := resolveExternalStep(extGate, fromArtistExternalResult(ctx, *ar, prov)); ok {
-				return res, nil
+			if localOnly {
+				continue
+			}
+			if r, name, isErr := fetchArtistImage(ctx, ag, gate, *ar); r != nil {
+				return resolution{reader: r, source: "external:" + name}, nil
 			} else if isErr {
 				extErr = true
 			}
@@ -178,7 +188,7 @@ func resolveArtist(ctx context.Context, ds model.DataStore, prov external.Provid
 
 // resolvePlaylist ports reader_playlist.go's chain: uploaded image, sidecar,
 // ExternalImageURL, then the generated 2x2 grid sourced through resolveAlbum.
-func resolvePlaylist(ctx context.Context, ds model.DataStore, prov external.Provider, ffm ffmpeg.FFmpeg, playlistID string, extGate extGateFunc) (resolution, error) {
+func resolvePlaylist(ctx context.Context, ds model.DataStore, ag *agents.Agents, ffm ffmpeg.FFmpeg, playlistID string, gate gateFunc, localOnly bool) (resolution, error) {
 	pl, err := ds.Playlist(ctx).Get(playlistID)
 	if err != nil {
 		return resolution{}, err
@@ -191,10 +201,26 @@ func resolvePlaylist(ctx context.Context, ds model.DataStore, prov external.Prov
 	if res, ok := resolveLocalFile(findPlaylistSidecarPath(ctx, pl.Path), "folder"); ok {
 		return res, nil
 	}
-	if res, ok, isErr := resolveExternalStep(extGate, fromPlaylistExternalSource(ctx, *pl)); ok {
-		return res, nil
-	} else if isErr {
-		extErr = true
+	// A local ExternalImageURL is a file-backed reference: serve it in place (staleness-checked,
+	// and available even on the request path). Only http(s) URLs need the gated remote fetch.
+	localImg, remoteImg := classifyPlaylistImage(pl.ExternalImageURL)
+	if localImg != "" {
+		if res, ok := resolveLocalFile(localImg, "folder"); ok {
+			return res, nil
+		}
+	}
+	if localOnly {
+		// The remote ExternalImageURL fetch and the 2x2 grid are worker-only; a request must
+		// not fetch remotely nor sample album art synchronously.
+		return resolution{}, nil
+	}
+	if remoteImg != nil && conf.Server.EnableM3UExternalAlbumArt {
+		sf := func() (io.ReadCloser, string, error) { return fetchPlaylistImageURL(ctx, remoteImg) }
+		if res, ok, isErr := resolveExternalStep(gate, "m3u", sf); ok {
+			return res, nil
+		} else if isErr {
+			extErr = true
+		}
 	}
 
 	albumIDs, err := ds.Playlist(ctx).Tracks(pl.ID, false).GetAlbumIDs(model.QueryOptions{Max: 4, Sort: "random()"})
@@ -205,7 +231,7 @@ func resolvePlaylist(ctx context.Context, ds model.DataStore, prov external.Prov
 	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 := resolveAlbum(ctx, ds, prov, ffm, albumID, extGate)
+		res, err := resolveAlbum(ctx, ds, ag, ffm, albumID, gate, false)
 		if err != nil {
 			if tileErr == nil {
 				tileErr = err
@@ -259,39 +285,52 @@ func resolveRadio(ctx context.Context, ds model.DataStore, radioID string) (reso
 	return res, nil
 }
 
-// resolveExternalStep runs an external sourceFunc through extGate, shared by
-// resolveAlbum and resolveArtist. ok reports a hit; extErr reports a
-// non-not-found error (a not-found is a definitive "no", not a failure).
-func resolveExternalStep(extGate extGateFunc, sf func() (io.ReadCloser, string, error)) (res resolution, ok bool, extErr bool) {
-	r, path, err := extGate(sf)
+// resolveMediaFile resolves a track's own embedded art only; there is no folder or
+// external fallback, so disabled/missing cover art is a definitive absent.
+func resolveMediaFile(ctx context.Context, ds model.DataStore, ffm ffmpeg.FFmpeg, id string) (resolution, error) {
+	mf, err := ds.MediaFile(ctx).Get(id)
+	if err != nil {
+		return resolution{}, err
+	}
+	if !conf.Server.EnableMediaFileCoverArt || !mf.HasCoverArt {
+		return resolution{}, nil
+	}
+	lib, err := loadLibraryView(ctx, ds, mf.LibraryID)
+	if err != nil {
+		return resolution{}, err
+	}
+	res, _ := resolveEmbedded(ctx, lib, ffm, mf.Path)
+	return res, nil
+}
+
+// resolveExternalStep runs a single external sourceFunc through the named gate; used by
+// the playlist ExternalImageURL step. ok reports a hit; extErr reports a non-not-found
+// error (a not-found is a definitive "no", not 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)
 }
 
-// fromPlaylistExternalSource mirrors reader_playlist.go's ExternalImageURL step:
-// a remote URL (gated) when M3U external art is enabled, else a local file path.
-func fromPlaylistExternalSource(ctx context.Context, pl model.Playlist) sourceFunc {
-	return func() (io.ReadCloser, string, error) {
-		imgURL := 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 fetchPlaylistImageURL(ctx, parsed)
-		}
-		// A missing/unreadable local file is a definitive miss, not a transient
-		// failure to retry: swallow the open error and fall through to the grid.
-		r, path, _ := fromLocalFile(imgURL)()
-		return r, path, nil
+// classifyPlaylistImage splits a playlist ExternalImageURL into a local filesystem path
+// (served file-backed) or a remote http(s) URL (fetched and stored); 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
 	}
 }
 
@@ -371,7 +410,7 @@ func mtimeOf(path string) int64 {
 	if err != nil {
 		return 0
 	}
-	return info.ModTime().Unix()
+	return info.ModTime().UnixNano()
 }
 
 // mtimeViaFS stats through the library FS instead of a joined absolute path,
@@ -384,7 +423,7 @@ func mtimeViaFS(fsys fs.FS, name string) int64 {
 	if err != nil {
 		return 0
 	}
-	return info.ModTime().Unix()
+	return info.ModTime().UnixNano()
 }
 
 // decodeTile and assembleTiles mirror playlistArtworkReader's createTile/

core/artwork/resolve_test.go

@@ -8,45 +8,18 @@ import (
 	"io"
 	"net/http"
 	"net/http/httptest"
-	"net/url"
 	"os"
 	"path/filepath"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
-	"github.com/navidrome/navidrome/core/external"
+	"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"
 )
 
-// fakeExternalProvider is a minimal external.Provider stub for resolve_test.go;
-// only AlbumImage/ArtistImage are exercised by the resolvers.
-type fakeExternalProvider struct {
-	external.Provider
-	albumImage  func(ctx context.Context, id string) (*url.URL, error)
-	artistImage func(ctx context.Context, id string) (*url.URL, error)
-}
-
-func (f *fakeExternalProvider) AlbumImage(ctx context.Context, id string) (*url.URL, error) {
-	if f.albumImage != nil {
-		return f.albumImage(ctx, id)
-	}
-	return nil, model.ErrNotFound
-}
-
-func (f *fakeExternalProvider) ArtistImage(ctx context.Context, id string) (*url.URL, error) {
-	if f.artistImage != nil {
-		return f.artistImage(ctx, id)
-	}
-	return nil, model.ErrNotFound
-}
-
-func (f *fakeExternalProvider) ArtistImageResult(ctx context.Context, id string) (*url.URL, error) {
-	return f.ArtistImage(ctx, id)
-}
-
 var _ = Describe("resolveItem", func() {
 	var (
 		ctx        context.Context
@@ -54,7 +27,7 @@ var _ = Describe("resolveItem", func() {
 		folderRepo *fakeFolderRepo
 		libRepo    *tests.MockLibraryRepo
 		ffm        *tests.MockFFmpeg
-		prov       *fakeExternalProvider
+		ag         *agents.Agents
 		repoRoot   string
 	)
 
@@ -69,7 +42,7 @@ var _ = Describe("resolveItem", func() {
 		libRepo = &tests.MockLibraryRepo{}
 		libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(repoRoot)}})
 		ffm = tests.NewMockFFmpeg("")
-		prov = &fakeExternalProvider{}
+		ag = agents.GetAgents(&tests.MockDataStore{}, nil)
 		ds = &tests.MockDataStore{
 			MockedFolder:  folderRepo,
 			MockedLibrary: libRepo,
@@ -78,11 +51,61 @@ var _ = Describe("resolveItem", func() {
 
 	Describe("kind dispatch", func() {
 		It("returns an error for kinds the worker never enqueues", func() {
-			_, err := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "mf", ItemID: "x"}, nil)
+			_, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "zz", ItemID: "x"}, nil)
 			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 := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "mf", ItemID: "mf1"}, nil)
+			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 := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "mf", ItemID: "mf2"}, nil)
+			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 := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "mf", ItemID: "mf3"}, nil)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).To(BeNil())
+		})
+
+		It("returns the error when the track is not in the DB", func() {
+			res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "mf", ItemID: "missing"}, nil)
+			Expect(err).To(MatchError(model.ErrNotFound))
+			Expect(res.reader).To(BeNil())
+		})
+	})
+
 	Describe("album", func() {
 		BeforeEach(func() {
 			conf.Server.CoverArtPriority = "cover.jpg, embedded"
@@ -98,7 +121,7 @@ var _ = Describe("resolveItem", func() {
 				{ID: "al1", Name: "Album", FolderIDs: []string{"f1"}},
 			})
 
-			res, err := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al1"}, nil)
+			res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al1"}, nil)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).ToNot(BeNil())
 			defer res.reader.Close()
@@ -114,7 +137,7 @@ var _ = Describe("resolveItem", func() {
 				{ID: "al2", Name: "Album", EmbedArtPath: "tests/fixtures/artist/an-album/test.mp3", FolderIDs: []string{"f1"}},
 			})
 
-			res, err := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al2"}, nil)
+			res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al2"}, nil)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).ToNot(BeNil())
 			defer res.reader.Close()
@@ -128,11 +151,9 @@ var _ = Describe("resolveItem", func() {
 			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
 				{ID: "al3", Name: "Album"},
 			})
-			prov.albumImage = func(context.Context, string) (*url.URL, error) {
-				return nil, errors.New("agent timed out")
-			}
+			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
 
-			res, err := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al3"}, nil)
+			res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al3"}, nil)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).To(BeNil())
 			Expect(res.extError).To(BeTrue())
@@ -143,9 +164,9 @@ var _ = Describe("resolveItem", func() {
 			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
 				{ID: "al4", Name: "Album"},
 			})
-			// prov.albumImage left nil -> fakeExternalProvider returns model.ErrNotFound
+			// no image agents enabled -> the external step is a definitive not-found
 
-			res, err := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al4"}, nil)
+			res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al4"}, nil)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).To(BeNil())
 			Expect(res.extError).To(BeFalse())
@@ -160,11 +181,9 @@ var _ = Describe("resolveItem", func() {
 			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
 				{ID: "al6", Name: "Album", FolderIDs: []string{"f1"}},
 			})
-			prov.albumImage = func(context.Context, string) (*url.URL, error) {
-				return nil, errors.New("agent timed out")
-			}
+			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
 
-			res, err := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al6"}, nil)
+			res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al6"}, nil)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).ToNot(BeNil())
 			defer res.reader.Close()
@@ -181,9 +200,9 @@ var _ = Describe("resolveItem", func() {
 			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
 				{ID: "al7", Name: "Album", FolderIDs: []string{"f1"}},
 			})
-			// prov.albumImage left nil -> fakeExternalProvider returns model.ErrNotFound
+			// no image agents enabled -> the external step is a definitive not-found
 
-			res, err := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al7"}, nil)
+			res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al7"}, nil)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).ToNot(BeNil())
 			defer res.reader.Close()
@@ -191,24 +210,22 @@ var _ = Describe("resolveItem", func() {
 			Expect(res.extError).To(BeFalse())
 		})
 
-		It("routes the external step through a custom extGate", func() {
+		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"},
 			})
-			prov.albumImage = func(context.Context, string) (*url.URL, error) {
-				return nil, errors.New("boom")
-			}
-			var extGateCalls int
-			extGate := func(f func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error) {
-				extGateCalls++
+			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 := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al5"}, extGate)
+			res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al5"}, gate)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.extError).To(BeTrue())
-			Expect(extGateCalls).To(Equal(1))
+			Expect(gatedNames).To(Equal([]string{"failAgent"}))
 		})
 	})
 
@@ -224,7 +241,7 @@ var _ = Describe("resolveItem", func() {
 			artistRepo.SetData(model.Artists{{ID: "ar1", Name: "Artist", UploadedImage: "ar1_test.jpg"}})
 			ds.MockedArtist = artistRepo
 
-			res, err := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar1"}, nil)
+			res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar1"}, nil)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).ToNot(BeNil())
 			defer res.reader.Close()
@@ -247,7 +264,7 @@ var _ = Describe("resolveItem", func() {
 				{ID: "al9", Name: "Album", LibraryID: 0, FolderIDs: []string{"f1"}},
 			}
 
-			res, err := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar2"}, nil)
+			res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar2"}, nil)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).ToNot(BeNil())
 			defer res.reader.Close()
@@ -260,11 +277,9 @@ var _ = Describe("resolveItem", func() {
 			artistRepo := tests.CreateMockArtistRepo()
 			artistRepo.SetData(model.Artists{{ID: "ar3", Name: "Artist"}})
 			ds.MockedArtist = artistRepo
-			prov.artistImage = func(context.Context, string) (*url.URL, error) {
-				return nil, errors.New("agent timed out")
-			}
+			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
 
-			res, err := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar3"}, nil)
+			res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar3"}, nil)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).To(BeNil())
 			Expect(res.extError).To(BeTrue())
@@ -275,32 +290,30 @@ var _ = Describe("resolveItem", func() {
 			artistRepo := tests.CreateMockArtistRepo()
 			artistRepo.SetData(model.Artists{{ID: "ar4", Name: "Artist"}})
 			ds.MockedArtist = artistRepo
-			// prov.artistImage left nil -> fakeExternalProvider returns model.ErrNotFound
+			// no image agents enabled -> the external step is a definitive not-found
 
-			res, err := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar4"}, nil)
+			res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar4"}, nil)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).To(BeNil())
 			Expect(res.extError).To(BeFalse())
 		})
 
-		It("routes the external step through a custom extGate", func() {
+		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
-			prov.artistImage = func(context.Context, string) (*url.URL, error) {
-				return nil, errors.New("boom")
-			}
-			var extGateCalls int
-			extGate := func(f func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error) {
-				extGateCalls++
+			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 := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar5"}, extGate)
+			res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar5"}, gate)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.extError).To(BeTrue())
-			Expect(extGateCalls).To(Equal(1))
+			Expect(gatedNames).To(Equal([]string{"failAgent"}))
 		})
 	})
 
@@ -313,7 +326,7 @@ var _ = Describe("resolveItem", func() {
 			radioRepo.Data = map[string]*model.Radio{"ra1": {ID: "ra1", Name: "Radio"}}
 			ds.MockedRadio = radioRepo
 
-			res, err := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "ra", ItemID: "ra1"}, nil)
+			res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "ra", ItemID: "ra1"}, nil)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res).To(Equal(resolution{}))
 		})
@@ -329,7 +342,7 @@ var _ = Describe("resolveItem", func() {
 			radioRepo.Data = map[string]*model.Radio{"ra2": {ID: "ra2", Name: "Radio", UploadedImage: "ra2_test.jpg"}}
 			ds.MockedRadio = radioRepo
 
-			res, err := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "ra", ItemID: "ra2"}, nil)
+			res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "ra", ItemID: "ra2"}, nil)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).ToNot(BeNil())
 			defer res.reader.Close()
@@ -361,7 +374,7 @@ var _ = Describe("resolveItem", func() {
 				plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: albumIDs}
 				ds.MockedPlaylist = plRepo
 
-				res, err := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "pl1"}, nil)
+				res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "pl1"}, nil)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(res.reader).ToNot(BeNil())
 				defer res.reader.Close()
@@ -393,7 +406,7 @@ var _ = Describe("resolveItem", func() {
 			plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: []string{"t1", "t2"}}
 			ds.MockedPlaylist = plRepo
 
-			res, err := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "plu"}, nil)
+			res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "plu"}, nil)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).ToNot(BeNil())
 			defer res.reader.Close()
@@ -411,7 +424,7 @@ var _ = Describe("resolveItem", func() {
 			plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: []string{"t1", "t2"}}
 			ds.MockedPlaylist = plRepo
 
-			res, err := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "pls"}, nil)
+			res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "pls"}, nil)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).ToNot(BeNil())
 			defer res.reader.Close()
@@ -419,6 +432,25 @@ var _ = Describe("resolveItem", func() {
 			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 := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "pll"}, nil)
+			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
@@ -428,17 +460,17 @@ var _ = Describe("resolveItem", func() {
 			plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: []string{"t1"}}
 			ds.MockedPlaylist = plRepo
 
-			var extGateCalls int
-			extGate := func(f func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error) {
-				extGateCalls++
+			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 := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "ple"}, extGate)
+			res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "ple"}, gate)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).To(BeNil())
 			Expect(res.extError).To(BeTrue())
-			Expect(extGateCalls).To(Equal(1))
+			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() {
@@ -449,7 +481,7 @@ var _ = Describe("resolveItem", func() {
 			plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: []string{"t1"}}
 			ds.MockedPlaylist = plRepo
 
-			res, err := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "plm"}, nil)
+			res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "plm"}, nil)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).To(BeNil())
 			Expect(res.extError).To(BeFalse())
@@ -467,7 +499,7 @@ var _ = Describe("resolveItem", func() {
 			plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: []string{"t1"}}
 			ds.MockedPlaylist = plRepo
 
-			res, err := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "pl404"}, nil)
+			res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "pl404"}, nil)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).ToNot(BeNil())
 			defer res.reader.Close()
@@ -488,7 +520,7 @@ var _ = Describe("resolveItem", func() {
 			plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: []string{"t1"}}
 			ds.MockedPlaylist = plRepo
 
-			res, err := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "pl500"}, nil)
+			res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "pl500"}, nil)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).To(BeNil())
 			Expect(res.extError).To(BeTrue())
@@ -504,7 +536,7 @@ var _ = Describe("resolveItem", func() {
 			ds.MockedPlaylist = plRepo
 			folderRepo.result = nil
 
-			res, err := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "pl2"}, nil)
+			res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "pl2"}, nil)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).To(BeNil())
 			Expect(res.source).To(BeEmpty())
@@ -523,7 +555,7 @@ var _ = Describe("resolveItem", func() {
 			plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: []string{"t1"}}
 			ds.MockedPlaylist = plRepo
 
-			res, err := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "plbomb"}, nil)
+			res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "plbomb"}, nil)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).To(BeNil())
 			Expect(res.source).To(BeEmpty())
@@ -537,7 +569,7 @@ var _ = Describe("resolveItem", func() {
 			plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: []string{"missing1", "missing2"}}
 			ds.MockedPlaylist = plRepo
 
-			res, err := resolveItem(ctx, ds, prov, ffm, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "pl3"}, nil)
+			res, err := resolveItem(ctx, ds, ag, ffm, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "pl3"}, nil)
 			Expect(err).To(HaveOccurred())
 			Expect(res).To(Equal(resolution{}))
 		})

core/artwork/serving.go

@@ -0,0 +1,417 @@
+package artwork
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"time"
+
+	"github.com/navidrome/navidrome/conf"
+	"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/resources"
+	"github.com/navidrome/navidrome/utils/cache"
+)
+
+var ErrUnavailable = errors.New("artwork unavailable")
+
+// errStaleSource signals that a backing file's mtime no longer matches the state
+// row's RefMtime: the stored hash may be stale, so the load is aborted (dangling).
+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 hash (immutable URL match); "" for placeholders
+	ETag        string    // served-representation validator; "" falls back to Hash (full-size original)
+	LastUpdated time.Time // zero for placeholders
+	Placeholder bool
+}
+
+// representationTag identifies a served resized representation for HTTP validation: it changes with
+// the dimensions and the encode settings (CoverArtQuality/EnableWebPEncoding), 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 Service interface {
+	// Get serves resolved/provisional artwork; ErrUnavailable or model.ErrNotFound when
+	// there is nothing to serve (absent, pending, dangling) — caller picks placeholder vs 404.
+	Get(ctx context.Context, artID model.ArtworkID, size int, square bool) (*Image, error)
+	// GetOrPlaceholder parses a raw id token (raw entity ids accepted, as today) and falls
+	// back to the kind's placeholder image (never resized, Placeholder=true).
+	GetOrPlaceholder(ctx context.Context, id string, size int, square bool) (*Image, error)
+}
+
+func NewService(ds model.DataStore, cache cache.FileCache, store *ImageStore, ffm ffmpeg.FFmpeg) Service {
+	return &service{ds: ds, cache: cache, store: store, ffmpeg: ffm}
+}
+
+type service struct {
+	ds     model.DataStore
+	cache  cache.FileCache
+	store  *ImageStore
+	ffmpeg ffmpeg.FFmpeg
+}
+
+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 {
+		img, err = s.Get(ctx, artID, size, square)
+	}
+	if errors.Is(err, ErrUnavailable) || errors.Is(err, model.ErrNotFound) {
+		return s.placeholder(artID.Kind), nil
+	}
+	return img, err
+}
+
+func (s *service) Get(ctx context.Context, artID model.ArtworkID, size int, square bool) (*Image, error) {
+	if artID.ID == "" {
+		return nil, ErrUnavailable
+	}
+	if size < 0 {
+		size = 0 // a negative size is a full-size request, 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)
+	}
+}
+
+// serveEntity serves an entity whose state the worker owns (album/artist/playlist/radio):
+// found row serves its hash, absent row is unavailable, missing row reads through provisionally.
+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.Prefix(), 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 == "":
+		return nil, ErrUnavailable
+	default:
+		return s.serveHash(ctx, artID, ia, size, square)
+	}
+}
+
+// serveHash serves the bytes of a found state row: full-size streams the original, sized
+// goes through the resize cache. A mismatch/open error is dangling (a warm cache still serves).
+func (s *service) serveHash(ctx context.Context, artID model.ArtworkID, ia *model.ItemArtwork, size int, square bool) (*Image, error) {
+	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
+	}
+
+	if size == 0 && !square {
+		rc, err := openOriginal(ia, art.Mime, s.store)
+		if err != nil {
+			return s.dangling(ctx, artID)
+		}
+		return &Image{ReadCloser: rc, Hash: ia.Hash, LastUpdated: ia.UpdatedAt}, nil
+	}
+
+	item := newResizedItem(ia, art.Mime, size, square, s.store, s.ffmpeg)
+	stream, err := s.cache.Get(ctx, item)
+	if err != nil {
+		if errors.Is(err, context.Canceled) {
+			return nil, err
+		}
+		return s.dangling(ctx, artID)
+	}
+	return &Image{ReadCloser: stream, Hash: ia.Hash, ETag: representationTag(ia.Hash, size, square), LastUpdated: ia.UpdatedAt}, nil
+}
+
+// openOriginal opens the full-resolution bytes for a found state row, enforcing 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()
+			return nil, errStaleSource
+		}
+		return f, nil
+	}
+	// Store-backed (embedded/external/generated): the bytes live in the content-addressed
+	// store, but an embedded source still carries the audio file's mtime to detect edits.
+	if ia.SourcePath != "" && ia.RefMtime != 0 {
+		info, err := os.Stat(ia.SourcePath)
+		if err != nil {
+			return nil, err
+		}
+		if info.ModTime().UnixNano() != ia.RefMtime {
+			return nil, errStaleSource
+		}
+	}
+	return store.Open(ia.Hash, mime)
+}
+
+// newResizedItem builds the resize-cache reader for a found state row's bytes; shared by
+// the serving path and the worker's precache so both key the cache identically.
+func newResizedItem(ia *model.ItemArtwork, mime string, size int, square bool, store *ImageStore, ffm ffmpeg.FFmpeg) *resizedItem {
+	return &resizedItem{
+		hash:       ia.Hash,
+		size:       size,
+		square:     square,
+		lastUpdate: ia.UpdatedAt,
+		ffmpeg:     ffm,
+		open:       func() (io.ReadCloser, error) { return openOriginal(ia, mime, store) },
+	}
+}
+
+// provisional does a local-only read-through for an entity with no state row: it enqueues
+// the worker (Bump) and serves any local bytes immediately, never writing a state row.
+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 := resolveItemLocal(ctx, s.ds, s.ffmpeg, item)
+	if err != nil {
+		return nil, err
+	}
+	s.enqueue(ctx, artID, model.ArtworkPriorityBump)
+	return s.serveResolution(ctx, res, size, square)
+}
+
+// serveResolution turns a local resolution's bytes into a servable Image (byte-hash
+// only, no decode). A resolution with no reader is unavailable.
+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
+	}
+	return s.serveBytes(ctx, hash, data, unixMtime(res.refMtime), size, square)
+}
+
+// serveBytes serves in-memory bytes: full-size directly, sized through the resize
+// cache keyed by the byte-hash (so it lines up with the worker's eventual store entry).
+func (s *service) serveBytes(ctx context.Context, hash string, data []byte, lastUpdate time.Time, size int, square bool) (*Image, error) {
+	if size == 0 && !square {
+		return &Image{ReadCloser: io.NopCloser(bytes.NewReader(data)), Hash: hash, LastUpdated: lastUpdate}, nil
+	}
+	item := &resizedItem{
+		hash:       hash,
+		size:       size,
+		square:     square,
+		lastUpdate: lastUpdate,
+		ffmpeg:     s.ffmpeg,
+		open:       func() (io.ReadCloser, error) { return io.NopCloser(bytes.NewReader(data)), nil },
+	}
+	stream, err := s.cache.Get(ctx, item)
+	if err != nil {
+		return nil, err
+	}
+	return &Image{ReadCloser: stream, Hash: hash, ETag: representationTag(hash, size, square), LastUpdated: lastUpdate}, nil
+}
+
+// serveMediaFile serves a track: own found art wins; an absent row delegates to the album;
+// a missing row extracts embedded art (if eligible, enqueuing) else delegates without enqueue.
+func (s *service) serveMediaFile(ctx context.Context, artID model.ArtworkID, size int, square bool) (*Image, error) {
+	// Per-track art can be disabled after mf rows were resolved (the setting is not in the
+	// config fingerprint). Honor it at serve time so a direct mf- URL falls 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("mf", 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 to album delegation
+	case errors.Is(err, model.ErrNotFound):
+		// no row → fall through to embedded eligibility / album delegation
+	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's fallback: a multi-disc track defers to its disc art
+	// (which itself falls back to the album), not straight to the album.
+	return s.Get(ctx, mf.DiscCoverArtID(), size, square)
+}
+
+// provisionalEmbedded extracts a track's embedded art for an immediate serve and always
+// enqueues the track (Bump) so the worker persists state; it never writes a state row.
+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, _ := resolveEmbedded(ctx, lib, s.ffmpeg, mf.Path)
+	s.enqueue(ctx, artID, model.ArtworkPriorityBump)
+	return s.serveResolution(ctx, res, size, square)
+}
+
+// serveDisc serves disc-level artwork as a pure provisional read-through: no state rows,
+// no enqueue. It tries the disc-folder selection chain and falls 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
+	}
+	// Only multi-disc albums use disc-specific resolution (matching the legacy reader); a
+	// single-disc album serves album art directly, so a stray disc*/embedded image can't
+	// shadow higher-priority album art.
+	if len(dr.album.Discs) > 1 {
+		funcs := dr.fromDiscArtPriority(ctx, s.ffmpeg, conf.Server.DiscArtPriority)
+		if r, path, err := selectImageReader(ctx, artID, funcs...); err == nil && r != nil {
+			defer r.Close()
+			if data, rerr := readCapped(r); rerr == nil {
+				if hash, herr := HashImage(bytes.NewReader(data)); herr == nil {
+					return s.serveBytes(ctx, hash, data, unixMtime(mtimeViaFS(dr.lib.FS, path)), size, square)
+				}
+			}
+		}
+	}
+	albumArtID := model.ArtworkID{Kind: model.KindAlbumArtwork, ID: dr.album.ID}
+	return s.Get(ctx, albumArtID, size, square)
+}
+
+// dangling enqueues a re-resolution at Scan priority and reports the artwork as
+// unavailable, leaving the state row untouched.
+func (s *service) dangling(ctx context.Context, artID model.ArtworkID) (*Image, error) {
+	s.enqueue(ctx, artID, model.ArtworkPriorityScan)
+	return nil, ErrUnavailable
+}
+
+// enqueue schedules a request-triggered re-resolution. It uses EnqueueBump so an incidental
+// read-through never resets a failed resolution's backoff (unlike scan/manual re-resolve).
+func (s *service) enqueue(ctx context.Context, artID model.ArtworkID, priority int) {
+	err := s.ds.ArtworkQueue(ctx).EnqueueBump(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 (s *service) placeholder(kind model.Kind) *Image {
+	return placeholderImage(kind)
+}
+
+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}
+}
+
+// PlaceholderFor returns the kind-appropriate placeholder for an artwork id, for callers that must
+// serve a placeholder without consulting persisted state (e.g. an access-control denial).
+func PlaceholderFor(id string) *Image {
+	artID, _ := model.ParseArtworkID(id)
+	return placeholderImage(artID.Kind)
+}
+
+type coverArtIDGetter interface {
+	CoverArtID() model.ArtworkID
+}
+
+// parseArtworkID ports the legacy getArtworkId: parse the token, and if it is a raw
+// entity id, resolve the entity and take its CoverArtID.
+func (s *service) parseArtworkID(ctx context.Context, id string) (model.ArtworkID, error) {
+	if id == "" {
+		return model.ArtworkID{}, ErrUnavailable
+	}
+	if artID, err := model.ParseArtworkID(id); err == nil {
+		return artID, nil
+	}
+	entity, err := model.GetEntityByID(ctx, s.ds, id)
+	if err != nil {
+		return model.ArtworkID{}, err
+	}
+	if e, ok := entity.(coverArtIDGetter); ok {
+		return e.CoverArtID(), nil
+	}
+	return model.ArtworkID{}, model.ErrNotFound
+}
+
+func unixMtime(mtime int64) time.Time {
+	if mtime <= 0 {
+		return time.Time{}
+	}
+	return time.Unix(0, mtime) // RefMtime is unix-nanoseconds
+}
+
+// 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
+	lastUpdate time.Time
+	ffmpeg     ffmpeg.FFmpeg
+	open       func() (io.ReadCloser, error)
+}
+
+func (r *resizedItem) Key() string {
+	return fmt.Sprintf("h-%s.%d.%v.%s", r.hash, r.size, r.square, formatQualityTag())
+}
+
+func (r *resizedItem) LastUpdated() time.Time { return r.lastUpdate }
+
+func (r *resizedItem) Reader(ctx context.Context) (io.ReadCloser, string, 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)), r.Key(), nil
+	}
+	if rc, ok := resized.(io.ReadCloser); ok {
+		return rc, r.Key(), nil
+	}
+	return io.NopCloser(resized), r.Key(), nil
+}

core/artwork/serving_test.go

@@ -0,0 +1,372 @@
+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/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("Service", func() {
+	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        Service
+		repoRoot   string
+		coverBytes []byte
+	)
+
+	primaryKey := func(kind, id string) string { return kind + "|" + id + "|" + model.ImageTypePrimary }
+
+	// seedFoundStore installs a store-backed found state (bytes in the content-addressed
+	// store, no backing file) and returns the hash.
+	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())
+		return hash
+	}
+
+	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())
+		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) {
+				r, _, err := arg.(artworkReader).Reader(ctx)
+				return r, err
+			})
+		Eventually(func() bool { return imgCache.Available(ctx) }).Should(BeTrue())
+		svc = NewService(ds, imgCache, store, ffm)
+	})
+
+	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)
+
+			img, err := svc.Get(ctx, model.MustParseArtworkID("al-al1"), 100, false)
+			Expect(err).ToNot(HaveOccurred())
+			// A resized response versions its validator with the encode settings, distinct from
+			// the pixel hash, so a CoverArtQuality/WebP change invalidates client caches.
+			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))
+
+			// Delete the store file: a warm resize-cache entry must keep serving without
+			// ever touching the original (the stale-serve self-heal).
+			hash, _ := HashImage(bytes.NewReader(coverBytes))
+			Expect(store.Remove(hash, "image/jpeg", time.Now().Add(time.Hour))).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())
+		})
+
+		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())
+			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())
+			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("al", "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())
+			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))
+		})
+
+		It("returns ErrUnavailable for an absent state without enqueuing", func() {
+			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "al4"})).To(Succeed())
+
+			_, err := svc.Get(ctx, model.MustParseArtworkID("al-al4"), 0, false)
+			Expect(err).To(MatchError(ErrUnavailable))
+			Expect(queueRepo.Data).To(BeEmpty())
+		})
+	})
+
+	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("al", "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("al", "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
+			// A resolved mf row exists (from when the setting was on) but must not be served.
+			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("mf", "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() {
+			// Not embedded-eligible: the fallback must mirror CoverArtID (disc first, then album).
+			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 wins over the album's found art, proving it routed via serveDisc.
+			Expect(readAll(img)).To(Equal(coverBytes))
+		})
+
+		It("delegates a single-disc track straight to the album, skipping disc resolution", func() {
+			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())
+			// Single-disc album: album art wins; the folder disc image must not shadow it.
+			Expect(readAll(img)).To(Equal([]byte("album-art-distinct")))
+		})
+	})
+
+	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))
+		})
+
+		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))
+		})
+	})
+})
+
+func fileMtime(path string) int64 {
+	GinkgoHelper()
+	info, err := os.Stat(path)
+	Expect(err).ToNot(HaveOccurred())
+	return info.ModTime().UnixNano()
+}

core/artwork/sources.go

@@ -16,11 +16,9 @@ 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"
 )
 
@@ -171,56 +169,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)
-	}
-}
-
-// fromArtistExternalResult is the worker's artist external step: via ArtistImageResult a
-// transient agent failure surfaces as an error (extError) rather than settling as absent.
-func fromArtistExternalResult(ctx context.Context, ar model.Artist, provider external.Provider) sourceFunc {
-	return func() (io.ReadCloser, string, error) {
-		imageUrl, err := provider.ArtistImageResult(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)

core/artwork/testhelpers_test.go

@@ -0,0 +1,37 @@
+package artwork
+
+import (
+	"github.com/navidrome/navidrome/model"
+)
+
+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
+}

core/artwork/wire_providers.go

@@ -5,9 +5,8 @@ import (
 )
 
 var Set = wire.NewSet(
-	NewArtwork,
+	NewService,
 	GetImageCache,
-	NewCacheWarmer,
 	NewWorker,
 	ProvideImageStore,
 )

core/artwork/worker.go

@@ -10,11 +10,13 @@ import (
 	"time"
 
 	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/core/external"
-	"github.com/navidrome/navidrome/core/ffmpeg"
+	"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"
 	"golang.org/x/time/rate"
 )
 
@@ -28,35 +30,40 @@ const (
 
 var errBreakerOpen = errors.New("artwork: external circuit breaker open")
 
-// Worker drains the artwork queue through processItem: the external step is rate-limited
-// and circuit-broken, and prune is serialized against in-flight acquisitions via pruneMu.
-type Worker struct {
-	deps    workerDeps
+// extGate is one agent's rate limiter + circuit breaker; each external agent gets its
+// own so a provider whose API or CDN is down backs off in isolation from the others.
+type extGate struct {
 	limiter *rate.Limiter
 	breaker *breaker
+}
+
+// Worker drains the artwork queue through processItem: each external agent is rate-limited
+// and circuit-broken independently, and prune is serialized against in-flight acquisitions
+// via pruneMu.
+type Worker struct {
+	deps    workerDeps
+	broker  events.Broker
 	pruneMu sync.RWMutex
 	wake    chan struct{}
 	runCtx  context.Context
 
+	gatesMu sync.Mutex
+	gates   map[string]*extGate
+
 	mu       sync.Mutex
 	inFlight map[string]struct{}
 }
 
-func NewWorker(ds model.DataStore, store *ImageStore, prov external.Provider, ffmpeg ffmpeg.FFmpeg) *Worker {
-	rps := conf.Server.ArtworkExternalMaxRPS
-	limit := rate.Inf // 0 or negative disables the external throttle
-	if rps > 0 {
-		limit = rate.Limit(rps)
-	}
+func NewWorker(ds model.DataStore, store *ImageStore, ag *agents.Agents, ffmpeg ffmpeg.FFmpeg, broker events.Broker, imgCache cache.FileCache) *Worker {
 	w := &Worker{
-		deps:     workerDeps{ds: ds, store: store, prov: prov, ffmpeg: ffmpeg},
-		limiter:  rate.NewLimiter(limit, max(1, rps)),
-		breaker:  newBreaker(),
+		deps:     workerDeps{ds: ds, store: store, agents: ag, ffmpeg: ffmpeg, cache: imgCache},
+		broker:   broker,
 		wake:     make(chan struct{}, 1),
 		runCtx:   context.Background(),
+		gates:    map[string]*extGate{},
 		inFlight: map[string]struct{}{},
 	}
-	w.deps.extGate = w.gate
+	w.deps.gate = w.gate
 	return w
 }
 
@@ -128,6 +135,8 @@ func (w *Worker) drain(ctx context.Context, concurrency int) (int, error) {
 	}
 	sem := make(chan struct{}, concurrency)
 	var wg sync.WaitGroup
+	var refreshMu sync.Mutex
+	var refresh []model.ArtworkQueueItem
 	for _, item := range items {
 		sem <- struct{}{}
 		wg.Add(1)
@@ -135,14 +144,60 @@ func (w *Worker) drain(ctx context.Context, concurrency int) (int, error) {
 			defer wg.Done()
 			defer func() { <-sem }()
 			defer w.release(it)
-			w.process(ctx, it)
+			out := w.process(ctx, it)
+			// Refresh clients on any visible state change: found/foundStale (new art) and absent
+			// (removed art — clients must drop a previously-served immutable cover). foundStale
+			// also wrote a served state row.
+			if out == outcomeFound || out == outcomeFoundStale || out == outcomeAbsent {
+				refreshMu.Lock()
+				refresh = append(refresh, it)
+				refreshMu.Unlock()
+			}
+			// Precache only actual images. Post-outcome only: the queue row was already settled
+			// by process, so warming the resize cache here can never block or alter queue ops.
+			if out == outcomeFound || out == outcomeFoundStale {
+				w.precache(ctx, it)
+			}
 		}(item)
 	}
 	wg.Wait()
+	w.broadcastRefresh(ctx, refresh)
 	return len(items), nil
 }
 
-func (w *Worker) process(ctx context.Context, item model.ArtworkQueueItem) {
+// artworkKindToResource maps a queue item's kind to the UI resource name carried
+// in the refresh event.
+var artworkKindToResource = map[string]string{
+	"al": "album",
+	"ar": "artist",
+	"pl": "playlist",
+	"ra": "radio",
+	"mf": "song",
+}
+
+// broadcastRefresh emits one coalesced RefreshResource for the batch's newly-acquired
+// artwork, so connected 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 {
+		if res, ok := artworkKindToResource[it.ItemKind]; 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 {
 	if item.ImageType == "" {
 		item.ImageType = model.ImageTypePrimary
 	}
@@ -166,6 +221,35 @@ func (w *Worker) process(ctx context.Context, item model.ArtworkQueueItem) {
 			log.Warn(ctx, "artwork: could not reschedule failed queue item", "kind", item.ItemKind, "id", item.ItemID, err)
 		}
 	}
+	return out
+}
+
+// precache warms the resize cache for a newly-acquired image at the UI cover size, so the
+// first UI request is a cache hit. Skipped when disabled; failures are debug-only.
+func (w *Worker) precache(ctx context.Context, item model.ArtworkQueueItem) {
+	if !conf.Server.EnableArtworkPrecache || w.deps.cache == nil || w.deps.cache.Disabled(ctx) {
+		return
+	}
+	imageType := item.ImageType
+	if imageType == "" {
+		imageType = model.ImageTypePrimary
+	}
+	repo := w.deps.ds.Artwork(ctx)
+	ia, err := repo.GetItemArtwork(item.ItemKind, item.ItemID, imageType)
+	if err != nil || ia.Hash == "" {
+		return
+	}
+	art, err := repo.GetImage(ia.Hash)
+	if err != nil {
+		return
+	}
+	stream, err := w.deps.cache.Get(ctx, newResizedItem(ia, art.Mime, conf.Server.UICoverArtSize, false, w.deps.store, w.deps.ffmpeg))
+	if err != nil {
+		log.Debug(ctx, "artwork: precache failed", "kind", item.ItemKind, "id", item.ItemID, err)
+		return
+	}
+	_, _ = io.Copy(io.Discard, stream)
+	_ = stream.Close()
 }
 
 // claim reserves items not already in flight, so a row appearing twice within a single
@@ -195,20 +279,39 @@ func queueKey(it model.ArtworkQueueItem) string {
 	return it.ItemKind + "|" + it.ItemID + "|" + it.ImageType
 }
 
-// gate wraps the external step with the rate limiter and circuit breaker, matching
-// extGateFunc so it can be injected via workerDeps.extGate.
-func (w *Worker) gate(f func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error) {
-	if !w.breaker.allow() {
+// gate wraps a named external step with that agent's own rate limiter and circuit
+// breaker, matching gateFunc so it can be injected via workerDeps.gate.
+func (w *Worker) gate(name string, f func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error) {
+	g := w.gateFor(name)
+	if !g.breaker.allow() {
 		return nil, "", errBreakerOpen
 	}
-	if err := w.limiter.Wait(w.runCtx); err != nil {
+	if err := g.limiter.Wait(w.runCtx); err != nil {
 		return nil, "", err
 	}
 	r, path, err := f()
-	w.breaker.record(err)
+	g.breaker.record(err)
 	return r, path, err
 }
 
+// gateFor lazily creates the per-name gate on first use, each with its own limiter at
+// ArtworkExternalMaxRPS and its own breaker.
+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.ArtworkExternalMaxRPS
+	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
+}
+
 // backoffFor returns min(5m×4^n, 48h) scaled by (1+jitter), with jitter in [-0.2, 0.2].
 func backoffFor(attempts int, jitter float64) time.Duration {
 	d := math.Min(float64(backoffBase)*math.Pow(4, float64(attempts)), float64(backoffCap))
@@ -245,8 +348,9 @@ func (b *breaker) allow() bool {
 func (b *breaker) record(err error) {
 	b.mu.Lock()
 	defer b.mu.Unlock()
-	// A not-found is a definitive answer, not a fault; only real errors trip the breaker.
-	if err == nil || errors.Is(err, model.ErrNotFound) {
+	// A not-found (from either package) is a definitive answer, not a fault; only real
+	// errors trip the breaker. Must stay consistent with isTransientExternal.
+	if err == nil || errors.Is(err, model.ErrNotFound) || errors.Is(err, agents.ErrNotFound) {
 		b.failures = 0
 		return
 	}

core/artwork/worker_soak_test.go

@@ -10,6 +10,7 @@ import (
 
 	"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"
@@ -39,7 +40,7 @@ var _ = Describe("Worker soak", func() {
 			ImageFiles: []string{"cover.jpg"},
 		}}}
 		ffm := tests.NewMockFFmpeg("")
-		prov := &fakeExternalProvider{}
+		ag := agents.GetAgents(&tests.MockDataStore{}, nil)
 		artRepo := tests.CreateMockArtworkRepo()
 		albumRepo := tests.CreateMockAlbumRepo()
 		albumRepo.SetData(model.Albums{
@@ -53,7 +54,7 @@ var _ = Describe("Worker soak", func() {
 			MockedAlbum:   albumRepo,
 		}
 		store := NewImageStore(GinkgoT().TempDir())
-		deps := &workerDeps{ds: ds, store: store, prov: prov, ffmpeg: ffm}
+		deps := &workerDeps{ds: ds, store: store, agents: ag, ffmpeg: ffm}
 		conf.Server.CoverArtPriority = "cover.jpg, embedded"
 
 		// Dangling refs (al/ra ids the repos don't know about) mirror an entity

core/artwork/worker_test.go

@@ -4,19 +4,49 @@ import (
 	"context"
 	"errors"
 	"io"
-	"net/url"
+	"net/http"
 	"os"
+	"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/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 	"go.uber.org/goleak"
 )
 
+// recordingCache captures the keys passed to Get so precache warming can be asserted,
+// and can be forced Disabled to exercise the skip path.
+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 append([]string(nil), c.keys...)
+}
+
 // reenqueueOnDequeue simulates a concurrent scan Enqueue between DequeueBatch and the
 // worker's delete by bumping retry_at, so a DeleteIfUnchanged on the dequeued value no-ops.
 type reenqueueOnDequeue struct {
@@ -38,6 +68,32 @@ func (r *reenqueueOnDequeue) DequeueBatch(n int) ([]model.ArtworkQueueItem, erro
 	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 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 {
@@ -54,10 +110,12 @@ var _ = Describe("Worker", func() {
 		folderRepo *fakeFolderRepo
 		libRepo    *tests.MockLibraryRepo
 		ffm        *tests.MockFFmpeg
-		prov       *fakeExternalProvider
+		ag         *agents.Agents
 		store      *ImageStore
 		artRepo    *tests.MockArtworkRepo
 		queueRepo  *tests.MockArtworkQueueRepo
+		broker     *fakeEventBroker
+		imgCache   *recordingCache
 		repoRoot   string
 		w          *Worker
 	)
@@ -68,12 +126,13 @@ var _ = Describe("Worker", func() {
 		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("")
-		prov = &fakeExternalProvider{}
+		ag = agents.GetAgents(&tests.MockDataStore{}, nil)
 		artRepo = tests.CreateMockArtworkRepo()
 		queueRepo = tests.CreateMockArtworkQueueRepo()
 		ds = &tests.MockDataStore{
@@ -86,7 +145,14 @@ var _ = Describe("Worker", func() {
 		store = NewImageStore(GinkgoT().TempDir())
 		conf.Server.CoverArtPriority = "cover.jpg, embedded"
 		conf.Server.ArtworkExternalMaxRPS = 1000 // keep the limiter out of the way of behavior tests
-		w = NewWorker(ds, store, prov, ffm)
+		broker = &fakeEventBroker{}
+		imgCache = &recordingCache{FileCache: cache.NewFileCache("WorkerTest", "100MB", "images", 0,
+			func(ctx context.Context, arg cache.Item) (io.Reader, error) {
+				r, _, err := arg.(artworkReader).Reader(ctx)
+				return r, err
+			})}
+		Eventually(func() bool { return imgCache.Available(ctx) }).Should(BeTrue())
+		w = NewWorker(ds, store, ag, ffm, broker, imgCache)
 	})
 
 	Describe("drain", func() {
@@ -115,12 +181,43 @@ var _ = Describe("Worker", func() {
 			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("mf", "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"}})
-			prov.albumImage = func(context.Context, string) (*url.URL, error) {
-				return nil, errors.New("agent timed out")
-			}
+			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)
@@ -145,9 +242,7 @@ var _ = Describe("Worker", func() {
 			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
 				{ID: "alstale", Name: "Album", FolderIDs: []string{"f1"}},
 			})
-			prov.albumImage = func(context.Context, string) (*url.URL, error) {
-				return nil, errors.New("agent timed out")
-			}
+			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)
@@ -162,6 +257,10 @@ var _ = Describe("Worker", func() {
 			ia, err := artRepo.GetItemArtwork("al", "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() {
@@ -174,7 +273,7 @@ var _ = Describe("Worker", func() {
 			})
 			racing := &reenqueueOnDequeue{MockArtworkQueueRepo: queueRepo}
 			ds.MockedArtworkQueue = racing
-			w = NewWorker(ds, store, prov, ffm)
+			w = NewWorker(ds, store, ag, ffm, broker, imgCache)
 			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{
 				ItemKind: "al", ItemID: "al7", Priority: model.ArtworkPriorityScan,
 			})).To(Succeed())
@@ -193,12 +292,10 @@ var _ = Describe("Worker", func() {
 		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"}})
-			prov.albumImage = func(context.Context, string) (*url.URL, error) {
-				return nil, errors.New("agent timed out")
-			}
+			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
 			racing := &reenqueueOnDequeue{MockArtworkQueueRepo: queueRepo}
 			ds.MockedArtworkQueue = racing
-			w = NewWorker(ds, store, prov, ffm)
+			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
 
@@ -221,7 +318,7 @@ var _ = Describe("Worker", func() {
 				private:       model.Playlist{ID: "plPriv", OwnerID: "admin"},
 				tracks:        &tests.MockPlaylistTrackRepo{},
 			}
-			w = NewWorker(vds, store, prov, ffm)
+			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)
@@ -240,6 +337,67 @@ var _ = Describe("Worker", func() {
 			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"))
+		})
+
+		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("al", "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("Bump", func() {
@@ -259,13 +417,13 @@ var _ = Describe("Worker", func() {
 				return nil, "", errors.New("boom")
 			}
 			for range 5 {
-				_, _, err := w.gate(failing)
+				_, _, err := w.gate("A", failing)
 				Expect(err).To(HaveOccurred())
 			}
 			Expect(calls).To(Equal(5))
 
-			_, _, err := w.gate(failing)
-			Expect(err).To(HaveOccurred())
+			_, _, err := w.gate("A", failing)
+			Expect(err).To(MatchError(errBreakerOpen))
 			Expect(calls).To(Equal(5), "an open breaker must not call the external step")
 		})
 
@@ -273,9 +431,9 @@ var _ = Describe("Worker", 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(failing)
+				_, _, _ = w.gate("A", failing)
 			}
-			_, _, err := w.gate(ok)
+			_, _, err := w.gate("A", ok)
 			Expect(err).ToNot(HaveOccurred())
 
 			var calls int
@@ -284,10 +442,85 @@ var _ = Describe("Worker", func() {
 				return nil, "", errors.New("boom")
 			}
 			for range 5 {
-				_, _, _ = w.gate(counting)
+				_, _, _ = 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() {
+			// Regression: agents.ErrNotFound is a definitive miss, not a fault. A run of
+			// artless items must never trip the breaker, or they'd loop in retry instead of
+			// settling absent. Uses the real gate, not passthroughGate.
+			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))
+
+			Expect(imgCache.getKeys()).To(ContainElement(ContainSubstring(".300.false.")))
+		})
+
+		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())
+		})
 	})
 
 	Describe("RunPrune", func() {
@@ -313,7 +546,7 @@ var _ = Describe("Worker", func() {
 			DeferCleanup(func() { goleak.VerifyNone(GinkgoT(), ignore) })
 
 			localDS := &tests.MockDataStore{MockedArtworkQueue: tests.CreateMockArtworkQueueRepo()}
-			lw := NewWorker(localDS, NewImageStore(GinkgoT().TempDir()), &fakeExternalProvider{}, tests.NewMockFFmpeg(""))
+			lw := NewWorker(localDS, NewImageStore(GinkgoT().TempDir()), agents.GetAgents(localDS, nil), tests.NewMockFFmpeg(""), &fakeEventBroker{}, imgCache)
 
 			runCtx, cancel := context.WithCancel(ctx)
 			done := make(chan error, 1)

core/artwork/worker_timing_test.go

@@ -2,10 +2,13 @@ package artwork
 
 import (
 	"errors"
+	"io"
 	"testing"
 	"testing/synctest"
 	"time"
 
+	"github.com/navidrome/navidrome/core/agents"
+	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/gomega"
 )
 
@@ -37,3 +40,39 @@ func TestArtworkBreakerHalfOpen(t *testing.T) {
 		g.Expect(b.allow()).To(BeTrue())
 	})
 }
+
+// Drives the worker's per-name gate map with the fake clock: one agent's open breaker
+// must neither block another agent nor short-circuit the other's probe recovery.
+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))
+	})
+}

core/external/provider.go

@@ -4,7 +4,6 @@ import (
 	"context"
 	"errors"
 	"fmt"
-	"net/url"
 	"sort"
 	"strings"
 	"time"
@@ -35,10 +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 string, count int) (model.MediaFiles, error)
-	ArtistImage(ctx context.Context, id string) (*url.URL, error)
-	// ArtistImageResult is like ArtistImage but reports a transient agent failure as a real error, not ErrNotFound.
-	ArtistImageResult(ctx context.Context, id string) (*url.URL, error)
-	AlbumImage(ctx context.Context, id string) (*url.URL, error)
 }
 
 type provider struct {
@@ -372,94 +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) {
-	u, _, err := e.artistImage(ctx, id)
-	return u, err
-}
-
-// ArtistImageResult is like ArtistImage but surfaces a transient agent failure as the
-// real error, so an agent outage is not mistaken for a definitive no-image (ErrNotFound).
-func (e *provider) ArtistImageResult(ctx context.Context, id string) (*url.URL, error) {
-	u, agentErr, err := e.artistImage(ctx, id)
-	if agentErr != nil && errors.Is(err, model.ErrNotFound) {
-		return nil, agentErr
-	}
-	return u, err
-}
-
-// artistImage returns the agent error (agentErr) separately from the caller-facing err,
-// so ArtistImageResult can tell "agent errored" apart from "definitively no image".
-func (e *provider) artistImage(ctx context.Context, id string) (u *url.URL, agentErr error, err error) {
-	artist, err := e.getArtist(ctx, id)
-	if err != nil {
-		return nil, nil, err
-	}
-
-	imageUrl := artist.ArtistImageUrl()
-	if imageUrl == "" {
-		// No cached URL — must fetch from external source synchronously
-		agentErr = e.callGetImage(ctx, e.ag, &artist)
-		if utils.IsCtxDone(ctx) {
-			log.Warn(ctx, "ArtistImage call canceled", ctx.Err())
-			return nil, agentErr, 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, agentErr, model.ErrNotFound
-	}
-	u, err = url.Parse(imageUrl)
-	return u, agentErr, err
-}
-
-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 string, count int) (model.MediaFiles, error) {
 	artist, err := e.findArtistByName(ctx, artistName)
 	if err != nil {

core/external/provider_albumimage_test.go

@@ -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)

core/external/provider_artistimage_test.go

@@ -1,469 +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"))
-	})
-
-	Describe("ArtistImageResult", func() {
-		It("returns the real agent error on a transient failure, not ErrNotFound", func() {
-			agentErr := errors.New("agent timed out")
-			mockImageAgent.Mock = mock.Mock{}
-			mockImageAgent.On("GetArtistImages", ctx, "artist-1", "Artist One", "").Return(nil, agentErr).Once()
-
-			imgURL, err := provider.ArtistImageResult(ctx, "artist-1")
-
-			Expect(err).To(MatchError(agentErr))
-			Expect(err).ToNot(MatchError(model.ErrNotFound))
-			Expect(imgURL).To(BeNil())
-		})
-
-		It("returns ErrNotFound when the agent definitively has no image", func() {
-			mockImageAgent.Mock = mock.Mock{}
-			mockImageAgent.On("GetArtistImages", ctx, "artist-1", "Artist One", "").Return(nil, agents.ErrNotFound).Once()
-
-			imgURL, err := provider.ArtistImageResult(ctx, "artist-1")
-
-			Expect(err).To(MatchError(model.ErrNotFound))
-			Expect(imgURL).To(BeNil())
-		})
-
-		It("returns ErrNotFound when the agent returns no images without error", func() {
-			mockImageAgent.Mock = mock.Mock{}
-			mockImageAgent.On("GetArtistImages", ctx, "artist-1", "Artist One", "").Return([]agents.ExternalImage{}, nil).Once()
-
-			imgURL, err := provider.ArtistImageResult(ctx, "artist-1")
-
-			Expect(err).To(MatchError(model.ErrNotFound))
-			Expect(imgURL).To(BeNil())
-		})
-
-		It("returns the largest image URL on success", func() {
-			expectedURL, _ := url.Parse("http://example.com/large.jpg")
-
-			imgURL, err := provider.ArtistImageResult(ctx, "artist-1")
-
-			Expect(err).ToNot(HaveOccurred())
-			Expect(imgURL).To(Equal(expectedURL))
-		})
-	})
-
-	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)

core/image_upload.go

@@ -18,6 +18,9 @@ import (
 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 clears an item's resolved state and re-queues it at Bump priority. Callers
+	// must invoke it AFTER persisting the new filename, so the worker never resolves the old one.
+	EnqueueArtwork(ctx context.Context, entityType, entityID string)
 }
 
 // MaxImageUploadSize returns the configured MaxImageUploadSize in bytes, or the built-in default
@@ -30,10 +33,20 @@ func MaxImageUploadSize() int64 {
 	return int64(size)
 }
 
-type imageUploadService struct{}
+// uploadEntityKind maps an upload's entity type to its artwork kind prefix, so a
+// successful upload can clear and re-queue that item's artwork state.
+var uploadEntityKind = map[string]string{
+	consts.EntityArtist:   model.KindArtistArtwork.Prefix(),
+	consts.EntityPlaylist: model.KindPlaylistArtwork.Prefix(),
+	consts.EntityRadio:    model.KindRadioArtwork.Prefix(),
+}
 
-func NewImageUploadService() ImageUploadService {
-	return &imageUploadService{}
+type imageUploadService struct {
+	ds model.DataStore
+}
+
+func NewImageUploadService(ds model.DataStore) ImageUploadService {
+	return &imageUploadService{ds: ds}
 }
 
 func (s *imageUploadService) SetImage(ctx context.Context, entityType string, entityID string, name string, oldPath string, reader io.Reader, ext string) (string, error) {
@@ -61,10 +74,26 @@ 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
 }
 
+// EnqueueArtwork clears the item's resolved state and re-queues it at Bump priority: the
+// upload is now the top-priority source, so the worker re-resolves and the UI swaps.
+func (s *imageUploadService) EnqueueArtwork(ctx context.Context, entityType, id string) {
+	kind, ok := uploadEntityKind[entityType]
+	if !ok {
+		return
+	}
+	if err := s.ds.Artwork(ctx).DeleteForItem(kind, id); err != nil {
+		log.Warn(ctx, "Could not clear artwork state after upload", "kind", kind, "id", id, err)
+	}
+	item := model.ArtworkQueueItem{ItemKind: kind, ItemID: id, ImageType: model.ImageTypePrimary,
+		Priority: model.ArtworkPriorityBump}
+	if err := s.ds.ArtworkQueue(ctx).Enqueue(item); err != nil {
+		log.Warn(ctx, "Could not enqueue artwork after upload", "kind", kind, "id", id, err)
+	}
+}
+
 func (s *imageUploadService) RemoveImage(ctx context.Context, path string) error {
 	if path == "" {
 		return nil

core/image_upload_test.go

@@ -10,6 +10,8 @@ import (
 	"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"
 )
@@ -17,12 +19,17 @@ import (
 var _ = Describe("ImageUploadService", func() {
 	var svc core.ImageUploadService
 	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 = core.NewImageUploadService(ds)
 	})
 
 	Describe("SetImage", func() {
@@ -69,6 +76,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("ar", "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("ar", "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() {

core/playlists/import_test.go

@@ -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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(ds))
 			mockLibRepo.SetData([]model.Library{{ID: 1, Path: "/music"}, {ID: 2, Path: "/new"}})
 			ctx = request.WithUser(ctx, model.User{ID: "123"})
 		})

core/playlists/playlists.go

@@ -57,6 +57,7 @@ type Playlists interface {
 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
 }

core/playlists/playlists_test.go

@@ -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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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, core.NewImageUploadService(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("pl", "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")

core/playlists/rest_adapter_test.go

@@ -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, core.NewImageUploadService(ds))
 		})
 
 		Describe("Save", func() {

model/album.go

@@ -13,6 +13,7 @@ import (
 
 type Album struct {
 	Annotations `structs:"-" hash:"ignore"`
+	ItemImage   `structs:"-" json:"-" hash:"ignore"`
 
 	ID            string `structs:"id" json:"id"`
 	LibraryID     int    `structs:"library_id" json:"libraryId"`

model/artist.go

@@ -11,6 +11,7 @@ import (
 
 type Artist struct {
 	Annotations `structs:"-"`
+	ItemImage   `structs:"-" json:"-"`
 
 	ID string `structs:"id" json:"id"`
 

model/artwork.go

@@ -15,6 +15,13 @@ type Artwork struct {
 
 const ImageTypePrimary = "primary"
 
+// ItemImage is per-entity artwork state hydrated at query time; never persisted
+// (structs:"-" keeps it out of upserts) nor exposed via the native API (json:"-").
+type ItemImage struct {
+	ImageHash   string `structs:"-" json:"-"`
+	ImageAbsent bool   `structs:"-" json:"-"`
+}
+
 // ItemArtwork is an entity's resolved artwork state. Hash=="" means known absent.
 type ItemArtwork struct {
 	ItemKind  string `structs:"item_kind"`
@@ -24,7 +31,7 @@ type ItemArtwork struct {
 	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 at resolution; 0 when there is no SourcePath.
+	// RefMtime is SourcePath's mtime (unix-nanoseconds) at resolution; 0 when there is no SourcePath.
 	RefMtime int64 `structs:"ref_mtime"`
 	// attempted_at/updated_at are nullable in the schema but always set by PutItemArtwork;
 	// raw inserts must set them too, since these non-pointer time.Time fields fail to scan NULL.
@@ -73,6 +80,8 @@ type ArtworkRepository interface {
 	GetItemArtwork(kind, id, imageType string) (*ItemArtwork, error)
 	PutItemArtwork(ia *ItemArtwork) error
 	DeleteForItem(kind, id string) error
+	// DeleteForItems removes state rows for the given ids of one kind, in chunks.
+	DeleteForItems(kind string, ids []string) error
 	// GetInfoForItems hydrates a page: one batched query, item_artwork joined to artwork.
 	GetInfoForItems(kind string, ids []string) (map[string]ItemArtworkInfo, error)
 	// GetAllMimes returns hash -> current mime for every stored artwork, for sweep retention checks.
@@ -82,8 +91,12 @@ type ArtworkRepository interface {
 }
 
 type ArtworkQueueRepository interface {
-	// Enqueue upserts; an existing row keeps the higher of the two priorities.
+	// Enqueue upserts; an existing row keeps the higher of the two priorities and has its
+	// retry_at reset (a detected change wants immediate re-resolution).
 	Enqueue(items ...ArtworkQueueItem) error
+	// EnqueueBump upserts like Enqueue but preserves an existing row's retry_at, so a
+	// request-triggered read-through never resets a failed resolution's backoff.
+	EnqueueBump(items ...ArtworkQueueItem) error
 	// DequeueBatch returns up to n items with retry_at <= now, priority desc, enqueued_at asc.
 	DequeueBatch(n int) ([]ArtworkQueueItem, error)
 	// MarkFailed increments attempts and pushes retry_at into the future.

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"}
@@ -38,7 +43,8 @@ var artworkKindMap = map[string]Kind{
 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 +52,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 +81,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 +134,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}
 }

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"))

model/mediafile.go

@@ -24,6 +24,7 @@ import (
 type MediaFile struct {
 	Annotations  `structs:"-" hash:"ignore"`
 	Bookmarkable `structs:"-" hash:"ignore"`
+	ItemImage    `structs:"-" json:"-" hash:"ignore"`
 
 	ID          string `structs:"id"  json:"id" hash:"ignore"`
 	PID         string `structs:"pid" json:"-" hash:"ignore"`
@@ -139,13 +140,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)
+		id := NewArtworkID(KindDiscArtwork, DiscArtworkID(mf.AlbumID, mf.DiscNumber), nil)
+		id.Hash = mf.ImageHash
+		return id
 	}
 	return mf.AlbumCoverArtID()
 }
 
 func (mf MediaFile) AlbumCoverArtID() ArtworkID {
-	return artworkIDFromAlbum(Album{ID: mf.AlbumID})
+	return artworkIDFromAlbum(Album{ID: mf.AlbumID, ItemImage: mf.ItemImage})
 }
 
 func (mf MediaFile) StructuredLyrics() (LyricList, error) {

model/playlist.go

@@ -13,6 +13,7 @@ import (
 
 type Playlist struct {
 	Annotations `structs:"-"`
+	ItemImage   `structs:"-" json:"-"`
 
 	ID               string         `structs:"id" json:"id"`
 	Name             string         `structs:"name" json:"name"`

model/radio.go

@@ -7,6 +7,8 @@ import (
 )
 
 type Radio struct {
+	ItemImage `structs:"-" json:"-"`
+
 	ID            string    `structs:"id"              json:"id"`
 	StreamUrl     string    `structs:"stream_url"      json:"streamUrl"`
 	Name          string    `structs:"name"            json:"name"`

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())
 		})
 	})
 

persistence/album_repository.go

@@ -251,7 +251,21 @@ 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
+}
+
+// hydrateArtwork fills each album's ImageHash/ImageAbsent from one batched item_artwork lookup.
+func (r *albumRepository) hydrateArtwork(albums model.Albums) {
+	if len(albums) == 0 {
+		return
+	}
+	ids := slice.Map(albums, func(a model.Album) string { return a.ID })
+	infos := hydrateItemImages(r.ctx, r.db, model.KindAlbumArtwork.Prefix(), ids)
+	for i := range albums {
+		applyItemImage(infos, albums[i].ID, &albums[i].ItemImage)
+	}
 }
 
 // GetAllIDs returns just the album IDs for the same row set as GetAll, skipping the
@@ -414,7 +428,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) {

persistence/artist_repository.go

@@ -250,6 +250,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,6 +262,7 @@ func (r *artistRepository) GetAll(options ...model.QueryOptions) (model.Artists,
 		return nil, err
 	}
 	res := dba.toModels()
+	r.hydrateArtwork(res)
 	return res, err
 }
 
@@ -273,6 +275,18 @@ func (r *artistRepository) GetAllIDs(options ...model.QueryOptions) ([]string, e
 	return ids, err
 }
 
+// hydrateArtwork fills each artist's ImageHash/ImageAbsent from one batched item_artwork lookup.
+func (r *artistRepository) hydrateArtwork(artists model.Artists) {
+	if len(artists) == 0 {
+		return
+	}
+	ids := slice.Map(artists, func(a model.Artist) string { return a.ID })
+	infos := hydrateItemImages(r.ctx, r.db, model.KindArtistArtwork.Prefix(), ids)
+	for i := range artists {
+		applyItemImage(infos, artists[i].ID, &artists[i].ItemImage)
+	}
+}
+
 func (r *artistRepository) GetCursor(options ...model.QueryOptions) (model.ArtistCursor, error) {
 	sel := r.selectArtist(options...)
 	cursor, err := queryWithStableResults[dbArtist](r.sqlRepository, sel)
@@ -644,7 +658,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

persistence/artwork_hydration.go

@@ -0,0 +1,31 @@
+package persistence
+
+import (
+	"context"
+
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+	"github.com/pocketbase/dbx"
+)
+
+// hydrateItemImages returns per-item artwork info for a fetched page via one batched query per kind
+// (never a join, see spec §6). On error it logs and returns an empty map so the page still renders.
+func hydrateItemImages(ctx context.Context, db dbx.Builder, kind string, 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.ImageHash = info.Hash
+		img.ImageAbsent = info.Absent()
+	}
+}

persistence/artwork_hydration_test.go

@@ -0,0 +1,305 @@
+package persistence
+
+import (
+	"context"
+
+	"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/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"github.com/pocketbase/dbx"
+)
+
+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
+
+			byID := map[string]model.Album{}
+			all, err := repo.GetAll()
+			Expect(err).ToNot(HaveOccurred())
+			for _, a := range all {
+				byID[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())
+
+			// No item_artwork rows exist, so a fresh read must observe zero values.
+			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
+
+			byID := map[string]model.Artist{}
+			all, err := repo.GetAll()
+			Expect(err).ToNot(HaveOccurred())
+			for _, a := range all {
+				byID[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, "")
+
+			byID := map[string]model.Playlist{}
+			all, err := repo.GetAll()
+			Expect(err).ToNot(HaveOccurred())
+			for _, p := range all {
+				byID[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"))
+		})
+	})
+
+	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, "")
+
+			byID := map[string]model.Radio{}
+			all, err := repo.GetAll()
+			Expect(err).ToNot(HaveOccurred())
+			for _, rd := range all {
+				byID[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 {
+			byID := map[string]model.MediaFile{}
+			all, err := repo.GetAll()
+			Expect(err).ToNot(HaveOccurred())
+			for _, mf := range all {
+				byID[mf.ID] = mf
+			}
+			return byID
+		}
+
+		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()
+
+			// eligible + own hash -> own hash
+			Expect(byID["1001"].ImageHash).To(Equal("mfh1001xxxxxxxx"))
+			Expect(byID["1001"].ImageAbsent).To(BeFalse())
+			// eligible + embedded absent -> falls through to album 102 info
+			Expect(byID["1002"].ImageHash).To(Equal("alh102xxxxxxxxxx"))
+			Expect(byID["1002"].ImageAbsent).To(BeFalse())
+			// not eligible (no embedded cover) -> album 103 info (known-absent)
+			Expect(byID["1003"].ImageHash).To(BeEmpty())
+			Expect(byID["1003"].ImageAbsent).To(BeTrue())
+			// not eligible, album has no row -> zero values (unresolved)
+			Expect(byID["2002"].ImageHash).To(BeEmpty())
+			Expect(byID["2002"].ImageAbsent).To(BeFalse())
+		})
+
+		It("keeps an eligible file optimistic when its own art is unresolved, even if the album is absent", func() {
+			// 1004 is eligible (has embedded cover) with no mf state row yet; its album (103) is absent.
+			setCover("1004", true)
+			DeferCleanup(func() { setCover("1004", false) })
+			putInfo("al", "103", "") // album known-absent
+
+			byID := getByID()
+
+			// The track's own embedded art is still unresolved, so it must NOT inherit the album's
+			// absence: coverArt stays requestable so serving can extract the embedded art.
+			Expect(byID["1004"].ImageAbsent).To(BeFalse())
+			Expect(byID["1004"].ImageHash).To(BeEmpty())
+			// A non-eligible sibling on the same absent album still inherits the 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()
+
+			// 2002 is multi-disc (DiscNumber>0); CoverArtID emits a dc- id served from disc art of
+			// unknown identity, so it must not advertise the album's hash as its content-version.
+			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()
+
+			// 2002 is a multi-disc track (DiscNumber>0); CoverArtID points at disc art, which
+			// resolves provisionally, so it must never inherit the album's absence.
+			Expect(byID["2002"].ImageAbsent).To(BeFalse())
+			Expect(byID["2002"].ImageHash).To(BeEmpty())
+		})
+
+		It("uses the album hash for an eligible file whose own art is unresolved but album is found", 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(Equal("alh103found11111"))
+		})
+
+		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"))
+		})
+	})
+})

persistence/artwork_queue_repository.go

@@ -26,6 +26,18 @@ func NewArtworkQueueRepository(ctx context.Context, db dbx.Builder) model.Artwor
 }
 
 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`, items)
+}
+
+// EnqueueBump raises priority like Enqueue but leaves an existing row's retry_at intact, so a
+// request-triggered read-through never resets a failed resolution's backoff. New rows insert eligible.
+func (r *artworkQueueRepository) EnqueueBump(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) enqueue(conflict string, items []model.ArtworkQueueItem) error {
 	now := time.Now()
 	for chunk := range slices.Chunk(items, enqueueChunkSize) {
 		ins := Insert(r.tableName).Columns("item_kind", "item_id", "image_type", "priority", "attempts", "retry_at", "enqueued_at")
@@ -35,8 +47,7 @@ func (r *artworkQueueRepository) Enqueue(items ...model.ArtworkQueueItem) error
 			}
 			ins = ins.Values(it.ItemKind, it.ItemID, it.ImageType, it.Priority, 0, now, now)
 		}
-		ins = ins.Suffix(`ON CONFLICT (item_kind, item_id, image_type) DO UPDATE SET
-			priority = MAX(priority, excluded.priority), retry_at = excluded.retry_at`)
+		ins = ins.Suffix(conflict)
 		if _, err := r.executeSQL(ins); err != nil {
 			return err
 		}

persistence/artwork_queue_repository_test.go

@@ -19,6 +19,7 @@ var _ = Describe("ArtworkQueueRepository", func() {
 
 	BeforeEach(func() {
 		clearArtworkTables()
+		DeferCleanup(clearArtworkTables)
 		repo = NewArtworkQueueRepository(context.Background(), GetDBXBuilder())
 	})
 
@@ -40,6 +41,30 @@ var _ = Describe("ArtworkQueueRepository", func() {
 		Expect(got[0].Priority).To(Equal(model.ArtworkPriorityBump))
 	})
 
+	It("EnqueueBump raises priority without resetting a backing-off row's retry_at", func() {
+		Expect(repo.Enqueue(item("al", "b1", model.ArtworkPriorityScan))).To(Succeed())
+		// Push retry_at into the future so the row is backing off and hidden from dequeue.
+		Expect(repo.MarkFailed("al", "b1", model.ImageTypePrimary, time.Now().Add(time.Hour))).To(Succeed())
+		Expect(repo.DequeueBatch(10)).To(BeEmpty())
+
+		// A request-triggered bump raises priority but must leave the backoff intact.
+		Expect(repo.EnqueueBump(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("EnqueueBump inserts a brand-new row eligible immediately", func() {
+		Expect(repo.EnqueueBump(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())
 		Expect(repo.MarkFailed("al", "f1", model.ImageTypePrimary, time.Now().Add(time.Hour))).To(Succeed())
@@ -126,18 +151,20 @@ var _ = Describe("ArtworkQueueRepository", func() {
 			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(4)))
+		Expect(purged).To(Equal(int64(5)))
 
 		got, _ := repo.DequeueBatch(100)
 		ids := make([]string, 0, len(got))
 		for _, it := range got {
 			ids = append(ids, it.ItemID)
 		}
-		Expect(ids).To(ConsistOf(albumSgtPeppers.ID, artistKraftwerk.ID, plsBest.ID, radioWithHomePage.ID))
+		Expect(ids).To(ConsistOf(albumSgtPeppers.ID, artistKraftwerk.ID, plsBest.ID, radioWithHomePage.ID, songDayInALife.ID))
 	})
 
 	It("enqueues stale absent states for recheck", func() {

persistence/artwork_repository.go

@@ -120,6 +120,7 @@ var danglingItemArtworkKinds = map[string]string{
 	"ar": "artist",
 	"pl": "playlist",
 	"ra": "radio",
+	"mf": "media_file",
 }
 
 // purgeDangling deletes rows in table whose owning entity is gone, one statement per kind.
@@ -177,6 +178,15 @@ func (r *artworkRepository) DeleteForItem(kind, id string) error {
 	return r.items.delete(Eq{"item_kind": kind, "item_id": id})
 }
 
+func (r *artworkRepository) DeleteForItems(kind string, ids []string) error {
+	for chunk := range slices.Chunk(ids, artworkBatchSize) {
+		if err := r.items.delete(Eq{"item_kind": kind, "item_id": chunk}); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
 func (r *artworkRepository) GetInfoForItems(kind string, ids []string) (map[string]model.ItemArtworkInfo, error) {
 	res := map[string]model.ItemArtworkInfo{}
 	for chunk := range slices.Chunk(ids, artworkBatchSize) {

persistence/artwork_repository_test.go

@@ -25,6 +25,7 @@ var _ = Describe("ArtworkRepository", func() {
 
 	BeforeEach(func() {
 		clearArtworkTables()
+		DeferCleanup(clearArtworkTables)
 		repo = NewArtworkRepository(context.Background(), GetDBXBuilder())
 	})
 
@@ -146,16 +147,19 @@ var _ = Describe("ArtworkRepository", func() {
 			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.PurgeDanglingItemArtwork()
 			Expect(err).ToNot(HaveOccurred())
-			Expect(purged).To(Equal(int64(4)))
+			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},
 			} {
 				_, err := repo.GetItemArtwork(kept.ItemKind, kept.ItemID, model.ImageTypePrimary)
 				Expect(err).ToNot(HaveOccurred())
@@ -165,6 +169,7 @@ var _ = Describe("ArtworkRepository", func() {
 				{ItemKind: "ar", ItemID: "no-such-artist"},
 				{ItemKind: "pl", ItemID: "no-such-playlist"},
 				{ItemKind: "ra", ItemID: "no-such-radio"},
+				{ItemKind: "mf", ItemID: "no-such-mediafile"},
 			} {
 				_, err := repo.GetItemArtwork(gone.ItemKind, gone.ItemID, model.ImageTypePrimary)
 				Expect(err).To(MatchError(model.ErrNotFound))
@@ -229,5 +234,26 @@ var _ = Describe("ArtworkRepository", func() {
 			_, err := repo.GetItemArtwork("pl", "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("mf", ids)).To(Succeed())
+
+			for _, id := range ids {
+				_, err := repo.GetItemArtwork("mf", id, model.ImageTypePrimary)
+				Expect(err).To(MatchError(model.ErrNotFound))
+			}
+			kept, err := repo.GetItemArtwork("mf", "keep", model.ImageTypePrimary)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(kept.ItemID).To(Equal("keep"))
+		})
 	})
 })

persistence/e2e/e2e_suite_test.go

@@ -14,7 +14,6 @@ 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/metrics"
 	"github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/core/storage/storagetest"
@@ -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, core.NewImageUploadService(initDS)), metrics.NewNoopInstance())
 	_, err = s.ScanAll(ctx, true)
 	Expect(err).ToNot(HaveOccurred())
 

persistence/mediafile_repository.go

@@ -218,7 +218,58 @@ 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
+}
+
+// hydrateArtwork mirrors MediaFile.CoverArtID: an embedded-eligible file with resolved own art uses
+// it, else it falls back to the album's. Two batched item_artwork lookups per page, never a join.
+func (r *mediaFileRepository) hydrateArtwork(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(r.ctx, r.db, model.KindAlbumArtwork.Prefix(), albumIDs)
+	mfInfos := hydrateItemImages(r.ctx, r.db, model.KindMediaFileArtwork.Prefix(), eligibleIDs)
+	for i := range mfs {
+		mf := &mfs[i]
+		eligible := mf.HasCoverArt && conf.Server.EnableMediaFileCoverArt
+		ownInfo, ownResolved := mfInfos[mf.ID]
+		if eligible && ownResolved && !ownInfo.Absent() {
+			mf.ImageHash = ownInfo.Hash // own resolved art wins
+			continue
+		}
+		// Fallback (see MediaFile.CoverArtID): inherit a found album hash for optimistic caching,
+		// but only for a single-disc track. A multi-disc track emits a dc- id served from
+		// disc-specific art of unknown identity, so stamping the album hash would advertise a
+		// wrong content-version; leave it bare (the served response still carries a correct ETag).
+		if album, ok := albumInfos[mf.AlbumID]; ok && !album.Absent() {
+			if mf.DiscNumber == 0 {
+				mf.ImageHash = album.Hash
+			}
+			continue
+		}
+		// Nothing found. Mark absent only when serving would definitively yield a placeholder:
+		// a single-disc track whose album is known-absent and whose own art won't resolve. A
+		// multi-disc track resolves disc art provisionally (never known-absent), and an
+		// eligible-but-unresolved track can still extract its own embedded art — both stay
+		// requestable.
+		if mf.DiscNumber > 0 {
+			continue
+		}
+		ownWontResolve := !eligible || (ownResolved && ownInfo.Absent())
+		if album, ok := albumInfos[mf.AlbumID]; ok && album.Absent() && ownWontResolve {
+			mf.ImageAbsent = true
+		}
+	}
 }
 
 // GetRandom uses two passes so the random sort runs over a narrow rowid index instead of the
@@ -252,7 +303,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) {
@@ -487,7 +540,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) {

persistence/playlist_repository.go

@@ -14,6 +14,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"
 )
 
@@ -131,6 +132,7 @@ 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; refreshCounters enqueues by it
 	return r.refreshCounters(&pls.Playlist)
 }
 
@@ -172,7 +174,21 @@ 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
+}
+
+// hydrateArtwork fills each playlist's ImageHash/ImageAbsent from one batched item_artwork lookup.
+func (r *playlistRepository) hydrateArtwork(playlists model.Playlists) {
+	if len(playlists) == 0 {
+		return
+	}
+	ids := slice.Map(playlists, func(p model.Playlist) string { return p.ID })
+	infos := hydrateItemImages(r.ctx, r.db, model.KindPlaylistArtwork.Prefix(), ids)
+	for i := range playlists {
+		applyItemImage(infos, playlists[i].ID, &playlists[i].ItemImage)
+	}
 }
 
 func (r *playlistRepository) GetAll(options ...model.QueryOptions) (model.Playlists, error) {
@@ -186,6 +202,7 @@ func (r *playlistRepository) GetAll(options ...model.QueryOptions) (model.Playli
 	for i, p := range res {
 		playlists[i] = p.Playlist
 	}
+	r.hydrateArtwork(playlists)
 	return playlists, err
 }
 
@@ -230,6 +247,7 @@ func (r *playlistRepository) GetPlaylists(mediaFileId string) (model.Playlists,
 	for i, p := range res {
 		playlists[i] = p.Playlist
 	}
+	r.hydrateArtwork(playlists)
 	return playlists, nil
 }
 
@@ -307,6 +325,13 @@ func (r *playlistRepository) refreshCounters(pls *model.Playlist) error {
 	pls.SongCount = int(res.Count)
 	pls.Duration = res.Duration
 	pls.Size = int64(res.Size)
+	// The generated 2x2 grid depends on the track set, so re-resolve the cover whenever it
+	// changes. No clear: the old cover keeps serving until the worker rebuilds (no flicker).
+	item := model.ArtworkQueueItem{ItemKind: "pl", ItemID: pls.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", pls.ID, err)
+	}
 	return nil
 }
 

persistence/playlist_repository_test.go

@@ -260,6 +260,34 @@ 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")
+	})
+
+	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()

persistence/radio_repository.go

@@ -10,6 +10,7 @@ import (
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/id"
+	"github.com/navidrome/navidrome/utils/slice"
 	"github.com/pocketbase/dbx"
 )
 
@@ -49,14 +50,35 @@ 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) {
+	if len(radios) == 0 {
+		return
+	}
+	ids := slice.Map(radios, func(rd model.Radio) string { return rd.ID })
+	infos := hydrateItemImages(r.ctx, r.db, model.KindRadioArtwork.Prefix(), ids)
+	for i := range radios {
+		applyItemImage(infos, radios[i].ID, &radios[i].ItemImage)
+	}
 }
 
 // GetAllIDs returns just the radio IDs. Used by bulk enumeration (artwork backfill).
@@ -84,9 +106,10 @@ func (r *radioRepository) Put(radio *model.Radio, colsToUpdate ...string) error
 	if err != nil {
 		return err
 	}
-	// Enqueue artwork resolution for the created/updated radio. Never fails the save.
+	// 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: "ra", ItemID: radio.ID, ImageType: model.ImageTypePrimary,
-		Priority: model.ArtworkPriorityScan}
+		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)
 	}

persistence/radio_repository_test.go

@@ -140,7 +140,7 @@ var _ = Describe("RadioRepository", func() {
 				Expect(queued).To(ContainElement(SatisfyAll(
 					HaveField("ItemKind", "ra"),
 					HaveField("ItemID", created.ID),
-					HaveField("Priority", model.ArtworkPriorityScan),
+					HaveField("Priority", model.ArtworkPriorityBump),
 				)))
 			})
 		})

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

scanner/controller_test.go

@@ -6,7 +6,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"
 	"github.com/navidrome/navidrome/db"
@@ -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, core.NewImageUploadService(ds)), metrics.NewNoopInstance())
 		})
 
 		It("includes last scan error", func() {

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,6 @@ 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
 
@@ -373,7 +368,6 @@ 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: "ar", ItemID: entry.artists[i].ID, ImageType: model.ImageTypePrimary,
 					Priority: model.ArtworkPriorityScan,
@@ -389,7 +383,6 @@ 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: "al", ItemID: entry.albums[i].ID, ImageType: model.ImageTypePrimary,
 					Priority: model.ArtworkPriorityScan,
@@ -406,6 +399,17 @@ 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 := make([]string, len(entry.tracks))
+			for i := range entry.tracks {
+				trackIDs[i] = entry.tracks[i].ID
+			}
+			if err := tx.Artwork(p.ctx).DeleteForItems("mf", 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...)
@@ -438,13 +442,6 @@ func (p *phaseFolders) persistChanges(entry *folderEntry) (*folderEntry, error)
 		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
 }
 

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,6 @@ 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: "pl", ItemID: pls.ID, ImageType: model.ImageTypePrimary,
 			Priority: model.ArtworkPriorityScan}
 		if err := p.ds.ArtworkQueue(p.ctx).Enqueue(item); err != nil {

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() {

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):

scanner/scanner_benchmark_test.go

@@ -13,7 +13,6 @@ import (
 	"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"
 	"github.com/navidrome/navidrome/core/storage/storagetest"
@@ -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, core.NewImageUploadService(ds)), metrics.NewNoopInstance())
 
 	fs := storagetest.FakeFS{}
 	storagetest.Register("fake", &fs)

scanner/scanner_multilibrary_test.go

@@ -12,7 +12,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"
 	"github.com/navidrome/navidrome/core/storage/storagetest"
@@ -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, core.NewImageUploadService(ds)), metrics.NewNoopInstance())
 
 		// Create two test libraries (let DB auto-assign IDs)
 		lib1 = model.Library{Name: "Rock Collection", Path: "rock:///music"}

scanner/scanner_selective_test.go

@@ -11,7 +11,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"
 	"github.com/navidrome/navidrome/core/storage/storagetest"
@@ -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, core.NewImageUploadService(ds)), metrics.NewNoopInstance())
 
 		lib = model.Library{ID: 1, Name: "Fake Library", Path: "fake:///music"}
 		Expect(ds.Library(ctx).Put(&lib)).To(Succeed())

scanner/scanner_test.go

@@ -14,7 +14,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"
 	"github.com/navidrome/navidrome/core/storage/storagetest"
@@ -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, core.NewImageUploadService(ds)), metrics.NewNoopInstance())
 
 		lib = model.Library{ID: 1, Name: "Fake Library", Path: "fake:///music"}
 		Expect(ds.Library(ctx).Put(&lib)).To(Succeed())
@@ -210,6 +209,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("mf", trackID, model.ImageTypePrimary)
+				Expect(err).To(MatchError(model.ErrNotFound))
+			})
 		})
 	})
 

server/imghttp/headers.go

@@ -0,0 +1,68 @@
+// Package imghttp holds the shared HTTP caching contract for artwork responses, so the
+// subsonic, public, and jellyfin image handlers 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
+// (in which case the caller must not write a body). requestedHash is the hash the client asserted
+// (id suffix / JWT payload / jellyfin tag param), or "" when the request carried no hash.
+func WriteImageHeaders(w http.ResponseWriter, r *http.Request, img *artwork.Image, requestedHash string) (wrote304 bool) {
+	h := w.Header()
+	// Placeholders are transient stand-ins for not-yet-resolved art: never cached, no validators.
+	if img.Placeholder {
+		h.Set("Cache-Control", "no-store")
+		return false
+	}
+
+	// The validator identifies the served representation (resized/re-encoded bytes version it via
+	// ETag), so a CoverArtQuality/EnableWebPEncoding change invalidates a revalidating client's
+	// cache. Falls back to the pixel hash for full-size originals (bytes == the hash).
+	etag := img.ETag
+	if etag == "" {
+		etag = img.Hash
+	}
+	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 exact current pixel hash; bare/legacy/mismatched
+	// requests get cheap ETag revalidation instead, which fixes stale art after re-resolution.
+	if requestedHash != "" && requestedHash == img.Hash {
+		h.Set("Cache-Control", "public, max-age=31536000, immutable")
+	} else {
+		h.Set("Cache-Control", "public, no-cache")
+	}
+
+	if ifNoneMatch(r.Header.Get("If-None-Match"), etag) {
+		w.WriteHeader(http.StatusNotModified)
+		return true
+	}
+	return false
+}
+
+// ifNoneMatch reports whether the If-None-Match header asserts the given hash, using weak
+// comparison (RFC 9110): "*" matches any current representation and W/ prefixes are ignored.
+func ifNoneMatch(header, hash string) bool {
+	header = strings.TrimSpace(header)
+	if header == "" {
+		return false
+	}
+	if header == "*" {
+		return true
+	}
+	for _, tag := range strings.Split(header, ",") {
+		tag = strings.TrimSpace(tag)
+		tag = strings.TrimPrefix(tag, "W/")
+		if strings.Trim(tag, `"`) == hash {
+			return true
+		}
+	}
+	return false
+}

server/imghttp/headers_test.go

@@ -0,0 +1,105 @@
+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}
+}
+
+// resized carries a representation ETag distinct from the pixel hash (as a resized/re-encoded
+// response does), 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,
+	}
+}
+
+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"}),
+	)
+})