update

core/artwork/artwork.go

@@ -0,0 +1,130 @@
+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)
+		default:
+			return nil, ErrUnavailable
+		}
+	}
+	return artReader, err
+}

core/artwork/artwork_internal_test.go

@@ -0,0 +1,328 @@
+package artwork
+
+import (
+	"context"
+	"errors"
+	"image"
+	"image/jpeg"
+	"image/png"
+	"io"
+	"os"
+	"path/filepath"
+
+	"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 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{}
+		ds = &tests.MockDataStore{
+			MockedTranscoding: &tests.MockTranscodingRepo{},
+			MockedFolder:      folderRepo,
+		}
+		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"}}
+		alExternalNotFound = model.Album{ID: "555", Name: "External not found", FolderIDs: []string{"f2"}}
+		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"),
+			)
+		})
+	})
+	Describe("artistArtworkReader", func() {
+		Context("Multiple covers", func() {
+			BeforeEach(func() {
+				folderRepo.result = []model.Folder{{
+					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(path).To(Equal(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,
+				})
+				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"))
+			})
+		})
+	})
+	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 a 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 a 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(format string, landscape bool, size int) {
+					coverFileName := "cover." + format
+					dirName := createImage(format, landscape, size)
+					alCover = model.Album{
+						ID:        "444",
+						Name:      "Only external",
+						FolderIDs: []string{"tmp"},
+					}
+					folderRepo.result = []model.Folder{{Path: dirName, ImageFiles: []string{coverFileName}}}
+					ds.Album(ctx).(*tests.MockAlbumRepo).SetData(model.Albums{
+						alCover,
+					})
+
+					conf.Server.CoverArtPriority = coverFileName
+					r, _, err := aw.Get(context.Background(), alCover.CoverArtID(), size, true)
+					Expect(err).ToNot(HaveOccurred())
+
+					img, format, err := image.Decode(r)
+					Expect(err).ToNot(HaveOccurred())
+					Expect(format).To(Equal("png"))
+					Expect(img.Bounds().Size().X).To(Equal(size))
+					Expect(img.Bounds().Size().Y).To(Equal(size))
+				},
+				Entry("portrait png image", "png", false, 200),
+				Entry("landscape png image", "png", true, 200),
+				Entry("portrait jpg image", "jpg", false, 200),
+				Entry("landscape jpg image", "jpg", true, 200),
+			)
+		})
+	})
+})
+
+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

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

core/artwork/artwork_test.go

@@ -0,0 +1,57 @@
+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/cache_warmer.go

@@ -0,0 +1,163 @@
+package artwork
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"maps"
+	"slices"
+	"sync"
+	"time"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
+	"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 in the UICoverArtSize constant.
+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),
+	}
+
+	// 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{}
+}
+
+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, 2, 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()
+
+	r, _, err := a.artwork.Get(ctx, id, consts.UICoverArtSize, true)
+	if err != nil {
+		return fmt.Errorf("caching id='%s': %w", id, err)
+	}
+	defer r.Close()
+	_, err = io.Copy(io.Discard, r)
+	if err != nil {
+		return err
+	}
+	return nil
+}
+
+func NoopCacheWarmer() CacheWarmer {
+	return &noopCacheWarmer{}
+}
+
+type noopCacheWarmer struct{}
+
+func (a *noopCacheWarmer) PreCache(model.ArtworkID) {}

core/artwork/cache_warmer_test.go

@@ -0,0 +1,222 @@
+package artwork
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"strings"
+	"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 := 0; i < 5; i++ {
+				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))
+		})
+	})
+})
+
+type mockArtwork struct {
+	err error
+}
+
+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
+	}
+	return io.NopCloser(strings.NewReader("test")), time.Now(), nil
+}
+
+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/image_cache.go

@@ -0,0 +1,44 @@
+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(),
+	)
+}
+
+type imageCache struct {
+	cache.FileCache
+}
+
+func GetImageCache() cache.FileCache {
+	return singleton.GetInstance(func() *imageCache {
+		return &imageCache{
+			FileCache: cache.NewFileCache("Image", conf.Server.ImageCacheSize, consts.ImageCacheDir, consts.DefaultImageCacheMaxItems,
+				func(ctx context.Context, arg cache.Item) (io.Reader, error) {
+					r, _, err := arg.(artworkReader).Reader(ctx)
+					return r, err
+				}),
+		}
+	})
+}

core/artwork/reader_album.go

@@ -0,0 +1,147 @@
+package artwork
+
+import (
+	"cmp"
+	"context"
+	"crypto/md5"
+	"fmt"
+	"io"
+	"path/filepath"
+	"slices"
+	"strings"
+	"time"
+
+	"github.com/Masterminds/squirrel"
+	"github.com/maruel/natural"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/core/external"
+	"github.com/navidrome/navidrome/core/ffmpeg"
+	"github.com/navidrome/navidrome/model"
+)
+
+type albumArtworkReader struct {
+	cacheKey
+	a          *artwork
+	provider   external.Provider
+	album      model.Album
+	updatedAt  *time.Time
+	imgFiles   []string
+	rootFolder string
+}
+
+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
+	}
+	a := &albumArtworkReader{
+		a:          artwork,
+		provider:   provider,
+		album:      *al,
+		updatedAt:  imagesUpdateAt,
+		imgFiles:   imgFiles,
+		rootFolder: core.AbsolutePath(ctx, artwork.ds, al.LibraryID, ""),
+	}
+	a.cacheKey.artID = artID
+	if a.updatedAt != nil && a.updatedAt.After(al.UpdatedAt) {
+		a.cacheKey.lastUpdate = *a.updatedAt
+	} else {
+		a.cacheKey.lastUpdate = al.UpdatedAt
+	}
+	return a, nil
+}
+
+func (a *albumArtworkReader) Key() string {
+	var hash [16]byte
+	if conf.Server.EnableExternalServices {
+		hash = md5.Sum([]byte(conf.Server.Agents + conf.Server.CoverArtPriority))
+	}
+	return fmt.Sprintf(
+		"%s.%x.%t",
+		a.cacheKey.Key(),
+		hash,
+		conf.Server.EnableExternalServices,
+	)
+}
+func (a *albumArtworkReader) LastUpdated() time.Time {
+	return a.album.UpdatedAt
+}
+
+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.Split(strings.ToLower(priority), ",") {
+		pattern = strings.TrimSpace(pattern)
+		switch {
+		case pattern == "embedded":
+			embedArtPath := filepath.Join(a.rootFolder, a.album.EmbedArtPath)
+			ff = append(ff, fromTag(ctx, embedArtPath), fromFFmpegTag(ctx, ffmpeg, embedArtPath))
+		case pattern == "external":
+			ff = append(ff, fromAlbumExternalSource(ctx, a.album, a.provider))
+		case len(a.imgFiles) > 0:
+			ff = append(ff, fromExternalFile(ctx, a.imgFiles, pattern))
+		}
+	}
+	return ff
+}
+
+func loadAlbumFoldersPaths(ctx context.Context, ds model.DataStore, albums ...model.Album) ([]string, []string, *time.Time, error) {
+	var folderIDs []string
+	for _, album := range albums {
+		folderIDs = append(folderIDs, album.FolderIDs...)
+	}
+	folders, err := ds.Folder(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"folder.id": folderIDs, "missing": false}})
+	if err != nil {
+		return nil, nil, nil, err
+	}
+	var paths []string
+	var imgFiles []string
+	var updatedAt time.Time
+	for _, f := range folders {
+		path := f.AbsolutePath()
+		paths = append(paths, path)
+		if f.ImagesUpdatedAt.After(updatedAt) {
+			updatedAt = f.ImagesUpdatedAt
+		}
+		for _, img := range f.ImageFiles {
+			imgFiles = append(imgFiles, filepath.Join(path, img))
+		}
+	}
+
+	// Sort image files to ensure consistent selection of cover art
+	// This prioritizes files without numeric suffixes (e.g., cover.jpg over cover.1.jpg)
+	// by comparing base filenames without extensions
+	slices.SortFunc(imgFiles, compareImageFiles)
+
+	return paths, imgFiles, &updatedAt, nil
+}
+
+// compareImageFiles compares two image file paths for sorting.
+// It extracts the base filename (without extension) and compares case-insensitively.
+// This ensures that "cover.jpg" sorts before "cover.1.jpg" since "cover" < "cover.1".
+// Note: This function is called O(n log n) times during sorting, but in practice albums
+// typically have only 1-20 image files, making the repeated string operations negligible.
+func compareImageFiles(a, b string) int {
+	// Case-insensitive comparison
+	a = strings.ToLower(a)
+	b = strings.ToLower(b)
+
+	// Extract base filenames without extensions
+	baseA := strings.TrimSuffix(filepath.Base(a), filepath.Ext(a))
+	baseB := strings.TrimSuffix(filepath.Base(b), filepath.Ext(b))
+
+	// Compare base names first, then full paths if equal
+	return cmp.Or(
+		natural.Compare(baseA, baseB),
+		natural.Compare(a, b),
+	)
+}

core/artwork/reader_album_test.go

@@ -0,0 +1,120 @@
+package artwork
+
+import (
+	"context"
+	"path/filepath"
+	"time"
+
+	"github.com/navidrome/navidrome/model"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Album Artwork Reader", func() {
+	Describe("loadAlbumFoldersPaths", func() {
+		var (
+			ctx        context.Context
+			ds         *fakeDataStore
+			repo       *fakeFolderRepo
+			album      model.Album
+			now        time.Time
+			expectedAt time.Time
+		)
+
+		BeforeEach(func() {
+			ctx = context.Background()
+			now = time.Now().Truncate(time.Second)
+			expectedAt = now.Add(5 * time.Minute)
+
+			// Set up the test folders with image files
+			repo = &fakeFolderRepo{}
+			ds = &fakeDataStore{
+				folderRepo: repo,
+			}
+			album = model.Album{
+				ID:        "album1",
+				Name:      "Album",
+				FolderIDs: []string{"folder1", "folder2", "folder3"},
+			}
+		})
+
+		It("returns sorted image files", func() {
+			repo.result = []model.Folder{
+				{
+					Path:            "Artist/Album/Disc1",
+					ImagesUpdatedAt: expectedAt,
+					ImageFiles:      []string{"cover.jpg", "back.jpg", "cover.1.jpg"},
+				},
+				{
+					Path:            "Artist/Album/Disc2",
+					ImagesUpdatedAt: now,
+					ImageFiles:      []string{"cover.jpg"},
+				},
+				{
+					Path:            "Artist/Album/Disc10",
+					ImagesUpdatedAt: now,
+					ImageFiles:      []string{"cover.jpg"},
+				},
+			}
+
+			_, imgFiles, imagesUpdatedAt, err := loadAlbumFoldersPaths(ctx, ds, album)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(*imagesUpdatedAt).To(Equal(expectedAt))
+
+			// Check that image files are sorted by base name (without extension)
+			Expect(imgFiles).To(HaveLen(5))
+
+			// Files should be sorted by base filename without extension, then by full path
+			// "back" < "cover", so back.jpg comes first
+			// Then all cover.jpg files, sorted by path
+			Expect(imgFiles[0]).To(Equal(filepath.FromSlash("Artist/Album/Disc1/back.jpg")))
+			Expect(imgFiles[1]).To(Equal(filepath.FromSlash("Artist/Album/Disc1/cover.jpg")))
+			Expect(imgFiles[2]).To(Equal(filepath.FromSlash("Artist/Album/Disc2/cover.jpg")))
+			Expect(imgFiles[3]).To(Equal(filepath.FromSlash("Artist/Album/Disc10/cover.jpg")))
+			Expect(imgFiles[4]).To(Equal(filepath.FromSlash("Artist/Album/Disc1/cover.1.jpg")))
+		})
+
+		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(filepath.FromSlash("Artist/Album/cover.jpg")))
+			Expect(imgFiles[1]).To(Equal(filepath.FromSlash("Artist/Album/cover.1.jpg")))
+			Expect(imgFiles[2]).To(Equal(filepath.FromSlash("Artist/Album/cover.2.jpg")))
+		})
+
+		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(filepath.FromSlash("Artist/Album/BACK.jpg")))
+			Expect(imgFiles[1]).To(Equal(filepath.FromSlash("Artist/Album/cover.jpg")))
+			Expect(imgFiles[2]).To(Equal(filepath.FromSlash("Artist/Album/Folder.jpg")))
+		})
+	})
+})

core/artwork/reader_artist.go

@@ -0,0 +1,198 @@
+package artwork
+
+import (
+	"context"
+	"crypto/md5"
+	"fmt"
+	"io"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+	"time"
+
+	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/core/external"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/utils/str"
+)
+
+const (
+	// maxArtistFolderTraversalDepth defines how many directory levels to search
+	// when looking for artist images (artist folder + parent directories)
+	maxArtistFolderTraversalDepth = 3
+)
+
+type artistReader struct {
+	cacheKey
+	a            *artwork
+	provider     external.Provider
+	artist       model.Artist
+	artistFolder string
+	imgFiles     []string
+}
+
+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
+	}
+	a := &artistReader{
+		a:            artwork,
+		provider:     provider,
+		artist:       *ar,
+		artistFolder: artistFolder,
+		imgFiles:     imgFiles,
+	}
+	// 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 artistFolderLastUpdate.After(a.cacheKey.lastUpdate) {
+		a.cacheKey.lastUpdate = artistFolderLastUpdate
+	}
+	a.cacheKey.artID = artID
+	return a, nil
+}
+
+func (a *artistReader) Key() string {
+	hash := md5.Sum([]byte(conf.Server.Agents + conf.Server.Spotify.ID))
+	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) {
+	var ff = a.fromArtistArtPriority(ctx, conf.Server.ArtistArtPriority)
+	return selectImageReader(ctx, a.artID, ff...)
+}
+
+func (a *artistReader) fromArtistArtPriority(ctx context.Context, priority string) []sourceFunc {
+	var ff []sourceFunc
+	for _, pattern := range strings.Split(strings.ToLower(priority), ",") {
+		pattern = strings.TrimSpace(pattern)
+		switch {
+		case pattern == "external":
+			ff = append(ff, fromArtistExternalSource(ctx, a.artist, a.provider))
+		case strings.HasPrefix(pattern, "album/"):
+			ff = append(ff, fromExternalFile(ctx, a.imgFiles, strings.TrimPrefix(pattern, "album/")))
+		default:
+			ff = append(ff, fromArtistFolder(ctx, a.artistFolder, pattern))
+		}
+	}
+	return ff
+}
+
+func fromArtistFolder(ctx context.Context, artistFolder string, pattern string) sourceFunc {
+	return func() (io.ReadCloser, string, error) {
+		current := artistFolder
+		for i := 0; i < maxArtistFolderTraversalDepth; i++ {
+			if reader, path, err := findImageInFolder(ctx, current, pattern); err == nil {
+				return reader, path, nil
+			}
+
+			parent := filepath.Dir(current)
+			if parent == current {
+				break
+			}
+			current = parent
+		}
+		return nil, "", fmt.Errorf(`no matches for '%s' in '%s' or its parent directories`, pattern, artistFolder)
+	}
+}
+
+func findImageInFolder(ctx context.Context, folder, pattern string) (io.ReadCloser, string, error) {
+	log.Trace(ctx, "looking for artist image", "pattern", pattern, "folder", folder)
+	fsys := os.DirFS(folder)
+	matches, err := fs.Glob(fsys, pattern)
+	if err != nil {
+		log.Warn(ctx, "Error matching artist image pattern", "pattern", pattern, "folder", folder, err)
+		return nil, "", err
+	}
+
+	// Filter to valid image files
+	var imagePaths []string
+	for _, m := range matches {
+		if !model.IsImageFile(m) {
+			continue
+		}
+		imagePaths = append(imagePaths, m)
+	}
+
+	// Sort image files by prioritizing base filenames without numeric
+	// suffixes (e.g., artist.jpg before artist.1.jpg)
+	slices.SortFunc(imagePaths, compareImageFiles)
+
+	// Try to open files in sorted order
+	for _, p := range imagePaths {
+		filePath := filepath.Join(folder, p)
+		f, err := os.Open(filePath)
+		if err != nil {
+			log.Warn(ctx, "Could not open cover art file", "file", filePath, err)
+			continue
+		}
+		return f, filePath, nil
+	}
+
+	return nil, "", fmt.Errorf(`no matches for '%s' in '%s'`, pattern, folder)
+}
+
+func loadArtistFolder(ctx context.Context, ds model.DataStore, albums model.Albums, paths []string) (string, time.Time, error) {
+	if len(albums) == 0 {
+		return "", time.Time{}, nil
+	}
+	libID := albums[0].LibraryID // Just need one of the albums, as they should all be in the same Library - for now! TODO: Support multiple libraries
+
+	folderPath := str.LongestCommonPrefix(paths)
+	if !strings.HasSuffix(folderPath, string(filepath.Separator)) {
+		folderPath, _ = filepath.Split(folderPath)
+	}
+	folderPath = filepath.Dir(folderPath)
+
+	// Manipulate the path to get the folder ID
+	// TODO: This is a bit hacky, but it's the easiest way to get the folder ID, ATM
+	libPath := core.AbsolutePath(ctx, ds, libID, "")
+	folderID := model.FolderID(model.Library{ID: libID, Path: libPath}, folderPath)
+
+	log.Trace(ctx, "Calculating artist folder details", "folderPath", folderPath, "folderID", folderID,
+		"libPath", libPath, "libID", libID, "albumPaths", paths)
+
+	// Get the last update time for the folder
+	folders, err := ds.Folder(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"folder.id": folderID, "missing": false}})
+	if err != nil || len(folders) == 0 {
+		log.Warn(ctx, "Could not find folder for artist", "folderPath", folderPath, "id", folderID,
+			"libPath", libPath, "libID", libID, err)
+		return "", time.Time{}, err
+	}
+	return folderPath, folders[0].ImagesUpdatedAt, nil
+}

core/artwork/reader_artist_test.go

@@ -0,0 +1,446 @@
+package artwork
+
+import (
+	"context"
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"time"
+
+	"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("/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("/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
+			testFunc sourceFunc
+		)
+
+		BeforeEach(func() {
+			ctx = context.Background()
+			tempDir = GinkgoT().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, 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 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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()
+			})
+		})
+	})
+})
+
+type fakeFolderRepo struct {
+	model.FolderRepository
+	result []model.Folder
+	err    error
+}
+
+func (f *fakeFolderRepo) GetAll(...model.QueryOptions) ([]model.Folder, error) {
+	return f.result, f.err
+}
+
+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

@@ -0,0 +1,65 @@
+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
+}
+
+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
+	}
+	a := &mediafileArtworkReader{
+		a:         artwork,
+		mediafile: *mf,
+		album:     *al,
+	}
+	a.cacheKey.artID = artID
+	if al.UpdatedAt.After(mf.UpdatedAt) {
+		a.cacheKey.lastUpdate = al.UpdatedAt
+	} else {
+		a.cacheKey.lastUpdate = mf.UpdatedAt
+	}
+	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 {
+		path := a.mediafile.AbsolutePath()
+		ff = []sourceFunc{
+			fromTag(ctx, path),
+			fromFFmpegTag(ctx, a.a.ffmpeg, path),
+		}
+	}
+	ff = append(ff, fromAlbum(ctx, a.a, a.mediafile.AlbumCoverArtID()))
+	return selectImageReader(ctx, a.artID, ff...)
+}

core/artwork/reader_playlist.go

@@ -0,0 +1,147 @@
+package artwork
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"image"
+	"image/draw"
+	"image/png"
+	"io"
+	"time"
+
+	"github.com/disintegration/imaging"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/utils/slice"
+)
+
+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
+	return a, nil
+}
+
+func (a *playlistArtworkReader) LastUpdated() time.Time {
+	return a.lastUpdate
+}
+
+func (a *playlistArtworkReader) Reader(ctx context.Context) (io.ReadCloser, string, error) {
+	ff := []sourceFunc{
+		a.fromGeneratedTiledCover(ctx),
+		fromAlbumPlaceholder(),
+	}
+	return selectImageReader(ctx, a.artID, ff...)
+}
+
+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 imaging.Fill(img, tileSize/2, tileSize/2, imaging.Center, imaging.Lanczos), 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
+}

core/artwork/reader_resized.go

@@ -0,0 +1,116 @@
+package artwork
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"image"
+	"image/jpeg"
+	"image/png"
+	"io"
+	"time"
+
+	"github.com/disintegration/imaging"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+)
+
+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.CoverJpegQuality)
+}
+
+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 := resizeImage(orig, a.size, a.square)
+	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
+	}
+	return io.NopCloser(resized), fmt.Sprintf("%s@%d", a.artID, a.size), nil
+}
+
+func resizeImage(reader io.Reader, size int, square bool) (io.Reader, int, error) {
+	original, format, err := image.Decode(reader)
+	if err != nil {
+		return nil, 0, err
+	}
+
+	bounds := original.Bounds()
+	originalSize := max(bounds.Max.X, bounds.Max.Y)
+
+	if originalSize <= size && !square {
+		return nil, originalSize, nil
+	}
+
+	var resized image.Image
+	if originalSize >= size {
+		resized = imaging.Fit(original, size, size, imaging.Lanczos)
+	} else {
+		if bounds.Max.Y < bounds.Max.X {
+			resized = imaging.Resize(original, size, 0, imaging.Lanczos)
+		} else {
+			resized = imaging.Resize(original, 0, size, imaging.Lanczos)
+		}
+	}
+	if square {
+		bg := image.NewRGBA(image.Rect(0, 0, size, size))
+		resized = imaging.OverlayCenter(bg, resized, 1)
+	}
+
+	buf := new(bytes.Buffer)
+	if format == "png" || square {
+		err = png.Encode(buf, resized)
+	} else {
+		err = jpeg.Encode(buf, resized, &jpeg.Options{Quality: conf.Server.CoverJpegQuality})
+	}
+	return buf, originalSize, err
+}

core/artwork/sources.go

@@ -0,0 +1,194 @@
+package artwork
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"reflect"
+	"regexp"
+	"runtime"
+	"strings"
+	"time"
+
+	"github.com/dhowden/tag"
+	"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"
+)
+
+func selectImageReader(ctx context.Context, artID model.ArtworkID, extractFuncs ...sourceFunc) (io.ReadCloser, string, error) {
+	for _, f := range extractFuncs {
+		if ctx.Err() != nil {
+			return nil, "", ctx.Err()
+		}
+		start := time.Now()
+		r, path, err := f()
+		if r != nil {
+			msg := fmt.Sprintf("Found %s artwork", artID.Kind)
+			log.Debug(ctx, msg, "artID", artID, "path", path, "source", f, "elapsed", time.Since(start))
+			return r, path, nil
+		}
+		log.Trace(ctx, "Failed trying to extract artwork", "artID", artID, "source", f, "elapsed", time.Since(start), err)
+	}
+	return nil, "", fmt.Errorf("could not get `%s` cover art for %s: %w", artID.Kind, artID, ErrUnavailable)
+}
+
+type sourceFunc func() (r io.ReadCloser, path string, err error)
+
+func (f sourceFunc) String() string {
+	name := runtime.FuncForPC(reflect.ValueOf(f).Pointer()).Name()
+	name = strings.TrimPrefix(name, "github.com/navidrome/navidrome/core/artwork.")
+	if _, after, found := strings.Cut(name, ")."); found {
+		name = after
+	}
+	name = strings.TrimSuffix(name, ".func1")
+	return name
+}
+
+func fromExternalFile(ctx context.Context, files []string, pattern string) sourceFunc {
+	return func() (io.ReadCloser, string, error) {
+		for _, file := range files {
+			_, name := filepath.Split(file)
+			match, err := filepath.Match(pattern, strings.ToLower(name))
+			if err != nil {
+				log.Warn(ctx, "Error matching cover art file to pattern", "pattern", pattern, "file", file)
+				continue
+			}
+			if !match {
+				continue
+			}
+			f, err := os.Open(file)
+			if err != nil {
+				log.Warn(ctx, "Could not open cover art file", "file", file, err)
+				continue
+			}
+			return f, file, err
+		}
+		return nil, "", fmt.Errorf("pattern '%s' not matched by files %v", pattern, files)
+	}
+}
+
+// These regexes are used to match the picture type in the file, in the order they are listed.
+var picTypeRegexes = []*regexp.Regexp{
+	regexp.MustCompile(`(?i).*cover.*front.*|.*front.*cover.*`),
+	regexp.MustCompile(`(?i).*front.*`),
+	regexp.MustCompile(`(?i).*cover.*`),
+}
+
+func fromTag(ctx context.Context, 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
+		}
+		defer f.Close()
+
+		m, err := tag.ReadFrom(f)
+		if err != nil {
+			return nil, "", err
+		}
+
+		types := m.PictureTypes()
+		if len(types) == 0 {
+			return nil, "", fmt.Errorf("no embedded image found in %s", path)
+		}
+
+		var picture *tag.Picture
+		for _, regex := range picTypeRegexes {
+			for _, t := range types {
+				if regex.MatchString(t) {
+					log.Trace(ctx, "Found embedded image", "type", t, "path", path)
+					picture = m.Pictures(t)
+					break
+				}
+			}
+			if picture != nil {
+				break
+			}
+		}
+		if picture == nil {
+			log.Trace(ctx, "Could not find a front image. Getting the first one", "type", types[0], "path", path)
+			picture = m.Picture()
+		}
+		if picture == nil {
+			return nil, "", fmt.Errorf("could not load embedded image from %s", path)
+		}
+		return io.NopCloser(bytes.NewReader(picture.Data)), path, nil
+	}
+}
+
+func fromFFmpegTag(ctx context.Context, ffmpeg ffmpeg.FFmpeg, path string) sourceFunc {
+	return func() (io.ReadCloser, string, error) {
+		if path == "" {
+			return nil, "", nil
+		}
+		r, err := ffmpeg.ExtractImage(ctx, path)
+		if err != nil {
+			return nil, "", err
+		}
+		return r, path, nil
+	}
+}
+
+func fromAlbum(ctx context.Context, a *artwork, id model.ArtworkID) sourceFunc {
+	return func() (io.ReadCloser, string, error) {
+		r, _, err := a.Get(ctx, id, 0, false)
+		if err != nil {
+			return nil, "", err
+		}
+		return r, id.String(), nil
+	}
+}
+
+func fromAlbumPlaceholder() sourceFunc {
+	return func() (io.ReadCloser, string, error) {
+		r, _ := resources.FS().Open(consts.PlaceholderAlbumArt)
+		return r, consts.PlaceholderAlbumArt, nil
+	}
+}
+func fromArtistExternalSource(ctx context.Context, ar model.Artist, provider external.Provider) sourceFunc {
+	return func() (io.ReadCloser, string, error) {
+		imageUrl, err := provider.ArtistImage(ctx, ar.ID)
+		if err != nil {
+			return nil, "", err
+		}
+
+		return fromURL(ctx, imageUrl)
+	}
+}
+
+func fromAlbumExternalSource(ctx context.Context, al model.Album, provider external.Provider) sourceFunc {
+	return func() (io.ReadCloser, string, error) {
+		imageUrl, err := provider.AlbumImage(ctx, al.ID)
+		if err != nil {
+			return nil, "", err
+		}
+
+		return fromURL(ctx, imageUrl)
+	}
+}
+
+func fromURL(ctx context.Context, imageUrl *url.URL) (io.ReadCloser, string, error) {
+	hc := http.Client{Timeout: 5 * time.Second}
+	req, _ := http.NewRequestWithContext(ctx, http.MethodGet, imageUrl.String(), nil)
+	resp, err := hc.Do(req)
+	if err != nil {
+		return nil, "", err
+	}
+	if resp.StatusCode != http.StatusOK {
+		resp.Body.Close()
+		return nil, "", fmt.Errorf("error retrieving artwork from %s: %s", imageUrl, resp.Status)
+	}
+	return resp.Body, imageUrl.String(), nil
+}

core/artwork/wire_providers.go

@@ -0,0 +1,11 @@
+package artwork
+
+import (
+	"github.com/google/wire"
+)
+
+var Set = wire.NewSet(
+	NewArtwork,
+	GetImageCache,
+	NewCacheWarmer,
+)