Merge remote-tracking branch 'origin/master' into codex/ttml-lrc-lyrics

# Conflicts:
#	server/subsonic/opensubsonic_test.go

.github/workflows/pipeline.yml

@@ -120,6 +120,79 @@ jobs:
           go build -o ndpgen .
           ./ndpgen --help
 
+  go-windows:
+    name: Test Go code (Windows)
+    runs-on: windows-2022
+    env:
+      FFMPEG_VERSION: "7.1"
+      FFMPEG_REPOSITORY: navidrome/ffmpeg-windows-builds
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+
+      - uses: msys2/setup-msys2@v2
+        with:
+          msystem: MINGW64
+          install: mingw-w64-x86_64-gcc
+          update: false
+
+      - name: Add mingw64 to PATH
+        shell: bash
+        run: echo "C:/msys64/mingw64/bin" >> $GITHUB_PATH
+
+      - name: Cache ffmpeg
+        id: ffmpeg-cache
+        uses: actions/cache@v4
+        with:
+          path: C:\ffmpeg
+          key: ffmpeg-${{ env.FFMPEG_VERSION }}-win64
+
+      - name: Download ffmpeg
+        if: steps.ffmpeg-cache.outputs.cache-hit != 'true'
+        shell: pwsh
+        run: |
+          $asset = "ffmpeg-n${env:FFMPEG_VERSION}-latest-win64-gpl-${env:FFMPEG_VERSION}"
+          $url = "https://github.com/${env:FFMPEG_REPOSITORY}/releases/download/latest/$asset.zip"
+          Invoke-WebRequest -Uri $url -OutFile ffmpeg.zip
+          Expand-Archive ffmpeg.zip -DestinationPath C:\ffmpeg-extracted
+          New-Item -ItemType Directory -Force -Path C:\ffmpeg\bin | Out-Null
+          Copy-Item "C:\ffmpeg-extracted\$asset\bin\ffmpeg.exe"  C:\ffmpeg\bin
+          Copy-Item "C:\ffmpeg-extracted\$asset\bin\ffprobe.exe" C:\ffmpeg\bin
+
+      - name: Add ffmpeg to PATH
+        shell: bash
+        run: echo "C:/ffmpeg/bin" >> $GITHUB_PATH
+
+      - name: Verify toolchain
+        shell: pwsh
+        run: |
+          go version
+          where.exe gcc
+          gcc --version
+          ffmpeg -version
+          ffprobe -version
+
+      - name: Download dependencies
+        shell: bash
+        run: go mod download
+
+      - name: Test
+        shell: bash
+        env:
+          CGO_ENABLED: "1"
+        run: go test -shuffle=on -tags netgo,sqlite_fts5 ./... -v
+
+      - name: Test ndpgen
+        shell: pwsh
+        run: |
+          cd plugins\cmd\ndpgen
+          go test -shuffle=on -v
+          go build -o ndpgen.exe .
+          .\ndpgen.exe --help
+
   js:
     name: Test JS code
     runs-on: ubuntu-latest
@@ -184,7 +257,7 @@ jobs:
 
   build:
     name: Build
-    needs: [js, go, go-lint, i18n-lint, git-version, check-push-enabled]
+    needs: [js, go, go-windows, go-lint, i18n-lint, git-version, check-push-enabled]
     strategy:
       matrix:
         platform: [ linux/amd64, linux/arm64, linux/arm/v5, linux/arm/v6, linux/arm/v7, linux/386, linux/riscv64, darwin/amd64, darwin/arm64, windows/amd64, windows/386 ]

Makefile

@@ -75,8 +75,8 @@ test-i18n: ##@Development Validate all translations files
 
 install-golangci-lint: ##@Development Install golangci-lint if not present
 	@INSTALL=false; \
-	if PATH=$$PATH:./bin which golangci-lint > /dev/null 2>&1; then \
-		CURRENT_VERSION=$$(PATH=$$PATH:./bin golangci-lint version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -n1); \
+	if PATH=./bin:$$PATH which golangci-lint > /dev/null 2>&1; then \
+		CURRENT_VERSION=$$(PATH=./bin:$$PATH golangci-lint version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -n1); \
 		REQUIRED_VERSION=$$(echo "$(GOLANGCI_LINT_VERSION)" | sed 's/^v//'); \
 		if [ "$$CURRENT_VERSION" != "$$REQUIRED_VERSION" ]; then \
 			echo "Found golangci-lint $$CURRENT_VERSION, but $$REQUIRED_VERSION is required. Reinstalling..."; \
@@ -93,7 +93,7 @@ install-golangci-lint: ##@Development Install golangci-lint if not present
 .PHONY: install-golangci-lint
 
 lint: install-golangci-lint ##@Development Lint Go code
-	PATH=$$PATH:./bin golangci-lint run --timeout 5m
+	PATH=./bin:$$PATH golangci-lint run --timeout 5m
 .PHONY: lint
 
 lintall: lint ##@Development Lint Go and JS code

adapters/gotaglib/gotaglib_test.go

@@ -5,6 +5,7 @@ import (
 	"os"
 	"strings"
 
+	"github.com/navidrome/navidrome/tests"
 	"github.com/navidrome/navidrome/utils"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -213,6 +214,7 @@ var _ = Describe("Extractor", func() {
 			// Only run permission tests if we are not root
 			RegularUserContext("when run without root privileges", func() {
 				BeforeEach(func() {
+					tests.SkipOnWindows("uses Unix file permission bits")
 					// Use root fs for absolute paths in temp directory
 					e = &extractor{fs: os.DirFS("/")}
 					accessForbiddenFile = utils.TempFileName("access_forbidden-", ".mp3")

cmd/pls.go

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

cmd/wire_gen.go

@@ -22,6 +22,7 @@ import (
 	"github.com/navidrome/navidrome/core/playback"
 	"github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/core/scrobbler"
+	"github.com/navidrome/navidrome/core/sonic"
 	"github.com/navidrome/navidrome/core/stream"
 	"github.com/navidrome/navidrome/db"
 	"github.com/navidrome/navidrome/model"
@@ -110,7 +111,8 @@ func CreateSubsonicAPIRouter(ctx context.Context) *subsonic.Router {
 	playbackServer := playback.GetInstance(dataStore)
 	lyricsLyrics := lyrics.NewLyrics(manager)
 	transcodeDecider := stream.NewTranscodeDecider(dataStore, fFmpeg)
-	router := subsonic.New(dataStore, artworkArtwork, mediaStreamer, archiver, players, provider, modelScanner, broker, playlistsPlaylists, playTracker, share, playbackServer, metricsMetrics, lyricsLyrics, transcodeDecider)
+	sonicSonic := sonic.New(dataStore, manager, matcherMatcher)
+	router := subsonic.New(dataStore, artworkArtwork, mediaStreamer, archiver, players, provider, modelScanner, broker, playlistsPlaylists, playTracker, share, playbackServer, metricsMetrics, lyricsLyrics, transcodeDecider, sonicSonic)
 	return router
 }
 
@@ -219,7 +221,7 @@ func getPluginManager() *plugins.Manager {
 
 // wire_injectors.go:
 
-var allProviders = wire.NewSet(core.Set, artwork.Set, server.New, subsonic.New, nativeapi.New, public.New, persistence.New, lastfm.NewRouter, listenbrainz.NewRouter, events.GetBroker, scanner.New, scanner.GetWatcher, metrics.GetPrometheusInstance, db.Db, plugins.GetManager, wire.Bind(new(agents.PluginLoader), new(*plugins.Manager)), wire.Bind(new(scrobbler.PluginLoader), new(*plugins.Manager)), wire.Bind(new(lyrics.PluginLoader), new(*plugins.Manager)), wire.Bind(new(nativeapi.PluginManager), new(*plugins.Manager)), wire.Bind(new(core.PluginUnloader), new(*plugins.Manager)), wire.Bind(new(plugins.PluginMetricsRecorder), new(metrics.Metrics)), wire.Bind(new(core.Watcher), new(scanner.Watcher)))
+var allProviders = wire.NewSet(core.Set, artwork.Set, server.New, subsonic.New, nativeapi.New, public.New, persistence.New, lastfm.NewRouter, listenbrainz.NewRouter, events.GetBroker, scanner.New, scanner.GetWatcher, metrics.GetPrometheusInstance, db.Db, plugins.GetManager, sonic.New, wire.Bind(new(agents.PluginLoader), new(*plugins.Manager)), wire.Bind(new(scrobbler.PluginLoader), new(*plugins.Manager)), wire.Bind(new(lyrics.PluginLoader), new(*plugins.Manager)), wire.Bind(new(sonic.PluginLoader), new(*plugins.Manager)), wire.Bind(new(nativeapi.PluginManager), new(*plugins.Manager)), wire.Bind(new(core.PluginUnloader), new(*plugins.Manager)), wire.Bind(new(plugins.PluginMetricsRecorder), new(metrics.Metrics)), wire.Bind(new(core.Watcher), new(scanner.Watcher)))
 
 func GetPluginManager(ctx context.Context) *plugins.Manager {
 	manager := getPluginManager()

cmd/wire_injectors.go

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

conf/configuration.go

@@ -27,6 +27,7 @@ type configOptions struct {
 	Address                         string
 	Port                            int
 	UnixSocketPerm                  string
+	EnforceNonRootUser              bool
 	MusicFolder                     string
 	DataFolder                      string
 	CacheFolder                     string
@@ -60,8 +61,8 @@ type configOptions struct {
 	SmartPlaylistRefreshDelay       time.Duration
 	AutoTranscodeDownload           bool
 	DefaultDownsamplingFormat       string
-	Search                          searchOptions `json:",omitzero"`
-	SimilarSongsMatchThreshold      int
+	Search                          searchOptions  `json:",omitzero"`
+	Matcher                         matcherOptions `json:",omitzero"`
 	RecentlyAddedByModTime          bool
 	PreferSortTags                  bool
 	IgnoredArticles                 string
@@ -261,6 +262,11 @@ type searchOptions struct {
 	FullString bool
 }
 
+type matcherOptions struct {
+	PreferStarred  bool
+	FuzzyThreshold int
+}
+
 // logFatal prints a fatal error message to stderr and exits.
 // Overridden in tests to allow testing fatal paths.
 var logFatal = func(args ...any) {
@@ -268,6 +274,12 @@ var logFatal = func(args ...any) {
 	os.Exit(1)
 }
 
+var getEUID = os.Geteuid
+
+var currentGOOS = func() string {
+	return runtime.GOOS
+}
+
 var (
 	Server = &configOptions{}
 	hooks  []func()
@@ -291,12 +303,18 @@ func Load(noConfigDump bool) {
 	mapDeprecatedOption("ReverseProxyUserHeader", "ExtAuth.UserHeader")
 	mapDeprecatedOption("HTTPSecurityHeaders.CustomFrameOptionsValue", "HTTPHeaders.FrameOptions")
 	mapDeprecatedOption("CoverJpegQuality", "CoverArtQuality")
+	mapDeprecatedOption("SimilarSongsMatchThreshold", "Matcher.FuzzyThreshold")
 
 	err := viper.Unmarshal(&Server)
 	if err != nil {
 		logFatal("Error parsing config:", err)
 	}
 
+	// Validate non-root user early, before any filesystem operations
+	if err := validateEnforceNonRootUser(); err != nil {
+		logFatal(err)
+	}
+
 	err = os.MkdirAll(Server.DataFolder, os.ModePerm)
 	if err != nil {
 		logFatal("Error creating data path:", err)
@@ -424,6 +442,7 @@ func Load(noConfigDump bool) {
 	logDeprecatedOptions("ReverseProxyUserHeader", "ExtAuth.UserHeader")
 	logDeprecatedOptions("HTTPSecurityHeaders.CustomFrameOptionsValue", "HTTPHeaders.FrameOptions")
 	logDeprecatedOptions("CoverJpegQuality", "CoverArtQuality")
+	logDeprecatedOptions("SimilarSongsMatchThreshold", "Matcher.FuzzyThreshold")
 
 	// Removed options
 	logRemovedOptions("Spotify.ID", "Spotify.Secret")
@@ -592,6 +611,18 @@ func validateMaxImageUploadSize() error {
 	return nil
 }
 
+func validateEnforceNonRootUser() error {
+	if !Server.EnforceNonRootUser || currentGOOS() == "windows" {
+		return nil
+	}
+
+	if getEUID() == 0 {
+		return fmt.Errorf("EnforceNonRootUser is enabled but Navidrome is running as root")
+	}
+
+	return nil
+}
+
 func validateScanSchedule() error {
 	if Server.Scanner.Schedule == "0" || Server.Scanner.Schedule == "" {
 		Server.Scanner.Schedule = ""
@@ -691,6 +722,7 @@ func setViperDefaults() {
 	viper.SetDefault("address", "0.0.0.0")
 	viper.SetDefault("port", 4533)
 	viper.SetDefault("unixsocketperm", "0660")
+	viper.SetDefault("enforcenonrootuser", false)
 	viper.SetDefault("sessiontimeout", consts.DefaultSessionTimeout)
 	viper.SetDefault("baseurl", "")
 	viper.SetDefault("tlscert", "")
@@ -716,7 +748,8 @@ func setViperDefaults() {
 	viper.SetDefault("defaultdownsamplingformat", consts.DefaultDownsamplingFormat)
 	viper.SetDefault("search.fullstring", false)
 	viper.SetDefault("search.backend", "fts")
-	viper.SetDefault("similarsongsmatchthreshold", 85)
+	viper.SetDefault("matcher.preferstarred", true)
+	viper.SetDefault("matcher.fuzzythreshold", 85)
 	viper.SetDefault("recentlyaddedbymodtime", false)
 	viper.SetDefault("prefersorttags", false)
 	viper.SetDefault("ignoredarticles", "The El La Los Las Le Les Os As O A")

conf/configuration_test.go

@@ -250,6 +250,49 @@ var _ = Describe("Configuration", func() {
 		)
 	})
 
+	Describe("EnforceNonRootUser", func() {
+		It("defaults to false", func() {
+			conf.Load(true)
+
+			Expect(conf.Server.EnforceNonRootUser).To(BeFalse())
+		})
+
+		It("allows startup for non-root users when enabled", func() {
+			DeferCleanup(conf.SetRuntimeInfoForTest("linux", 1000))
+			viper.Set("enforcenonrootuser", true)
+
+			conf.Load(true)
+
+			Expect(conf.Server.EnforceNonRootUser).To(BeTrue())
+		})
+
+		It("exits when enabled and running as root without having created a data folder", func() {
+			// Create a path that doesn't exist yet
+			tempBase := GinkgoT().TempDir()
+			nonExistentDataFolder := filepath.Join(tempBase, "nonexistent", "data")
+			DeferCleanup(conf.SetRuntimeInfoForTest("linux", 0))
+			viper.Set("enforcenonrootuser", true)
+			viper.Set("datafolder", nonExistentDataFolder)
+
+			// Attempt to load config as root user - should fail before creating directories
+			Expect(func() {
+				conf.Load(true)
+			}).To(PanicWith(ContainSubstring("EnforceNonRootUser is enabled but Navidrome is running as root")))
+
+			// Verify that the data folder was NOT created
+			Expect(nonExistentDataFolder).ToNot(BeAnExistingFile())
+		})
+
+		It("is a no-op on non-unix platforms", func() {
+			DeferCleanup(conf.SetRuntimeInfoForTest("windows", 0))
+			viper.Set("enforcenonrootuser", true)
+
+			conf.Load(true)
+
+			Expect(conf.Server.EnforceNonRootUser).To(BeTrue())
+		})
+	})
+
 	DescribeTable("should load configuration from",
 		func(format string) {
 			filename := filepath.Join("testdata", "cfg."+format)

conf/export_test.go

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

core/archiver.go

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

core/artwork/artwork_internal_test.go

@@ -37,10 +37,15 @@ var _ = Describe("Artwork", func() {
 		conf.Server.CoverArtPriority = "folder.*, cover.*, embedded , front.*"
 
 		folderRepo = &fakeFolderRepo{}
+		libRepo := &tests.MockLibraryRepo{}
+		repoRoot, _ := os.Getwd()
+		libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(repoRoot)}})
 		ds = &tests.MockDataStore{
 			MockedTranscoding: &tests.MockTranscodingRepo{},
 			MockedFolder:      folderRepo,
+			MockedLibrary:     libRepo,
 		}
+		// Paths use forward slashes because the scanner stores fs.FS-relative paths in the DB.
 		alOnlyEmbed = model.Album{ID: "222", Name: "Only embed", EmbedArtPath: "tests/fixtures/artist/an-album/test.mp3", FolderIDs: []string{"f1"}}
 		alEmbedNotFound = model.Album{ID: "333", Name: "Embed not found", EmbedArtPath: "tests/fixtures/NON_EXISTENT.mp3", FolderIDs: []string{"f1"}}
 		alOnlyExternal = model.Album{ID: "444", Name: "Only external", FolderIDs: []string{"f1"}, Discs: model.Discs{1: "", 2: ""}}
@@ -194,9 +199,12 @@ var _ = Describe("Artwork", func() {
 	Describe("artistArtworkReader", func() {
 		Context("Multiple covers", func() {
 			BeforeEach(func() {
+				repoRoot, err := os.Getwd()
+				Expect(err).ToNot(HaveOccurred())
 				folderRepo.result = []model.Folder{{
-					Path:       "tests/fixtures/artist/an-album",
-					ImageFiles: []string{"artist.png"},
+					LibraryPath: testFileLibPath(repoRoot),
+					Path:        "tests/fixtures/artist/an-album",
+					ImageFiles:  []string{"artist.png"},
 				}}
 				ds.Artist(ctx).(*tests.MockArtistRepo).SetData(model.Artists{
 					arMultipleCovers,
@@ -215,7 +223,7 @@ var _ = Describe("Artwork", func() {
 					Expect(err).ToNot(HaveOccurred())
 					_, path, err := aw.Reader(ctx)
 					Expect(err).ToNot(HaveOccurred())
-					Expect(path).To(Equal(expected))
+					Expect(filepath.ToSlash(path)).To(HaveSuffix(expected))
 				},
 				Entry(nil, " folder.* , artist.*,album/artist.*", "tests/fixtures/artist/artist.jpg"),
 				Entry(nil, "album/artist.*, folder.*,artist.*", "tests/fixtures/artist/an-album/artist.png"),
@@ -459,7 +467,10 @@ var _ = Describe("Artwork", func() {
 						Name:      "Only external",
 						FolderIDs: []string{"tmp"},
 					}
-					folderRepo.result = []model.Folder{{Path: dirName, ImageFiles: []string{coverFileName}}}
+					folderRepo.result = []model.Folder{{ImageFiles: []string{coverFileName}}}
+					rootLibRepo := &tests.MockLibraryRepo{}
+					rootLibRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(dirName)}})
+					ds.(*tests.MockDataStore).MockedLibrary = rootLibRepo
 					ds.Album(ctx).(*tests.MockAlbumRepo).SetData(model.Albums{
 						alCover,
 					})
@@ -547,7 +558,10 @@ var _ = Describe("Artwork", func() {
 					Name:      "Only external",
 					FolderIDs: []string{"tmp"},
 				}
-				folderRepo.result = []model.Folder{{Path: dirName, ImageFiles: []string{"cover.png"}}}
+				folderRepo.result = []model.Folder{{ImageFiles: []string{"cover.png"}}}
+				rootLibRepo := &tests.MockLibraryRepo{}
+				rootLibRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(dirName)}})
+				ds.(*tests.MockDataStore).MockedLibrary = rootLibRepo
 				ds.Album(ctx).(*tests.MockAlbumRepo).SetData(model.Albums{alCover})
 
 				conf.Server.CoverArtPriority = "cover.png"

core/artwork/artwork_suite_test.go

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

core/artwork/e2e/album_test.go

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

core/artwork/e2e/artist_test.go

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

core/artwork/e2e/disc_test.go

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

core/artwork/e2e/helpers_test.go

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

core/artwork/e2e/mediafile_test.go

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

core/artwork/e2e/playlist_test.go

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

core/artwork/e2e/radio_test.go

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

core/artwork/e2e/suite_test.go

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

core/artwork/library_fs.go

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

core/artwork/library_fs_test.go

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

core/artwork/reader_album.go

@@ -7,14 +7,13 @@ import (
 	"errors"
 	"fmt"
 	"io"
-	"path/filepath"
+	"path"
 	"slices"
 	"strings"
 	"time"
 
 	"github.com/Masterminds/squirrel"
 	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/core"
 	"github.com/navidrome/navidrome/core/external"
 	"github.com/navidrome/navidrome/core/ffmpeg"
 	"github.com/navidrome/navidrome/log"
@@ -24,12 +23,12 @@ import (
 
 type albumArtworkReader struct {
 	cacheKey
-	a          *artwork
-	provider   external.Provider
-	album      model.Album
-	updatedAt  *time.Time
-	imgFiles   []string
-	rootFolder string
+	a         *artwork
+	provider  external.Provider
+	album     model.Album
+	updatedAt *time.Time
+	imgFiles  []string // library-relative, forward-slash, no leading slash
+	lib       libraryView
 }
 
 func newAlbumArtworkReader(ctx context.Context, artwork *artwork, artID model.ArtworkID, provider external.Provider) (*albumArtworkReader, error) {
@@ -41,13 +40,17 @@ func newAlbumArtworkReader(ctx context.Context, artwork *artwork, artID model.Ar
 	if err != nil {
 		return nil, err
 	}
+	lib, err := loadLibraryView(ctx, artwork.ds, al.LibraryID)
+	if err != nil {
+		return nil, err
+	}
 	a := &albumArtworkReader{
-		a:          artwork,
-		provider:   provider,
-		album:      *al,
-		updatedAt:  imagesUpdateAt,
-		imgFiles:   imgFiles,
-		rootFolder: core.AbsolutePath(ctx, artwork.ds, al.LibraryID, ""),
+		a:         artwork,
+		provider:  provider,
+		album:     *al,
+		updatedAt: imagesUpdateAt,
+		imgFiles:  imgFiles,
+		lib:       lib,
 	}
 	a.cacheKey.artID = artID
 	if a.updatedAt != nil && a.updatedAt.After(al.UpdatedAt) {
@@ -86,12 +89,15 @@ func (a *albumArtworkReader) fromCoverArtPriority(ctx context.Context, ffmpeg ff
 		pattern = strings.TrimSpace(pattern)
 		switch {
 		case pattern == "embedded":
-			embedArtPath := filepath.Join(a.rootFolder, a.album.EmbedArtPath)
-			ff = append(ff, fromTag(ctx, embedArtPath), fromFFmpegTag(ctx, ffmpeg, embedArtPath))
+			embedRel := a.album.EmbedArtPath
+			ff = append(ff,
+				fromTag(ctx, a.lib.FS, embedRel),
+				fromFFmpegTag(ctx, ffmpeg, a.lib.Abs(embedRel)),
+			)
 		case pattern == "external":
 			ff = append(ff, fromAlbumExternalSource(ctx, a.album, a.provider))
 		case len(a.imgFiles) > 0:
-			ff = append(ff, fromExternalFile(ctx, a.imgFiles, pattern))
+			ff = append(ff, fromExternalFile(ctx, a.lib.FS, a.imgFiles, pattern))
 		}
 	}
 	return ff
@@ -132,13 +138,13 @@ func loadAlbumFoldersPaths(ctx context.Context, ds model.DataStore, albums ...mo
 	var imgFiles []string
 	var updatedAt time.Time
 	for _, f := range folders {
-		path := f.AbsolutePath()
-		paths = append(paths, path)
+		paths = append(paths, f.AbsolutePath())
 		if f.ImagesUpdatedAt.After(updatedAt) {
 			updatedAt = f.ImagesUpdatedAt
 		}
+		rel := strings.TrimPrefix(path.Join(f.Path, f.Name), "/")
 		for _, img := range f.ImageFiles {
-			imgFiles = append(imgFiles, filepath.Join(path, img))
+			imgFiles = append(imgFiles, path.Join(rel, img))
 		}
 	}
 
@@ -179,8 +185,8 @@ func compareImageFiles(a, b string) int {
 	b = strings.ToLower(b)
 
 	// Extract base filenames without extensions
-	baseA := strings.TrimSuffix(filepath.Base(a), filepath.Ext(a))
-	baseB := strings.TrimSuffix(filepath.Base(b), filepath.Ext(b))
+	baseA := strings.TrimSuffix(path.Base(a), path.Ext(a))
+	baseB := strings.TrimSuffix(path.Base(b), path.Ext(b))
 
 	// Compare base names first, then full paths if equal
 	return cmp.Or(

core/artwork/reader_album_test.go

@@ -3,7 +3,6 @@ package artwork
 import (
 	"context"
 	"errors"
-	"path/filepath"
 	"time"
 
 	"github.com/navidrome/navidrome/model"
@@ -69,11 +68,11 @@ var _ = Describe("Album Artwork Reader", func() {
 			// Files should be sorted by base filename without extension, then by full path
 			// "back" < "cover", so back.jpg comes first
 			// Then all cover.jpg files, sorted by path
-			Expect(imgFiles[0]).To(Equal(filepath.FromSlash("Artist/Album/Disc1/back.jpg")))
-			Expect(imgFiles[1]).To(Equal(filepath.FromSlash("Artist/Album/Disc1/cover.jpg")))
-			Expect(imgFiles[2]).To(Equal(filepath.FromSlash("Artist/Album/Disc2/cover.jpg")))
-			Expect(imgFiles[3]).To(Equal(filepath.FromSlash("Artist/Album/Disc10/cover.jpg")))
-			Expect(imgFiles[4]).To(Equal(filepath.FromSlash("Artist/Album/Disc1/cover.1.jpg")))
+			Expect(imgFiles[0]).To(Equal("Artist/Album/Disc1/back.jpg"))
+			Expect(imgFiles[1]).To(Equal("Artist/Album/Disc1/cover.jpg"))
+			Expect(imgFiles[2]).To(Equal("Artist/Album/Disc2/cover.jpg"))
+			Expect(imgFiles[3]).To(Equal("Artist/Album/Disc10/cover.jpg"))
+			Expect(imgFiles[4]).To(Equal("Artist/Album/Disc1/cover.1.jpg"))
 		})
 
 		It("prioritizes files without numeric suffixes", func() {
@@ -92,9 +91,9 @@ var _ = Describe("Album Artwork Reader", func() {
 			Expect(imgFiles).To(HaveLen(3))
 
 			// cover.jpg should come first because "cover" < "cover.1" < "cover.2"
-			Expect(imgFiles[0]).To(Equal(filepath.FromSlash("Artist/Album/cover.jpg")))
-			Expect(imgFiles[1]).To(Equal(filepath.FromSlash("Artist/Album/cover.1.jpg")))
-			Expect(imgFiles[2]).To(Equal(filepath.FromSlash("Artist/Album/cover.2.jpg")))
+			Expect(imgFiles[0]).To(Equal("Artist/Album/cover.jpg"))
+			Expect(imgFiles[1]).To(Equal("Artist/Album/cover.1.jpg"))
+			Expect(imgFiles[2]).To(Equal("Artist/Album/cover.2.jpg"))
 		})
 
 		It("handles case-insensitive sorting", func() {
@@ -113,9 +112,9 @@ var _ = Describe("Album Artwork Reader", func() {
 			Expect(imgFiles).To(HaveLen(3))
 
 			// Files should be sorted case-insensitively: BACK, cover, Folder
-			Expect(imgFiles[0]).To(Equal(filepath.FromSlash("Artist/Album/BACK.jpg")))
-			Expect(imgFiles[1]).To(Equal(filepath.FromSlash("Artist/Album/cover.jpg")))
-			Expect(imgFiles[2]).To(Equal(filepath.FromSlash("Artist/Album/Folder.jpg")))
+			Expect(imgFiles[0]).To(Equal("Artist/Album/BACK.jpg"))
+			Expect(imgFiles[1]).To(Equal("Artist/Album/cover.jpg"))
+			Expect(imgFiles[2]).To(Equal("Artist/Album/Folder.jpg"))
 		})
 
 		It("includes images from parent folder for multi-disc albums", func() {
@@ -151,8 +150,8 @@ var _ = Describe("Album Artwork Reader", func() {
 			Expect(err).ToNot(HaveOccurred())
 			Expect(*imagesUpdatedAt).To(Equal(expectedAt))
 			Expect(imgFiles).To(HaveLen(2))
-			Expect(imgFiles[0]).To(Equal(filepath.FromSlash("Artist/Album/back.jpg")))
-			Expect(imgFiles[1]).To(Equal(filepath.FromSlash("Artist/Album/cover.jpg")))
+			Expect(imgFiles[0]).To(Equal("Artist/Album/back.jpg"))
+			Expect(imgFiles[1]).To(Equal("Artist/Album/cover.jpg"))
 		})
 
 		It("does not query parent when parent ID is already in album folders", func() {
@@ -179,7 +178,7 @@ var _ = Describe("Album Artwork Reader", func() {
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(imgFiles).To(HaveLen(1))
-			Expect(imgFiles[0]).To(Equal(filepath.FromSlash("Artist/Album/cover.jpg")))
+			Expect(imgFiles[0]).To(Equal("Artist/Album/cover.jpg"))
 			// Get should not have been called (parent already in folder set)
 			Expect(repo.getCallCount).To(Equal(0))
 		})
@@ -209,7 +208,7 @@ var _ = Describe("Album Artwork Reader", func() {
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(imgFiles).To(HaveLen(1))
-			Expect(imgFiles[0]).To(Equal(filepath.FromSlash("Artist1/Album/part1/cover.jpg")))
+			Expect(imgFiles[0]).To(Equal("Artist1/Album/part1/cover.jpg"))
 			// Get should not have been called (different parents)
 			Expect(repo.getCallCount).To(Equal(0))
 		})
@@ -232,7 +231,7 @@ var _ = Describe("Album Artwork Reader", func() {
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(imgFiles).To(HaveLen(1))
-			Expect(imgFiles[0]).To(Equal(filepath.FromSlash("Artist/Album/cover.jpg")))
+			Expect(imgFiles[0]).To(Equal("Artist/Album/cover.jpg"))
 			// Get should not have been called (single folder, no parent lookup)
 			Expect(repo.getCallCount).To(Equal(0))
 		})
@@ -290,7 +289,7 @@ var _ = Describe("Album Artwork Reader", func() {
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(imgFiles).To(HaveLen(1))
-			Expect(imgFiles[0]).To(Equal(filepath.FromSlash("Artist/Album/CD1/cover.jpg")))
+			Expect(imgFiles[0]).To(Equal("Artist/Album/CD1/cover.jpg"))
 			Expect(repo.getCallCount).To(Equal(1))
 		})
 	})

core/artwork/reader_artist.go

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

core/artwork/reader_artist_test.go

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

core/artwork/reader_disc.go

@@ -5,7 +5,7 @@ import (
 	"crypto/md5"
 	"fmt"
 	"io"
-	"os"
+	"path"
 	"path/filepath"
 	"strconv"
 	"strings"
@@ -13,7 +13,6 @@ import (
 
 	"github.com/Masterminds/squirrel"
 	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/core"
 	"github.com/navidrome/navidrome/core/ffmpeg"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
@@ -24,10 +23,11 @@ type discArtworkReader struct {
 	a              *artwork
 	album          model.Album
 	discNumber     int
-	imgFiles       []string
-	discFolders    map[string]bool
+	imgFiles       []string        // library-relative, forward-slash, no leading slash
+	discFoldersRel map[string]bool // library-relative folder paths
 	isMultiFolder  bool
-	firstTrackPath string
+	firstTrackRel  string // library-relative; for fromTag / ffmpeg via lib.Abs
+	lib            libraryView
 	updatedAt      *time.Time
 }
 
@@ -57,18 +57,23 @@ func newDiscArtworkReader(ctx context.Context, a *artwork, artID model.ArtworkID
 		return nil, err
 	}
 
-	// Build disc folder set and find first track
-	discFolders := make(map[string]bool)
-	var firstTrackPath string
+	lib, err := loadLibraryView(ctx, a.ds, al.LibraryID)
+	if err != nil {
+		return nil, err
+	}
+
+	// Build disc folder set and find first track. mf.Path is already library-relative.
+	var firstTrackRel string
 	allFolderIDs := make(map[string]bool)
 	for _, mf := range mfs {
 		allFolderIDs[mf.FolderID] = true
-		if firstTrackPath == "" {
-			firstTrackPath = mf.Path
+		if firstTrackRel == "" {
+			firstTrackRel = filepath.ToSlash(mf.Path)
 		}
 	}
 
-	// Resolve folder IDs to absolute paths
+	// Resolve folder IDs to library-relative paths
+	discFoldersRel := make(map[string]bool)
 	if len(allFolderIDs) > 0 {
 		folderIDs := make([]string, 0, len(allFolderIDs))
 		for id := range allFolderIDs {
@@ -81,7 +86,8 @@ func newDiscArtworkReader(ctx context.Context, a *artwork, artID model.ArtworkID
 			return nil, err
 		}
 		for _, f := range folders {
-			discFolders[f.AbsolutePath()] = true
+			rel := strings.TrimPrefix(path.Join(f.Path, f.Name), "/")
+			discFoldersRel[rel] = true
 		}
 	}
 
@@ -92,9 +98,10 @@ func newDiscArtworkReader(ctx context.Context, a *artwork, artID model.ArtworkID
 		album:          *al,
 		discNumber:     discNumber,
 		imgFiles:       imgFiles,
-		discFolders:    discFolders,
+		discFoldersRel: discFoldersRel,
 		isMultiFolder:  isMultiFolder,
-		firstTrackPath: core.AbsolutePath(ctx, a.ds, al.LibraryID, firstTrackPath),
+		firstTrackRel:  firstTrackRel,
+		lib:            lib,
 		updatedAt:      imagesUpdatedAt,
 	}
 	r.cacheKey.artID = artID
@@ -133,7 +140,10 @@ func (d *discArtworkReader) fromDiscArtPriority(ctx context.Context, ffmpeg ffmp
 		pattern = strings.TrimSpace(pattern)
 		switch {
 		case pattern == "embedded":
-			ff = append(ff, fromTag(ctx, d.firstTrackPath), fromFFmpegTag(ctx, ffmpeg, d.firstTrackPath))
+			ff = append(ff,
+				fromTag(ctx, d.lib.FS, d.firstTrackRel),
+				fromFFmpegTag(ctx, ffmpeg, d.lib.Abs(d.firstTrackRel)),
+			)
 		case pattern == "external":
 			// Not supported for disc art, silently ignore
 		case pattern == "discsubtitle":
@@ -152,12 +162,12 @@ func (d *discArtworkReader) fromDiscArtPriority(ctx context.Context, ffmpeg ffmp
 func (d *discArtworkReader) fromDiscSubtitle(ctx context.Context, subtitle string) sourceFunc {
 	return func() (io.ReadCloser, string, error) {
 		for _, file := range d.imgFiles {
-			_, name := filepath.Split(file)
-			stem := strings.TrimSuffix(name, filepath.Ext(name))
+			name := path.Base(file)
+			stem := strings.TrimSuffix(name, path.Ext(name))
 			if !strings.EqualFold(stem, subtitle) {
 				continue
 			}
-			f, err := os.Open(file)
+			f, err := d.lib.FS.Open(file)
 			if err != nil {
 				log.Warn(ctx, "Could not open disc art file", "file", file, err)
 				continue
@@ -214,8 +224,7 @@ func (d *discArtworkReader) fromExternalFile(ctx context.Context, pattern string
 	return func() (io.ReadCloser, string, error) {
 		var fallbacks []string
 		for _, file := range d.imgFiles {
-			_, name := filepath.Split(file)
-			name = strings.ToLower(name)
+			name := strings.ToLower(path.Base(file))
 			match, err := filepath.Match(pattern, name)
 			if err != nil {
 				log.Warn(ctx, "Error matching disc art file to pattern", "pattern", pattern, "file", file)
@@ -230,7 +239,7 @@ func (d *discArtworkReader) fromExternalFile(ctx context.Context, pattern string
 					if num != d.discNumber {
 						continue
 					}
-					f, err := os.Open(file)
+					f, err := d.lib.FS.Open(file)
 					if err != nil {
 						log.Warn(ctx, "Could not open disc art file", "file", file, err)
 						continue
@@ -239,14 +248,14 @@ func (d *discArtworkReader) fromExternalFile(ctx context.Context, pattern string
 				}
 			}
 
-			if d.isMultiFolder && !d.discFolders[filepath.Dir(file)] {
+			if d.isMultiFolder && !d.discFoldersRel[path.Dir(file)] {
 				continue
 			}
 			fallbacks = append(fallbacks, file)
 		}
 
 		for _, file := range fallbacks {
-			f, err := os.Open(file)
+			f, err := d.lib.FS.Open(file)
 			if err != nil {
 				log.Warn(ctx, "Could not open disc art file", "file", file, err)
 				continue

core/artwork/reader_disc_test.go

@@ -74,20 +74,27 @@ var _ = Describe("Disc Artwork Reader", func() {
 			tmpDir = GinkgoT().TempDir()
 		})
 
-		createFile := func(path string) string {
-			fullPath := filepath.Join(tmpDir, filepath.FromSlash(path))
+		// createFile creates the file on disk and returns its library-relative forward-slash path.
+		createFile := func(relPath string) string {
+			fullPath := filepath.Join(tmpDir, filepath.FromSlash(relPath))
 			Expect(os.MkdirAll(filepath.Dir(fullPath), 0755)).To(Succeed())
 			Expect(os.WriteFile(fullPath, []byte("image data"), 0600)).To(Succeed())
-			return fullPath
+			return relPath
+		}
+
+		// removeFile removes a library-relative file from disk.
+		removeFile := func(relPath string) {
+			Expect(os.Remove(filepath.Join(tmpDir, filepath.FromSlash(relPath)))).To(Succeed())
 		}
 
 		It("matches file with disc number in single-folder album", func() {
 			f1 := createFile("album/disc1.jpg")
 			f2 := createFile("album/disc2.jpg")
 			reader := &discArtworkReader{
-				discNumber:  1,
-				imgFiles:    []string{f1, f2},
-				discFolders: map[string]bool{filepath.Join(tmpDir, "album"): true},
+				discNumber:     1,
+				imgFiles:       []string{f1, f2},
+				discFoldersRel: map[string]bool{"album": true},
+				lib:            libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 			}
 
 			sf := reader.fromExternalFile(ctx, "disc*.*")
@@ -101,9 +108,10 @@ var _ = Describe("Disc Artwork Reader", func() {
 		It("matches file without number in single-folder album (shared disc art)", func() {
 			f1 := createFile("album/cover.png")
 			reader := &discArtworkReader{
-				discNumber:  1,
-				imgFiles:    []string{f1},
-				discFolders: map[string]bool{filepath.Join(tmpDir, "album"): true},
+				discNumber:     1,
+				imgFiles:       []string{f1},
+				discFoldersRel: map[string]bool{"album": true},
+				lib:            libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 			}
 
 			sf := reader.fromExternalFile(ctx, "cover.*")
@@ -118,9 +126,10 @@ var _ = Describe("Disc Artwork Reader", func() {
 			f1 := createFile("album/shellac.png")
 			makeReader := func(discNum int) *discArtworkReader {
 				return &discArtworkReader{
-					discNumber:  discNum,
-					imgFiles:    []string{f1},
-					discFolders: map[string]bool{filepath.Join(tmpDir, "album"): true},
+					discNumber:     discNum,
+					imgFiles:       []string{f1},
+					discFoldersRel: map[string]bool{"album": true},
+					lib:            libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 				}
 			}
 
@@ -139,9 +148,10 @@ var _ = Describe("Disc Artwork Reader", func() {
 			f2 := createFile("album/disc1.jpg")
 			f3 := createFile("album/disc2.jpg")
 			reader := &discArtworkReader{
-				discNumber:  2,
-				imgFiles:    []string{f1, f2, f3},
-				discFolders: map[string]bool{filepath.Join(tmpDir, "album"): true},
+				discNumber:     2,
+				imgFiles:       []string{f1, f2, f3},
+				discFoldersRel: map[string]bool{"album": true},
+				lib:            libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 			}
 
 			sf := reader.fromExternalFile(ctx, "disc*.*")
@@ -163,9 +173,10 @@ var _ = Describe("Disc Artwork Reader", func() {
 			f1 := createFile("album/cover.png")
 			f2 := createFile("album/disc1.jpg")
 			reader := &discArtworkReader{
-				discNumber:  1,
-				imgFiles:    []string{f1, f2},
-				discFolders: map[string]bool{filepath.Join(tmpDir, "album"): true},
+				discNumber:     1,
+				imgFiles:       []string{f1, f2},
+				discFoldersRel: map[string]bool{"album": true},
+				lib:            libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 			}
 
 			ff := reader.fromDiscArtPriority(ctx, nil, "disc*.*, cover.*")
@@ -191,9 +202,10 @@ var _ = Describe("Disc Artwork Reader", func() {
 					createFile("album/disc2.jpg"),
 				}
 				reader := &discArtworkReader{
-					discNumber:  discNumber,
-					imgFiles:    files,
-					discFolders: map[string]bool{filepath.Join(tmpDir, "album"): true},
+					discNumber:     discNumber,
+					imgFiles:       files,
+					discFoldersRel: map[string]bool{"album": true},
+					lib:            libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 				}
 
 				sf := reader.fromExternalFile(ctx, "disc*.*")
@@ -210,12 +222,13 @@ var _ = Describe("Disc Artwork Reader", func() {
 		It("tries the next fallback candidate when the first one cannot be opened", func() {
 			f1 := createFile("album/cover.jpg")
 			f2 := createFile("album/cover.png")
-			// Remove f1 so os.Open will fail on it; f2 should still win.
-			Expect(os.Remove(f1)).To(Succeed())
+			// Remove f1 so Open will fail on it; f2 should still win.
+			removeFile(f1)
 			reader := &discArtworkReader{
-				discNumber:  1,
-				imgFiles:    []string{f1, f2},
-				discFolders: map[string]bool{filepath.Join(tmpDir, "album"): true},
+				discNumber:     1,
+				imgFiles:       []string{f1, f2},
+				discFoldersRel: map[string]bool{"album": true},
+				lib:            libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 			}
 
 			sf := reader.fromExternalFile(ctx, "cover.*")
@@ -234,15 +247,16 @@ var _ = Describe("Disc Artwork Reader", func() {
 			// that first file is unreadable.
 			f1 := createFile("album/stale/cover.png")
 			f2 := createFile("album/cover.png")
-			Expect(os.Remove(f1)).To(Succeed())
+			removeFile(f1)
 			reader := &discArtworkReader{
 				discNumber: 1,
 				imgFiles:   []string{f1, f2},
-				discFolders: map[string]bool{
-					filepath.Join(tmpDir, "album"):       true,
-					filepath.Join(tmpDir, "album/stale"): true,
+				discFoldersRel: map[string]bool{
+					"album":       true,
+					"album/stale": true,
 				},
 				isMultiFolder: true,
+				lib:           libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 			}
 
 			sf := reader.fromExternalFile(ctx, "cover.png")
@@ -260,9 +274,10 @@ var _ = Describe("Disc Artwork Reader", func() {
 					createFile("album/disc2.jpg"),
 				}
 				reader := &discArtworkReader{
-					discNumber:  discNumber,
-					imgFiles:    files,
-					discFolders: map[string]bool{filepath.Join(tmpDir, "album"): true},
+					discNumber:     discNumber,
+					imgFiles:       files,
+					discFoldersRel: map[string]bool{"album": true},
+					lib:            libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 				}
 
 				sf := reader.fromExternalFile(ctx, pattern)
@@ -282,10 +297,11 @@ var _ = Describe("Disc Artwork Reader", func() {
 			f1 := createFile("album/cd1/disc.jpg")
 			f2 := createFile("album/cd2/disc.jpg")
 			reader := &discArtworkReader{
-				discNumber:    1,
-				imgFiles:      []string{f1, f2},
-				discFolders:   map[string]bool{filepath.Join(tmpDir, "album", "cd1"): true},
-				isMultiFolder: true,
+				discNumber:     1,
+				imgFiles:       []string{f1, f2},
+				discFoldersRel: map[string]bool{"album/cd1": true},
+				isMultiFolder:  true,
+				lib:            libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 			}
 
 			sf := reader.fromExternalFile(ctx, "disc*.*")
@@ -300,10 +316,11 @@ var _ = Describe("Disc Artwork Reader", func() {
 			// disc2.jpg in cd1 folder should match disc 2, not disc 1
 			f1 := createFile("album/cd1/disc2.jpg")
 			reader := &discArtworkReader{
-				discNumber:    2,
-				imgFiles:      []string{f1},
-				discFolders:   map[string]bool{filepath.Join(tmpDir, "album", "cd1"): true},
-				isMultiFolder: true,
+				discNumber:     2,
+				imgFiles:       []string{f1},
+				discFoldersRel: map[string]bool{"album/cd1": true},
+				isMultiFolder:  true,
+				lib:            libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 			}
 
 			sf := reader.fromExternalFile(ctx, "disc*.*")
@@ -317,9 +334,10 @@ var _ = Describe("Disc Artwork Reader", func() {
 		It("does not match disc2.jpg when looking for disc 1", func() {
 			f1 := createFile("album/disc2.jpg")
 			reader := &discArtworkReader{
-				discNumber:  1,
-				imgFiles:    []string{f1},
-				discFolders: map[string]bool{filepath.Join(tmpDir, "album"): true},
+				discNumber:     1,
+				imgFiles:       []string{f1},
+				discFoldersRel: map[string]bool{"album": true},
+				lib:            libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 			}
 
 			sf := reader.fromExternalFile(ctx, "disc*.*")
@@ -339,11 +357,11 @@ var _ = Describe("Disc Artwork Reader", func() {
 			tmpDir = GinkgoT().TempDir()
 		})
 
-		createFile := func(path string) string {
-			fullPath := filepath.Join(tmpDir, filepath.FromSlash(path))
+		createFile := func(relPath string) string {
+			fullPath := filepath.Join(tmpDir, filepath.FromSlash(relPath))
 			Expect(os.MkdirAll(filepath.Dir(fullPath), 0755)).To(Succeed())
 			Expect(os.WriteFile(fullPath, []byte("image data"), 0600)).To(Succeed())
-			return fullPath
+			return relPath
 		}
 
 		It("matches image file whose stem equals the disc subtitle (case-insensitive)", func() {
@@ -351,6 +369,7 @@ var _ = Describe("Disc Artwork Reader", func() {
 			reader := &discArtworkReader{
 				discNumber: 1,
 				imgFiles:   []string{f1},
+				lib:        libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 			}
 
 			sf := reader.fromDiscSubtitle(ctx, "The Blue Disc")
@@ -366,6 +385,7 @@ var _ = Describe("Disc Artwork Reader", func() {
 			reader := &discArtworkReader{
 				discNumber: 2,
 				imgFiles:   []string{f1},
+				lib:        libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 			}
 
 			sf := reader.fromDiscSubtitle(ctx, "Bonus Tracks")
@@ -381,6 +401,7 @@ var _ = Describe("Disc Artwork Reader", func() {
 			reader := &discArtworkReader{
 				discNumber: 1,
 				imgFiles:   []string{f1},
+				lib:        libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 			}
 
 			sf := reader.fromDiscSubtitle(ctx, "The Blue Disc")
@@ -394,6 +415,7 @@ var _ = Describe("Disc Artwork Reader", func() {
 			reader := &discArtworkReader{
 				discNumber: 1,
 				imgFiles:   []string{f1, f2},
+				lib:        libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 			}
 
 			sf := reader.fromDiscSubtitle(ctx, "The Blue Disc")
@@ -407,19 +429,24 @@ var _ = Describe("Disc Artwork Reader", func() {
 
 	Describe("discArtworkReader", func() {
 		Describe("fromDiscArtPriority", func() {
-			var reader *discArtworkReader
+			var (
+				reader *discArtworkReader
+				tmpDir string
+			)
 
 			BeforeEach(func() {
+				tmpDir = GinkgoT().TempDir()
 				reader = &discArtworkReader{
-					discNumber:    2,
-					isMultiFolder: true,
-					discFolders:   map[string]bool{"/music/album/cd2": true},
+					discNumber:     2,
+					isMultiFolder:  true,
+					discFoldersRel: map[string]bool{"music/album/cd2": true},
 					imgFiles: []string{
-						"/music/album/cd1/disc.jpg",
-						"/music/album/cd2/disc.jpg",
-						"/music/album/cd2/disc2.jpg",
+						"music/album/cd1/disc.jpg",
+						"music/album/cd2/disc.jpg",
+						"music/album/cd2/disc2.jpg",
 					},
-					firstTrackPath: "/music/album/cd2/track1.flac",
+					firstTrackRel: "music/album/cd2/track1.flac",
+					lib:           libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},
 				}
 			})
 

core/artwork/reader_mediafile.go

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

core/artwork/sources.go

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

core/artwork/sources_internal_test.go

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

core/auth/claims.go

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

core/auth/claims_test.go

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

core/common_test.go

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

core/external/provider.go

@@ -302,7 +302,7 @@ func (e *provider) SimilarSongs(ctx context.Context, id string, count int) (mode
 	}
 
 	if err == nil && len(songs) > 0 {
-		return e.matcher.MatchSongsToLibrary(ctx, songs, count)
+		return e.matcher.MatchSongs(ctx, songs, count)
 	}
 
 	// Fallback to existing similar artists + top songs algorithm
@@ -481,7 +481,7 @@ func (e *provider) getMatchingTopSongs(ctx context.Context, agent agents.ArtistT
 		}
 	}
 
-	mfs, err := e.matcher.MatchSongsToLibrary(ctx, songs, count)
+	mfs, err := e.matcher.MatchSongs(ctx, songs, count)
 	if err != nil {
 		return nil, err
 	}

core/external/provider_topsongs_test.go

@@ -30,7 +30,7 @@ var _ = Describe("Provider - TopSongs", func() {
 	BeforeEach(func() {
 		DeferCleanup(configtest.SetupConfig())
 		// Disable fuzzy matching for these tests to avoid unexpected GetAll calls
-		conf.Server.SimilarSongsMatchThreshold = 100
+		conf.Server.Matcher.FuzzyThreshold = 100
 
 		ctx = GinkgoT().Context()
 

core/external/provider_updateartistinfo_test.go

@@ -105,6 +105,29 @@ var _ = Describe("Provider - UpdateArtistInfo", func() {
 		ag.AssertExpectations(GinkgoT())
 	})
 
+	It("preserves decoded plain text in biography storage", func() {
+		originalArtist := &model.Artist{
+			ID:   "ar-encoded-bio",
+			Name: "Encoded Bio Artist",
+		}
+		mockArtistRepo.SetData(model.Artists{*originalArtist})
+
+		expectedMBID := "mbid-encoded-bio"
+		expectedBio := "R&B"
+
+		ag.On("GetArtistMBID", ctx, "ar-encoded-bio", "Encoded Bio Artist").Return(expectedMBID, nil).Once()
+		ag.On("GetArtistImages", ctx, "ar-encoded-bio", "Encoded Bio Artist", expectedMBID).Return(nil, nil).Maybe()
+		ag.On("GetArtistBiography", ctx, "ar-encoded-bio", "Encoded Bio Artist", expectedMBID).Return(expectedBio, nil).Once()
+		ag.On("GetArtistURL", ctx, "ar-encoded-bio", "Encoded Bio Artist", expectedMBID).Return("", nil).Maybe()
+		ag.On("GetSimilarArtists", ctx, "ar-encoded-bio", "Encoded Bio Artist", expectedMBID, 100).Return(nil, nil).Maybe()
+
+		updatedArtist, err := p.UpdateArtistInfo(ctx, "ar-encoded-bio", 10, false)
+
+		Expect(err).NotTo(HaveOccurred())
+		Expect(updatedArtist).NotTo(BeNil())
+		Expect(updatedArtist.Biography).To(Equal("R&B"))
+	})
+
 	It("returns cached info when artist exists and info is not expired", func() {
 		now := time.Now()
 		originalArtist := &model.Artist{

core/ffmpeg/ffmpeg.go

@@ -13,6 +13,7 @@ import (
 	"strconv"
 	"strings"
 	"sync"
+	"time"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
@@ -57,6 +58,11 @@ func New() FFmpeg {
 	return &ffmpeg{}
 }
 
+// ErrAnimatedWebPUnsupported is returned by ConvertAnimatedImage when the
+// ffmpeg binary lacks the libwebp_anim encoder. Callers can use errors.Is to
+// detect this specific case and fall back to static resize.
+var ErrAnimatedWebPUnsupported = errors.New("ffmpeg lacks libwebp_anim encoder — install an ffmpeg build with libwebp")
+
 const (
 	extractImageCmd     = "ffmpeg -i %s -map 0:v -map -0:V -vcodec copy -f image2pipe -"
 	probeCmd            = "ffmpeg %s -f ffmetadata"
@@ -86,6 +92,9 @@ func (e *ffmpeg) ConvertAnimatedImage(ctx context.Context, reader io.Reader, max
 	if err != nil {
 		return nil, err
 	}
+	if !animWebP.has(cmdPath, "libwebp_anim") {
+		return nil, ErrAnimatedWebPUnsupported
+	}
 
 	args := []string{cmdPath, "-i", "pipe:0"}
 	if maxSize > 0 {
@@ -98,6 +107,19 @@ func (e *ffmpeg) ConvertAnimatedImage(ctx context.Context, reader io.Reader, max
 	return e.start(ctx, args, reader)
 }
 
+// parseEncodersOutput scans the stdout of `ffmpeg -encoders` for a whole-word
+// match of encoder name. The output has rows like " V....D libwebp_anim  ..."
+// where the name is the 2nd whitespace-separated field.
+func parseEncodersOutput(out []byte, name string) bool {
+	for line := range strings.SplitSeq(string(out), "\n") {
+		fields := strings.Fields(line)
+		if len(fields) >= 2 && fields[1] == name {
+			return true
+		}
+	}
+	return false
+}
+
 func (e *ffmpeg) ExtractImage(ctx context.Context, path string) (io.ReadCloser, error) {
 	if _, err := ffmpegCmd(); err != nil {
 		return nil, err
@@ -538,6 +560,49 @@ func ffmpegCmd() (string, error) {
 	return ffmpegPath, ffmpegErr
 }
 
+type encoderProbeState uint8
+
+const (
+	encoderProbeUnknown encoderProbeState = iota
+	encoderProbeAvailable
+	encoderProbeUnavailable
+)
+
+type encoderProbe struct {
+	mu    sync.Mutex
+	state encoderProbeState
+}
+
+func (p *encoderProbe) has(cmdPath, encoder string) bool {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	switch p.state {
+	case encoderProbeAvailable:
+		return true
+	case encoderProbeUnavailable:
+		return false
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	out, err := exec.CommandContext(ctx, cmdPath, "-hide_banner", "-encoders").Output() // #nosec
+	if err != nil {
+		log.Warn(ctx, "Could not probe ffmpeg encoders; will retry on next animated cover", err)
+		return false
+	}
+
+	if parseEncodersOutput(out, encoder) {
+		p.state = encoderProbeAvailable
+		return true
+	}
+
+	p.state = encoderProbeUnavailable
+	log.Warn(ctx, "ffmpeg has no libwebp_anim encoder; animated covers will be served as static images",
+		"path", cmdPath, "hint", "install ffmpeg built with libwebp (e.g. `brew install ffmpeg@7`)")
+	return false
+}
+
 // These variables are accessible here for tests. Do not use them directly in production code. Use ffmpegCmd() instead.
 var (
 	ffOnce     sync.Once
@@ -545,4 +610,5 @@ var (
 	ffmpegErr  error
 	probeOnce  sync.Once
 	probeAvail bool
+	animWebP   encoderProbe
 )

core/ffmpeg/ffmpeg_test.go

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

core/lyrics/lyrics_test.go

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

core/matcher/matcher.go

@@ -23,7 +23,7 @@ func New(ds model.DataStore) *Matcher {
 	return &Matcher{ds: ds}
 }
 
-// MatchSongsToLibrary matches agent song results to local library tracks using a multi-phase
+// MatchSongs matches agent song results to local library tracks using a multi-phase
 // matching algorithm that prioritizes accuracy over recall.
 //
 // # Algorithm Overview
@@ -46,18 +46,20 @@ func New(ds model.DataStore) *Matcher {
 // # Fuzzy Matching Details
 //
 // For title+artist matching, the algorithm uses Jaro-Winkler similarity (threshold configurable
-// via SimilarSongsMatchThreshold, default 85%). Matches are ranked by:
+// via Matcher.FuzzyThreshold, default 85%). Matches are ranked by:
 //
 //  1. Title similarity (Jaro-Winkler score, 0.0-1.0)
 //  2. Duration proximity (closer duration = higher score, 1.0 if unknown)
-//  3. Specificity level (0-5, based on metadata precision):
+//  3. Preferred track flag (enabled by Matcher.PreferStarred; prioritized when the track is
+//     starred or has rating >= 4)
+//  4. Specificity level (0-5, based on metadata precision):
 //     - Level 5: Title + Artist MBID + Album MBID (most specific)
 //     - Level 4: Title + Artist MBID + Album name (fuzzy)
 //     - Level 3: Title + Artist name + Album name (fuzzy)
 //     - Level 2: Title + Artist MBID
 //     - Level 1: Title + Artist name
 //     - Level 0: Title only
-//  4. Album similarity (Jaro-Winkler, as final tiebreaker)
+//  5. Album similarity (Jaro-Winkler, as final tiebreaker)
 //
 // # Examples
 //
@@ -105,25 +107,58 @@ func New(ds model.DataStore) *Matcher {
 //
 // Returns up to 'count' MediaFiles from the library that best match the input songs,
 // preserving the original order from the agent. Songs that cannot be matched are skipped.
-func (m *Matcher) MatchSongsToLibrary(ctx context.Context, songs []agents.Song, count int) (model.MediaFiles, error) {
-	idMatches, err := m.loadTracksByID(ctx, songs)
-	if err != nil {
-		return nil, fmt.Errorf("failed to load tracks by ID: %w", err)
-	}
-	mbidMatches, err := m.loadTracksByMBID(ctx, songs, idMatches)
-	if err != nil {
-		return nil, fmt.Errorf("failed to load tracks by MBID: %w", err)
-	}
-	isrcMatches, err := m.loadTracksByISRC(ctx, songs, idMatches, mbidMatches)
-	if err != nil {
-		return nil, fmt.Errorf("failed to load tracks by ISRC: %w", err)
-	}
-	titleMatches, err := m.loadTracksByTitleAndArtist(ctx, songs, idMatches, mbidMatches, isrcMatches)
-	if err != nil {
-		return nil, fmt.Errorf("failed to load tracks by title: %w", err)
+func (m *Matcher) MatchSongs(ctx context.Context, songs []agents.Song, count int) (model.MediaFiles, error) {
+	if len(songs) == 0 {
+		return nil, nil
 	}
 
-	return m.selectBestMatchingSongs(songs, idMatches, mbidMatches, isrcMatches, titleMatches, count), nil
+	byID, byMBID, byISRC, byTitle, err := m.loadAllMatches(ctx, songs)
+	if err != nil {
+		return nil, err
+	}
+	return m.selectBestMatchingSongs(songs, byID, byMBID, byISRC, byTitle, count), nil
+}
+
+// MatchSongsIndexed matches agent song results to local library tracks and returns a map
+// from input song index to matched MediaFile. Songs that cannot be matched are omitted from the map.
+// This preserves original indices, allowing callers to correlate results back to the input slice.
+func (m *Matcher) MatchSongsIndexed(ctx context.Context, songs []agents.Song) (map[int]model.MediaFile, error) {
+	if len(songs) == 0 {
+		return nil, nil
+	}
+
+	byID, byMBID, byISRC, byTitle, err := m.loadAllMatches(ctx, songs)
+	if err != nil {
+		return nil, err
+	}
+
+	result := make(map[int]model.MediaFile, len(songs))
+	for i, t := range songs {
+		if mf, found := findMatchingTrack(t, byID, byMBID, byISRC, byTitle); found {
+			result[i] = mf
+		}
+	}
+	return result, nil
+}
+
+func (m *Matcher) loadAllMatches(ctx context.Context, songs []agents.Song) (byID, byMBID, byISRC, byTitle map[string]model.MediaFile, err error) {
+	byID, err = m.loadTracksByID(ctx, songs)
+	if err != nil {
+		return nil, nil, nil, nil, fmt.Errorf("failed to load tracks by ID: %w", err)
+	}
+	byMBID, err = m.loadTracksByMBID(ctx, songs, byID)
+	if err != nil {
+		return nil, nil, nil, nil, fmt.Errorf("failed to load tracks by MBID: %w", err)
+	}
+	byISRC, err = m.loadTracksByISRC(ctx, songs, byID, byMBID)
+	if err != nil {
+		return nil, nil, nil, nil, fmt.Errorf("failed to load tracks by ISRC: %w", err)
+	}
+	byTitle, err = m.loadTracksByTitleAndArtist(ctx, songs, byID, byMBID, byISRC)
+	if err != nil {
+		return nil, nil, nil, nil, fmt.Errorf("failed to load tracks by title: %w", err)
+	}
+	return byID, byMBID, byISRC, byTitle, nil
 }
 
 // songMatchedIn checks if a song has already been matched in any of the provided match maps.
@@ -250,6 +285,7 @@ type songQuery struct {
 type matchScore struct {
 	titleSimilarity   float64
 	durationProximity float64
+	preferredMatch    bool
 	albumSimilarity   float64
 	specificityLevel  int
 }
@@ -262,6 +298,9 @@ func (s matchScore) betterThan(other matchScore) bool {
 	if s.durationProximity != other.durationProximity {
 		return s.durationProximity > other.durationProximity
 	}
+	if s.preferredMatch != other.preferredMatch {
+		return s.preferredMatch
+	}
 	if s.specificityLevel != other.specificityLevel {
 		return s.specificityLevel > other.specificityLevel
 	}
@@ -322,7 +361,7 @@ func (m *Matcher) loadTracksByTitleAndArtist(ctx context.Context, songs []agents
 		return map[string]model.MediaFile{}, nil
 	}
 
-	threshold := float64(conf.Server.SimilarSongsMatchThreshold) / 100.0
+	threshold := float64(conf.Server.Matcher.FuzzyThreshold) / 100.0
 
 	byArtist := map[string][]songQuery{}
 	for _, q := range queries {
@@ -393,6 +432,7 @@ func (m *Matcher) findBestMatch(q songQuery, sanitizedTracks []sanitizedTrack, t
 		score := matchScore{
 			titleSimilarity:   titleSim,
 			durationProximity: durationProximity(q.durationMs, t.mf.Duration),
+			preferredMatch:    conf.Server.Matcher.PreferStarred && isPreferredTrack(t.mf),
 			albumSimilarity:   albumSim,
 			specificityLevel:  computeSpecificityLevel(q, t, threshold),
 		}
@@ -406,6 +446,10 @@ func (m *Matcher) findBestMatch(q songQuery, sanitizedTracks []sanitizedTrack, t
 	return bestMatch, found
 }
 
+func isPreferredTrack(mf *model.MediaFile) bool {
+	return mf.Starred || mf.Rating >= 4
+}
+
 // buildTitleQueries converts agent songs into normalized songQuery structs for title+artist matching.
 func (m *Matcher) buildTitleQueries(songs []agents.Song, priorMatches ...map[string]model.MediaFile) []songQuery {
 	var queries []songQuery

core/matcher/matcher_test.go

@@ -75,10 +75,10 @@ var _ = Describe("Matcher", func() {
 			Return(artistTracks, nil).Maybe()
 	}
 
-	Describe("MatchSongsToLibrary", func() {
+	Describe("MatchSongs", func() {
 		Context("matching by direct ID", func() {
 			It("matches songs with an ID field to MediaFiles by ID", func() {
-				conf.Server.SimilarSongsMatchThreshold = 100
+				conf.Server.Matcher.FuzzyThreshold = 100
 				songs := []agents.Song{
 					{ID: "track-1", Name: "Some Song", Artist: "Some Artist"},
 				}
@@ -87,7 +87,7 @@ var _ = Describe("Matcher", func() {
 				}
 				expectIDPhase(model.MediaFiles{idMatch})
 				allowOtherPhases()
-				result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+				result, err := m.MatchSongs(ctx, songs, 5)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(result).To(HaveLen(1))
 				Expect(result[0].ID).To(Equal("track-1"))
@@ -96,7 +96,7 @@ var _ = Describe("Matcher", func() {
 
 		Context("matching by MBID", func() {
 			It("matches songs with MBID to tracks with matching mbz_recording_id", func() {
-				conf.Server.SimilarSongsMatchThreshold = 100
+				conf.Server.Matcher.FuzzyThreshold = 100
 				songs := []agents.Song{
 					{Name: "Paranoid Android", MBID: "abc-123", Artist: "Radiohead"},
 				}
@@ -106,7 +106,7 @@ var _ = Describe("Matcher", func() {
 				}
 				expectMBIDPhase(model.MediaFiles{mbidMatch})
 				allowOtherPhases()
-				result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+				result, err := m.MatchSongs(ctx, songs, 5)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(result).To(HaveLen(1))
 				Expect(result[0].ID).To(Equal("track-mbid"))
@@ -115,7 +115,7 @@ var _ = Describe("Matcher", func() {
 
 		Context("matching by ISRC", func() {
 			It("matches songs with ISRC to tracks with matching ISRC tag", func() {
-				conf.Server.SimilarSongsMatchThreshold = 100
+				conf.Server.Matcher.FuzzyThreshold = 100
 				songs := []agents.Song{
 					{Name: "Paranoid Android", ISRC: "GBAYE0000351", Artist: "Radiohead"},
 				}
@@ -125,7 +125,7 @@ var _ = Describe("Matcher", func() {
 				}
 				expectISRCPhase(model.MediaFiles{isrcMatch})
 				allowOtherPhases()
-				result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+				result, err := m.MatchSongs(ctx, songs, 5)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(result).To(HaveLen(1))
 				Expect(result[0].ID).To(Equal("track-isrc"))
@@ -134,7 +134,7 @@ var _ = Describe("Matcher", func() {
 
 		Context("fuzzy title+artist matching", func() {
 			It("matches songs by title and artist name", func() {
-				conf.Server.SimilarSongsMatchThreshold = 100
+				conf.Server.Matcher.FuzzyThreshold = 100
 				songs := []agents.Song{
 					{Name: "Enjoy the Silence", Artist: "Depeche Mode"},
 				}
@@ -142,14 +142,14 @@ var _ = Describe("Matcher", func() {
 					ID: "track-title", Title: "Enjoy the Silence", Artist: "Depeche Mode",
 				}
 				setupTitleOnlyExpectations(model.MediaFiles{titleMatch})
-				result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+				result, err := m.MatchSongs(ctx, songs, 5)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(result).To(HaveLen(1))
 				Expect(result[0].ID).To(Equal("track-title"))
 			})
 
 			It("matches songs with fuzzy title similarity", func() {
-				conf.Server.SimilarSongsMatchThreshold = 85
+				conf.Server.Matcher.FuzzyThreshold = 85
 				songs := []agents.Song{
 					{Name: "Bohemian Rhapsody", Artist: "Queen"},
 				}
@@ -157,14 +157,14 @@ var _ = Describe("Matcher", func() {
 					ID: "track-fuzzy", Title: "Bohemian Rhapsody (Live)", Artist: "Queen",
 				}
 				setupTitleOnlyExpectations(model.MediaFiles{fuzzyMatch})
-				result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+				result, err := m.MatchSongs(ctx, songs, 5)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(result).To(HaveLen(1))
 				Expect(result[0].ID).To(Equal("track-fuzzy"))
 			})
 
 			It("does not match completely different titles", func() {
-				conf.Server.SimilarSongsMatchThreshold = 85
+				conf.Server.Matcher.FuzzyThreshold = 85
 				songs := []agents.Song{
 					{Name: "Yesterday", Artist: "The Beatles"},
 				}
@@ -172,7 +172,7 @@ var _ = Describe("Matcher", func() {
 					{ID: "different", Title: "Tomorrow Never Knows", Artist: "The Beatles"},
 				}
 				setupTitleOnlyExpectations(differentTracks)
-				result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+				result, err := m.MatchSongs(ctx, songs, 5)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(result).To(BeEmpty())
 			})
@@ -180,7 +180,7 @@ var _ = Describe("Matcher", func() {
 
 		Context("deduplication", func() {
 			It("removes duplicates when different input songs match the same library track", func() {
-				conf.Server.SimilarSongsMatchThreshold = 85
+				conf.Server.Matcher.FuzzyThreshold = 85
 				songs := []agents.Song{
 					{Name: "Bohemian Rhapsody (Live)", Artist: "Queen"},
 					{Name: "Bohemian Rhapsody (Original Mix)", Artist: "Queen"},
@@ -189,14 +189,14 @@ var _ = Describe("Matcher", func() {
 					ID: "br-live", Title: "Bohemian Rhapsody (Live)", Artist: "Queen",
 				}
 				setupTitleOnlyExpectations(model.MediaFiles{libraryTrack})
-				result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+				result, err := m.MatchSongs(ctx, songs, 5)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(result).To(HaveLen(1))
 				Expect(result[0].ID).To(Equal("br-live"))
 			})
 
 			It("preserves duplicates when identical input songs match the same library track", func() {
-				conf.Server.SimilarSongsMatchThreshold = 85
+				conf.Server.Matcher.FuzzyThreshold = 85
 				songs := []agents.Song{
 					{Name: "Bohemian Rhapsody", Artist: "Queen", Album: "A Night at the Opera"},
 					{Name: "Bohemian Rhapsody", Artist: "Queen", Album: "A Night at the Opera"},
@@ -205,7 +205,7 @@ var _ = Describe("Matcher", func() {
 					ID: "br", Title: "Bohemian Rhapsody", Artist: "Queen", Album: "A Night at the Opera",
 				}
 				setupTitleOnlyExpectations(model.MediaFiles{libraryTrack})
-				result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+				result, err := m.MatchSongs(ctx, songs, 5)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(result).To(HaveLen(2))
 				Expect(result[0].ID).To(Equal("br"))
@@ -215,7 +215,7 @@ var _ = Describe("Matcher", func() {
 
 		Context("priority ordering", func() {
 			It("prefers ID match over MBID match", func() {
-				conf.Server.SimilarSongsMatchThreshold = 100
+				conf.Server.Matcher.FuzzyThreshold = 100
 				// Song has both ID and MBID set. The matcher should resolve via ID
 				// and short-circuit the MBID phase entirely, so no MBID fetch should
 				// occur even though an mbz_recording_id exists in the input.
@@ -227,7 +227,7 @@ var _ = Describe("Matcher", func() {
 				}
 				expectIDPhase(model.MediaFiles{idMatch})
 				allowOtherPhases()
-				result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+				result, err := m.MatchSongs(ctx, songs, 5)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(result).To(HaveLen(1))
 				Expect(result[0].ID).To(Equal("track-id"))
@@ -236,7 +236,7 @@ var _ = Describe("Matcher", func() {
 
 		Context("count limit", func() {
 			It("returns at most 'count' results", func() {
-				conf.Server.SimilarSongsMatchThreshold = 100
+				conf.Server.Matcher.FuzzyThreshold = 100
 				songs := []agents.Song{
 					{Name: "Song A", Artist: "Artist"},
 					{Name: "Song B", Artist: "Artist"},
@@ -248,7 +248,7 @@ var _ = Describe("Matcher", func() {
 					{ID: "c", Title: "Song C", Artist: "Artist"},
 				}
 				setupTitleOnlyExpectations(tracks)
-				result, err := m.MatchSongsToLibrary(ctx, songs, 2)
+				result, err := m.MatchSongs(ctx, songs, 2)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(result).To(HaveLen(2))
 			})
@@ -256,16 +256,63 @@ var _ = Describe("Matcher", func() {
 
 		Context("empty input", func() {
 			It("returns empty results for no songs", func() {
-				result, err := m.MatchSongsToLibrary(ctx, []agents.Song{}, 5)
+				result, err := m.MatchSongs(ctx, []agents.Song{}, 5)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(result).To(BeEmpty())
 			})
 		})
 	})
 
+	Describe("MatchSongsIndexed", func() {
+		It("returns index-keyed map of matched songs", func() {
+			songs := []agents.Song{
+				{ID: "track-1", Name: "Song One", Artist: "Artist A"},
+				{ID: "track-2", Name: "Song Two", Artist: "Artist B"},
+				{ID: "track-3", Name: "Song Three", Artist: "Artist C"},
+			}
+			mf1 := model.MediaFile{ID: "track-1", Title: "Song One", Artist: "Artist A"}
+			mf2 := model.MediaFile{ID: "track-2", Title: "Song Two", Artist: "Artist B"}
+
+			expectIDPhase(model.MediaFiles{mf1, mf2})
+			allowOtherPhases()
+
+			result, err := m.MatchSongsIndexed(ctx, songs)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(2))
+			Expect(result[0].ID).To(Equal("track-1"))
+			Expect(result[1].ID).To(Equal("track-2"))
+			_, exists := result[2]
+			Expect(exists).To(BeFalse())
+		})
+
+		It("preserves original indices when some songs don't match", func() {
+			songs := []agents.Song{
+				{Name: "Unknown Song", Artist: "Unknown Artist"},
+				{ID: "track-1", Name: "Known Song", Artist: "Known Artist"},
+			}
+			mf1 := model.MediaFile{ID: "track-1", Title: "Known Song", Artist: "Known Artist"}
+
+			expectIDPhase(model.MediaFiles{mf1})
+			allowOtherPhases()
+
+			result, err := m.MatchSongsIndexed(ctx, songs)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(1))
+			_, exists := result[0]
+			Expect(exists).To(BeFalse())
+			Expect(result[1].ID).To(Equal("track-1"))
+		})
+
+		It("returns empty map for empty input", func() {
+			result, err := m.MatchSongsIndexed(ctx, nil)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(BeEmpty())
+		})
+	})
+
 	Describe("specificity level matching", func() {
 		BeforeEach(func() {
-			conf.Server.SimilarSongsMatchThreshold = 100
+			conf.Server.Matcher.FuzzyThreshold = 100
 		})
 
 		It("matches by title + artist MBID + album MBID (highest priority)", func() {
@@ -283,7 +330,7 @@ var _ = Describe("Matcher", func() {
 
 			setupTitleOnlyExpectations(model.MediaFiles{wrongMatch, correctMatch})
 
-			result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+			result, err := m.MatchSongs(ctx, songs, 5)
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(result).To(HaveLen(1))
@@ -303,7 +350,7 @@ var _ = Describe("Matcher", func() {
 
 			setupTitleOnlyExpectations(model.MediaFiles{wrongMatch, correctMatch})
 
-			result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+			result, err := m.MatchSongs(ctx, songs, 5)
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(result).To(HaveLen(1))
@@ -323,7 +370,7 @@ var _ = Describe("Matcher", func() {
 
 			setupTitleOnlyExpectations(model.MediaFiles{wrongMatch, correctMatch})
 
-			result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+			result, err := m.MatchSongs(ctx, songs, 5)
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(result).To(HaveLen(1))
@@ -337,7 +384,7 @@ var _ = Describe("Matcher", func() {
 
 			setupTitleOnlyExpectations(model.MediaFiles{})
 
-			result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+			result, err := m.MatchSongs(ctx, songs, 5)
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(result).To(BeEmpty())
@@ -356,7 +403,7 @@ var _ = Describe("Matcher", func() {
 
 			setupTitleOnlyExpectations(model.MediaFiles{cover1, cover2, cover3})
 
-			result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+			result, err := m.MatchSongs(ctx, songs, 5)
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(result).To(HaveLen(3))
@@ -384,7 +431,7 @@ var _ = Describe("Matcher", func() {
 
 			setupTitleOnlyExpectations(model.MediaFiles{lessAccurateMatch, preciseMatch, artistTwoMatch})
 
-			result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+			result, err := m.MatchSongs(ctx, songs, 5)
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(result).To(HaveLen(2))
@@ -396,7 +443,7 @@ var _ = Describe("Matcher", func() {
 	Describe("fuzzy matching thresholds", func() {
 		Context("with default threshold (85%)", func() {
 			It("matches songs with remastered suffix", func() {
-				conf.Server.SimilarSongsMatchThreshold = 85
+				conf.Server.Matcher.FuzzyThreshold = 85
 
 				songs := []agents.Song{
 					{Name: "Paranoid Android", Artist: "Radiohead"},
@@ -407,7 +454,7 @@ var _ = Describe("Matcher", func() {
 
 				setupTitleOnlyExpectations(artistTracks)
 
-				result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+				result, err := m.MatchSongs(ctx, songs, 5)
 
 				Expect(err).ToNot(HaveOccurred())
 				Expect(result).To(HaveLen(1))
@@ -415,7 +462,7 @@ var _ = Describe("Matcher", func() {
 			})
 
 			It("matches songs with live suffix", func() {
-				conf.Server.SimilarSongsMatchThreshold = 85
+				conf.Server.Matcher.FuzzyThreshold = 85
 
 				songs := []agents.Song{
 					{Name: "Bohemian Rhapsody", Artist: "Queen"},
@@ -426,7 +473,7 @@ var _ = Describe("Matcher", func() {
 
 				setupTitleOnlyExpectations(artistTracks)
 
-				result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+				result, err := m.MatchSongs(ctx, songs, 5)
 
 				Expect(err).ToNot(HaveOccurred())
 				Expect(result).To(HaveLen(1))
@@ -436,7 +483,7 @@ var _ = Describe("Matcher", func() {
 
 		Context("with threshold set to 100 (exact match only)", func() {
 			It("only matches exact titles", func() {
-				conf.Server.SimilarSongsMatchThreshold = 100
+				conf.Server.Matcher.FuzzyThreshold = 100
 
 				songs := []agents.Song{
 					{Name: "Paranoid Android", Artist: "Radiohead"},
@@ -447,7 +494,7 @@ var _ = Describe("Matcher", func() {
 
 				setupTitleOnlyExpectations(artistTracks)
 
-				result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+				result, err := m.MatchSongs(ctx, songs, 5)
 
 				Expect(err).ToNot(HaveOccurred())
 				Expect(result).To(BeEmpty())
@@ -456,7 +503,7 @@ var _ = Describe("Matcher", func() {
 
 		Context("with lower threshold (75%)", func() {
 			It("matches more aggressively", func() {
-				conf.Server.SimilarSongsMatchThreshold = 75
+				conf.Server.Matcher.FuzzyThreshold = 75
 
 				songs := []agents.Song{
 					{Name: "Song", Artist: "Artist"},
@@ -467,7 +514,7 @@ var _ = Describe("Matcher", func() {
 
 				setupTitleOnlyExpectations(artistTracks)
 
-				result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+				result, err := m.MatchSongs(ctx, songs, 5)
 
 				Expect(err).ToNot(HaveOccurred())
 				Expect(result).To(HaveLen(1))
@@ -478,7 +525,8 @@ var _ = Describe("Matcher", func() {
 
 	Describe("fuzzy album matching", func() {
 		BeforeEach(func() {
-			conf.Server.SimilarSongsMatchThreshold = 85
+			conf.Server.Matcher.FuzzyThreshold = 85
+			conf.Server.Matcher.PreferStarred = false
 		})
 
 		It("matches album with (Remaster) suffix", func() {
@@ -494,7 +542,7 @@ var _ = Describe("Matcher", func() {
 
 			setupTitleOnlyExpectations(model.MediaFiles{wrongMatch, correctMatch})
 
-			result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+			result, err := m.MatchSongs(ctx, songs, 5)
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(result).To(HaveLen(1))
@@ -514,7 +562,7 @@ var _ = Describe("Matcher", func() {
 
 			setupTitleOnlyExpectations(model.MediaFiles{wrongMatch, correctMatch})
 
-			result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+			result, err := m.MatchSongs(ctx, songs, 5)
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(result).To(HaveLen(1))
@@ -534,17 +582,59 @@ var _ = Describe("Matcher", func() {
 
 			setupTitleOnlyExpectations(model.MediaFiles{fuzzyMatch, exactMatch})
 
-			result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+			result, err := m.MatchSongs(ctx, songs, 5)
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(result).To(HaveLen(1))
 			Expect(result[0].ID).To(Equal("exact"))
 		})
+
+		It("prefers starred songs over better album match when enabled", func() {
+			conf.Server.Matcher.PreferStarred = true
+			songs := []agents.Song{
+				{Name: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator"},
+			}
+			albumMatch := model.MediaFile{
+				ID: "album-match", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator",
+			}
+			starredTrack := model.MediaFile{
+				ID: "starred", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Singles", Annotations: model.Annotations{Starred: true},
+			}
+
+			setupTitleOnlyExpectations(model.MediaFiles{albumMatch, starredTrack})
+
+			result, err := m.MatchSongs(ctx, songs, 5)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(1))
+			Expect(result[0].ID).To(Equal("starred"))
+		})
+
+		It("prefers 4-star songs over better album match when enabled", func() {
+			conf.Server.Matcher.PreferStarred = true
+			songs := []agents.Song{
+				{Name: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator"},
+			}
+			albumMatch := model.MediaFile{
+				ID: "album-match", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Violator",
+			}
+			ratedTrack := model.MediaFile{
+				ID: "rated", Title: "Enjoy the Silence", Artist: "Depeche Mode", Album: "Singles", Annotations: model.Annotations{Rating: 4},
+			}
+
+			setupTitleOnlyExpectations(model.MediaFiles{albumMatch, ratedTrack})
+
+			result, err := m.MatchSongs(ctx, songs, 5)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(result).To(HaveLen(1))
+			Expect(result[0].ID).To(Equal("rated"))
+		})
 	})
 
 	Describe("duration matching", func() {
 		BeforeEach(func() {
-			conf.Server.SimilarSongsMatchThreshold = 100
+			conf.Server.Matcher.FuzzyThreshold = 100
 		})
 
 		It("prefers tracks with matching duration", func() {
@@ -560,7 +650,7 @@ var _ = Describe("Matcher", func() {
 
 			setupTitleOnlyExpectations(model.MediaFiles{wrongDuration, correctMatch})
 
-			result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+			result, err := m.MatchSongs(ctx, songs, 5)
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(result).To(HaveLen(1))
@@ -577,7 +667,7 @@ var _ = Describe("Matcher", func() {
 
 			setupTitleOnlyExpectations(model.MediaFiles{closeDuration})
 
-			result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+			result, err := m.MatchSongs(ctx, songs, 5)
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(result).To(HaveLen(1))
@@ -597,7 +687,7 @@ var _ = Describe("Matcher", func() {
 
 			setupTitleOnlyExpectations(model.MediaFiles{farDuration, closeDuration})
 
-			result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+			result, err := m.MatchSongs(ctx, songs, 5)
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(result).To(HaveLen(1))
@@ -614,7 +704,7 @@ var _ = Describe("Matcher", func() {
 
 			setupTitleOnlyExpectations(model.MediaFiles{differentDuration})
 
-			result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+			result, err := m.MatchSongs(ctx, songs, 5)
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(result).To(HaveLen(1))
@@ -634,7 +724,7 @@ var _ = Describe("Matcher", func() {
 
 			setupTitleOnlyExpectations(model.MediaFiles{differentTitle, correctTitle})
 
-			result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+			result, err := m.MatchSongs(ctx, songs, 5)
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(result).To(HaveLen(1))
@@ -651,7 +741,7 @@ var _ = Describe("Matcher", func() {
 
 			setupTitleOnlyExpectations(model.MediaFiles{anyTrack})
 
-			result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+			result, err := m.MatchSongs(ctx, songs, 5)
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(result).To(HaveLen(1))
@@ -668,7 +758,7 @@ var _ = Describe("Matcher", func() {
 
 			setupTitleOnlyExpectations(model.MediaFiles{shortTrack})
 
-			result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+			result, err := m.MatchSongs(ctx, songs, 5)
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(result).To(HaveLen(1))
@@ -678,7 +768,7 @@ var _ = Describe("Matcher", func() {
 
 	Describe("deduplication edge cases", func() {
 		BeforeEach(func() {
-			conf.Server.SimilarSongsMatchThreshold = 85
+			conf.Server.Matcher.FuzzyThreshold = 85
 		})
 
 		It("handles mixed scenario with both identical and different input songs", func() {
@@ -694,7 +784,7 @@ var _ = Describe("Matcher", func() {
 
 			setupTitleOnlyExpectations(model.MediaFiles{libraryTrack})
 
-			result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+			result, err := m.MatchSongs(ctx, songs, 5)
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(result).To(HaveLen(2))
@@ -714,7 +804,7 @@ var _ = Describe("Matcher", func() {
 
 			setupTitleOnlyExpectations(model.MediaFiles{trackA, trackB, trackC})
 
-			result, err := m.MatchSongsToLibrary(ctx, songs, 5)
+			result, err := m.MatchSongs(ctx, songs, 5)
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(result).To(HaveLen(3))
@@ -735,7 +825,7 @@ var _ = Describe("Matcher", func() {
 
 			setupTitleOnlyExpectations(model.MediaFiles{trackA, trackB})
 
-			result, err := m.MatchSongsToLibrary(ctx, songs, 2)
+			result, err := m.MatchSongs(ctx, songs, 2)
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(result).To(HaveLen(2))

core/playback/mpv/mpv_test.go

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

core/playlists/import.go

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

core/playlists/import_test.go

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

core/playlists/parse_m3u.go

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

core/playlists/parse_m3u_test.go

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

core/playlists/playlists.go

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

core/playlists/rest_adapter.go

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

core/playlists/rest_adapter_test.go

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

core/sonic/sonic.go

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

core/sonic/sonic_suite_test.go

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

core/sonic/sonic_test.go

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

core/storage/local/local_test.go

@@ -13,6 +13,7 @@ import (
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/core/storage"
 	"github.com/navidrome/navidrome/model/metadata"
+	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -44,6 +45,10 @@ var _ = Describe("LocalStorage", func() {
 	})
 
 	Describe("newLocalStorage", func() {
+		BeforeEach(func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-storage-local)")
+		})
+
 		Context("with valid path", func() {
 			It("should create a localStorage instance with correct path", func() {
 				u, err := url.Parse("file://" + tempDir)
@@ -166,6 +171,10 @@ var _ = Describe("LocalStorage", func() {
 	})
 
 	Describe("localStorage.FS", func() {
+		BeforeEach(func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-storage-local)")
+		})
+
 		Context("with existing directory", func() {
 			It("should return a localFS instance", func() {
 				u, err := url.Parse("file://" + tempDir)
@@ -199,6 +208,7 @@ var _ = Describe("LocalStorage", func() {
 		var testFile string
 
 		BeforeEach(func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-storage-local)")
 			// Create a test file
 			testFile = filepath.Join(tempDir, "test.mp3")
 			err := os.WriteFile(testFile, []byte("test data"), 0600)
@@ -380,6 +390,7 @@ var _ = Describe("LocalStorage", func() {
 
 	Describe("Storage registration", func() {
 		It("should register localStorage for file scheme", func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-storage-local)")
 			// This tests the init() function indirectly
 			storage, err := storage.For("file://" + tempDir)
 			Expect(err).ToNot(HaveOccurred())

core/storage/storage_test.go

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

go.mod

@@ -9,7 +9,6 @@ require (
 	github.com/Masterminds/squirrel v1.5.4
 	github.com/andybalholm/cascadia v1.3.3
 	github.com/bmatcuk/doublestar/v4 v4.10.0
-	github.com/bradleyjkemp/cupaloy/v2 v2.8.0
 	github.com/deluan/rest v0.0.0-20211102003136-6260bc399cbf
 	github.com/deluan/sanitize v0.0.0-20241120162836-fdfd8fdfaa55
 	github.com/dexterlb/mpvipc v0.0.0-20241005113212-7cdefca0e933
@@ -35,15 +34,16 @@ require (
 	github.com/jellydator/ttlcache/v3 v3.4.0
 	github.com/kardianos/service v1.2.4
 	github.com/kr/pretty v0.3.1
-	github.com/lestrrat-go/jwx/v3 v3.0.13
+	github.com/lestrrat-go/jwx/v3 v3.1.0
 	github.com/mattn/go-sqlite3 v1.14.42
 	github.com/microcosm-cc/bluemonday v1.0.27
 	github.com/mileusna/useragent v1.3.5
-	github.com/onsi/ginkgo/v2 v2.28.1
+	github.com/onsi/ginkgo/v2 v2.28.2
 	github.com/onsi/gomega v1.39.1
 	github.com/pelletier/go-toml/v2 v2.3.0
+	github.com/pmezard/go-difflib v1.0.0
 	github.com/pocketbase/dbx v1.12.0
-	github.com/pressly/goose/v3 v3.27.0
+	github.com/pressly/goose/v3 v3.27.1
 	github.com/prometheus/client_golang v1.23.2
 	github.com/rjeczalik/notify v0.9.3
 	github.com/robfig/cron/v3 v3.0.1
@@ -112,10 +112,9 @@ require (
 	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
 	github.com/ogier/pflag v0.0.1 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
-	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
 	github.com/prometheus/client_model v0.6.2 // indirect
 	github.com/prometheus/common v0.67.5 // indirect
-	github.com/prometheus/procfs v0.19.2 // indirect
+	github.com/prometheus/procfs v0.20.1 // indirect
 	github.com/rogpeppe/go-internal v1.14.1 // indirect
 	github.com/sagikazarmark/locafero v0.12.0 // indirect
 	github.com/sanity-io/litter v1.5.8 // indirect

go.sum

@@ -16,8 +16,6 @@ github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
 github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
 github.com/bmatcuk/doublestar/v4 v4.10.0 h1:zU9WiOla1YA122oLM6i4EXvGW62DvKZVxIe6TYWexEs=
 github.com/bmatcuk/doublestar/v4 v4.10.0/go.mod h1:xBQ8jztBU6kakFMg+8WGxn0c6z1fTSPVIjEY1Wr7jzc=
-github.com/bradleyjkemp/cupaloy/v2 v2.8.0 h1:any4BmKE+jGIaMpnU8YgH/I2LPiLBufr6oMMlVBbn9M=
-github.com/bradleyjkemp/cupaloy/v2 v2.8.0/go.mod h1:bm7JXdkRd4BHJk9HpwqAI8BoAY1lps46Enkdqw6aRX0=
 github.com/cespare/reflex v0.3.1 h1:N4Y/UmRrjwOkNT0oQQnYsdr6YBxvHqtSfPB4mqOyAKk=
 github.com/cespare/reflex v0.3.1/go.mod h1:I+0Pnu2W693i7Hv6ZZG76qHTY0mgUa7uCIfCtikXojE=
 github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
@@ -141,8 +139,8 @@ github.com/kardianos/service v1.2.4 h1:XNlGtZOYNx2u91urOdg/Kfmc+gfmuIo1Dd3rEi2Og
 github.com/kardianos/service v1.2.4/go.mod h1:E4V9ufUuY82F7Ztlu1eN9VXWIQxg8NoLQlmFe0MtrXc=
 github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51 h1:Z9n2FFNUXsshfwJMBgNA0RU6/i7WVaAegv3PtuIHPMs=
 github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51/go.mod h1:CzGEWj7cYgsdH8dAjBGEr58BoE7ScuLd+fwFZ44+/x8=
-github.com/klauspost/compress v1.18.4 h1:RPhnKRAQ4Fh8zU2FY/6ZFDwTVTxgJ/EMydqSTzE9a2c=
-github.com/klauspost/compress v1.18.4/go.mod h1:R0h/fSBs8DE4ENlcrlib3PsXS61voFxhIs2DeRhCvJ4=
+github.com/klauspost/compress v1.18.5 h1:/h1gH5Ce+VWNLSWqPzOVn6XBO+vJbCNGvjoaGBFW2IE=
+github.com/klauspost/compress v1.18.5/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
 github.com/klauspost/cpuid/v2 v2.3.0 h1:S4CRMLnYUhGeDFDqkGriYKdfoFlDnMtqTiI/sFzhA9Y=
 github.com/klauspost/cpuid/v2 v2.3.0/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
 github.com/konsorten/go-windows-terminal-sequences v1.0.1/go.mod h1:T0+1ngSBFLxvqU3pZ+m/2kptfBszLMUkC4ZK/EgS/cQ=
@@ -169,14 +167,14 @@ github.com/lestrrat-go/httpcc v1.0.1 h1:ydWCStUeJLkpYyjLDHihupbn2tYmZ7m22BGkcvZZ
 github.com/lestrrat-go/httpcc v1.0.1/go.mod h1:qiltp3Mt56+55GPVCbTdM9MlqhvzyuL6W/NMDA8vA5E=
 github.com/lestrrat-go/httprc/v3 v3.0.5 h1:S+Mb4L2I+bM6JGTibLmxExhyTOqnXjqx+zi9MoXw/TM=
 github.com/lestrrat-go/httprc/v3 v3.0.5/go.mod h1:mSMtkZW92Z98M5YoNNztbRGxbXHql7tSitCvaxvo9l0=
-github.com/lestrrat-go/jwx/v3 v3.0.13 h1:AdHKiPIYeCSnOJtvdpipPg/0SuFh9rdkN+HF3O0VdSk=
-github.com/lestrrat-go/jwx/v3 v3.0.13/go.mod h1:2m0PV1A9tM4b/jVLMx8rh6rBl7F6WGb3EG2hufN9OQU=
+github.com/lestrrat-go/jwx/v3 v3.1.0 h1:AyyLtxc0QM75F75JroWgt1phwC7X+wOb3XKhH7XBZWw=
+github.com/lestrrat-go/jwx/v3 v3.1.0/go.mod h1:uw/MN2M/Xiu4FhwcIwH11Zsh9JWx9SWzgALl7/uIEkU=
 github.com/lestrrat-go/option/v2 v2.0.0 h1:XxrcaJESE1fokHy3FpaQ/cXW8ZsIdWcdFzzLOcID3Ss=
 github.com/lestrrat-go/option/v2 v2.0.0/go.mod h1:oSySsmzMoR0iRzCDCaUfsCzxQHUEuhOViQObyy7S6Vg=
 github.com/maruel/natural v1.3.0 h1:VsmCsBmEyrR46RomtgHs5hbKADGRVtliHTyCOLFBpsg=
 github.com/maruel/natural v1.3.0/go.mod h1:v+Rfd79xlw1AgVBjbO0BEQmptqb5HvL/k9GRHB7ZKEg=
-github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
-github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mattn/go-isatty v0.0.21 h1:xYae+lCNBP7QuW4PUnNG61ffM4hVIfm+zUzDuSzYLGs=
+github.com/mattn/go-isatty v0.0.21/go.mod h1:ZXfXG4SQHsB/w3ZeOYbR0PrPwLy+n6xiMrJlRFqopa4=
 github.com/mattn/go-sqlite3 v1.14.42 h1:MigqEP4ZmHw3aIdIT7T+9TLa90Z6smwcthx+Azv4Cgo=
 github.com/mattn/go-sqlite3 v1.14.42/go.mod h1:pjEuOr8IwzLJP2MfGeTb0A35jauH+C2kbHKBr7yXKVQ=
 github.com/mfridman/interpolate v0.0.2 h1:pnuTK7MQIxxFz1Gr+rjSIx9u7qVjf5VOoM/u6BbAxPY=
@@ -195,8 +193,8 @@ github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOF
 github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
 github.com/ogier/pflag v0.0.1 h1:RW6JSWSu/RkSatfcLtogGfFgpim5p7ARQ10ECk5O750=
 github.com/ogier/pflag v0.0.1/go.mod h1:zkFki7tvTa0tafRvTBIZTvzYyAu6kQhPZFnshFFPE+g=
-github.com/onsi/ginkgo/v2 v2.28.1 h1:S4hj+HbZp40fNKuLUQOYLDgZLwNUVn19N3Atb98NCyI=
-github.com/onsi/ginkgo/v2 v2.28.1/go.mod h1:CLtbVInNckU3/+gC8LzkGUb9oF+e8W8TdUsxPwvdOgE=
+github.com/onsi/ginkgo/v2 v2.28.2 h1:DTrMfpqxiNUyQ3Y0zhn1n3cOO2euFgQPYIpkWwxVFps=
+github.com/onsi/ginkgo/v2 v2.28.2/go.mod h1:CLtbVInNckU3/+gC8LzkGUb9oF+e8W8TdUsxPwvdOgE=
 github.com/onsi/gomega v1.39.1 h1:1IJLAad4zjPn2PsnhH70V4DKRFlrCzGBNrNaru+Vf28=
 github.com/onsi/gomega v1.39.1/go.mod h1:hL6yVALoTOxeWudERyfppUcZXjMwIMLnuSfruD2lcfg=
 github.com/pelletier/go-toml/v2 v2.3.0 h1:k59bC/lIZREW0/iVaQR8nDHxVq8OVlIzYCOJf421CaM=
@@ -205,21 +203,20 @@ github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsK
 github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v0.0.0-20151028094244-d8ed2627bdf0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
-github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/pocketbase/dbx v1.12.0 h1:/oLErM+A0b4xI0PWTGPqSDVjzix48PqI/bng2l0PzoA=
 github.com/pocketbase/dbx v1.12.0/go.mod h1:xXRCIAKTHMgUCyCKZm55pUOdvFziJjQfXaWKhu2vhMs=
-github.com/pressly/goose/v3 v3.27.0 h1:/D30gVTuQhu0WsNZYbJi4DMOsx1lNq+6SkLe+Wp59BM=
-github.com/pressly/goose/v3 v3.27.0/go.mod h1:3ZBeCXqzkgIRvrEMDkYh1guvtoJTU5oMMuDdkutoM78=
+github.com/pressly/goose/v3 v3.27.1 h1:6uEvcprBybDmW4hcz3gYujhARhye+GoWKhEWyzD5sh4=
+github.com/pressly/goose/v3 v3.27.1/go.mod h1:maruOxsPnIG2yHHyo8UqKWXYKFcH7Q76csUV7+7KYoM=
 github.com/prometheus/client_golang v1.23.2 h1:Je96obch5RDVy3FDMndoUsjAhG5Edi49h0RJWRi/o0o=
 github.com/prometheus/client_golang v1.23.2/go.mod h1:Tb1a6LWHB3/SPIzCoaDXI4I8UHKeFTEQ1YCr+0Gyqmg=
 github.com/prometheus/client_model v0.6.2 h1:oBsgwpGs7iVziMvrGhE53c/GrLUsZdHnqNwqPLxwZyk=
 github.com/prometheus/client_model v0.6.2/go.mod h1:y3m2F6Gdpfy6Ut/GBsUqTWZqCUvMVzSfMLjcu6wAwpE=
 github.com/prometheus/common v0.67.5 h1:pIgK94WWlQt1WLwAC5j2ynLaBRDiinoAb86HZHTUGI4=
 github.com/prometheus/common v0.67.5/go.mod h1:SjE/0MzDEEAyrdr5Gqc6G+sXI67maCxzaT3A2+HqjUw=
-github.com/prometheus/procfs v0.19.2 h1:zUMhqEW66Ex7OXIiDkll3tl9a1ZdilUOd/F6ZXw4Vws=
-github.com/prometheus/procfs v0.19.2/go.mod h1:M0aotyiemPhBCM0z5w87kL22CxfcH05ZpYlu+b4J7mw=
+github.com/prometheus/procfs v0.20.1 h1:XwbrGOIplXW/AU3YhIhLODXMJYyC1isLFfYCsTEycfc=
+github.com/prometheus/procfs v0.20.1/go.mod h1:o9EMBZGRyvDrSPH1RqdxhojkuXstoe4UlK79eF5TGGo=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
 github.com/rjeczalik/notify v0.9.3 h1:6rJAzHTGKXGj76sbRgDiDcYj/HniypXmSJo1SWakZeY=
@@ -321,8 +318,6 @@ golang.org/x/crypto v0.23.0/go.mod h1:CKFgDieR+mRhux2Lsu27y0fO304Db0wZe70UKqHu0v
 golang.org/x/crypto v0.31.0/go.mod h1:kDsLvtWBEx7MV9tJOj9bnXsPbxwJQ6csT/x4KIN4Ssk=
 golang.org/x/crypto v0.50.0 h1:zO47/JPrL6vsNkINmLoo/PH1gcxpls50DNogFvB5ZGI=
 golang.org/x/crypto v0.50.0/go.mod h1:3muZ7vA7PBCE6xgPX7nkzzjiUq87kRItoJQM1Yo8S+Q=
-golang.org/x/exp v0.0.0-20260218203240-3dfff04db8fa h1:Zt3DZoOFFYkKhDT3v7Lm9FDMEV06GpzjG2jrqW+QTE0=
-golang.org/x/exp v0.0.0-20260218203240-3dfff04db8fa/go.mod h1:K79w1Vqn7PoiZn+TkNpx3BUWUQksGO3JcVX6qIjytmA=
 golang.org/x/image v0.39.0 h1:skVYidAEVKgn8lZ602XO75asgXBgLj9G/FE3RbuPFww=
 golang.org/x/image v0.39.0/go.mod h1:sIbmppfU+xFLPIG0FoVUTvyBMmgng1/XAMhQ2ft0hpA=
 golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
@@ -422,11 +417,11 @@ gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
-modernc.org/libc v1.68.0 h1:PJ5ikFOV5pwpW+VqCK1hKJuEWsonkIJhhIXyuF/91pQ=
-modernc.org/libc v1.68.0/go.mod h1:NnKCYeoYgsEqnY3PgvNgAeaJnso968ygU8Z0DxjoEc0=
+modernc.org/libc v1.72.1 h1:db1xwJ6u1kE3KHTFTTbe2GCrczHPKzlURP0aDC4NGD0=
+modernc.org/libc v1.72.1/go.mod h1:HRMiC/PhPGLIPM7GzAFCbI+oSgE3dhZ8FWftmRrHVlY=
 modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
 modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
 modernc.org/memory v1.11.0 h1:o4QC8aMQzmcwCK3t3Ux/ZHmwFPzE6hf2Y5LbkRs+hbI=
 modernc.org/memory v1.11.0/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
-modernc.org/sqlite v1.46.1 h1:eFJ2ShBLIEnUWlLy12raN0Z1plqmFX9Qe3rjQTKt6sU=
-modernc.org/sqlite v1.46.1/go.mod h1:CzbrU2lSB1DKUusvwGz7rqEKIq+NUd8GWuBBZDs9/nA=
+modernc.org/sqlite v1.49.1 h1:dYGHTKcX1sJ+EQDnUzvz4TJ5GbuvhNJa8Fg6ElGx73U=
+modernc.org/sqlite v1.49.1/go.mod h1:m0w8xhwYUVY3H6pSDwc3gkJ/irZT/0YEXwBlhaxQEew=

model/criteria/criteria.go

@@ -1,17 +1,17 @@
-// Package criteria implements a Criteria API based on Masterminds/squirrel
+// Package criteria implements the smart playlist criteria DSL.
 package criteria
 
 import (
 	"encoding/json"
 	"errors"
-	"fmt"
-	"strings"
+	"slices"
 
-	"github.com/Masterminds/squirrel"
 	"github.com/navidrome/navidrome/log"
 )
 
-type Expression = squirrel.Sqlizer
+type Expression interface {
+	fields() map[string]any
+}
 
 type Criteria struct {
 	Expression
@@ -43,125 +43,35 @@ func (c Criteria) EffectiveLimit(totalCount int64) int {
 	return 0
 }
 
+// ResolveLimit converts a percentage-based limit into an absolute Limit using
+// the given totalCount. It is a no-op when a fixed Limit is already set or when
+// no percentage limit is configured.
+func (c *Criteria) ResolveLimit(totalCount int64) {
+	if !c.IsPercentageLimit() {
+		return
+	}
+	c.Limit = c.EffectiveLimit(totalCount)
+}
+
 // IsPercentageLimit returns true when the criteria uses a valid percentage-based
 // limit (i.e. LimitPercent is in [1, 100] and no fixed Limit overrides it).
 func (c Criteria) IsPercentageLimit() bool {
 	return c.Limit == 0 && c.LimitPercent > 0 && c.LimitPercent <= 100
 }
 
-func (c Criteria) OrderBy() string {
-	if c.Sort == "" {
-		c.Sort = "title"
-	}
-
-	order := strings.ToLower(strings.TrimSpace(c.Order))
-	if order != "" && order != "asc" && order != "desc" {
-		log.Error("Invalid value in 'order' field. Valid values: 'asc', 'desc'", "order", c.Order)
-		order = ""
-	}
-
-	parts := strings.Split(c.Sort, ",")
-	fields := make([]string, 0, len(parts))
-
-	for _, p := range parts {
-		p = strings.TrimSpace(p)
-		if p == "" {
-			continue
-		}
-
-		dir := "asc"
-		if strings.HasPrefix(p, "+") || strings.HasPrefix(p, "-") {
-			if strings.HasPrefix(p, "-") {
-				dir = "desc"
-			}
-			p = strings.TrimSpace(p[1:])
-		}
-
-		sortField := strings.ToLower(p)
-		f := fieldMap[sortField]
-		if f == nil {
-			log.Error("Invalid field in 'sort' field", "sort", sortField)
-			continue
-		}
-
-		var mapped string
-
-		if f.order != "" {
-			mapped = f.order
-		} else if f.isTag {
-			// Use the actual field name (handles aliases like albumtype -> releasetype)
-			tagName := sortField
-			if f.field != "" {
-				tagName = f.field
-			}
-			mapped = "COALESCE(json_extract(media_file.tags, '$." + tagName + "[0].value'), '')"
-		} else if f.isRole {
-			mapped = "COALESCE(json_extract(media_file.participants, '$." + sortField + "[0].name'), '')"
-		} else {
-			mapped = f.field
-		}
-		if f.numeric {
-			mapped = fmt.Sprintf("CAST(%s AS REAL)", mapped)
-		}
-		// If the global 'order' field is set to 'desc', reverse the default or field-specific sort direction.
-		// This ensures that the global order applies consistently across all fields.
-		if order == "desc" {
-			if dir == "asc" {
-				dir = "desc"
-			} else {
-				dir = "asc"
-			}
-		}
-
-		fields = append(fields, mapped+" "+dir)
-	}
-
-	return strings.Join(fields, ", ")
-}
-
-func (c Criteria) ToSql() (sql string, args []any, err error) {
-	return c.Expression.ToSql()
-}
-
-// ExpressionJoins returns only the JOINs needed by the WHERE-clause expression,
-// excluding any JOINs required solely for sorting. This is useful for COUNT
-// queries where sort order is irrelevant.
-func (c Criteria) ExpressionJoins() JoinType {
-	if c.Expression == nil {
-		return JoinNone
-	}
-	return extractJoinTypes(c.Expression)
-}
-
-// RequiredJoins inspects the expression tree and Sort field to determine which
-// additional JOINs are needed when evaluating this criteria.
-func (c Criteria) RequiredJoins() JoinType {
-	result := JoinNone
-	if c.Expression != nil {
-		result |= extractJoinTypes(c.Expression)
-	}
-	// Also check Sort fields
-	if c.Sort != "" {
-		for _, p := range strings.Split(c.Sort, ",") {
-			p = strings.TrimSpace(p)
-			p = strings.TrimLeft(p, "+-")
-			p = strings.TrimSpace(p)
-			result |= fieldJoinType(p)
-		}
-	}
-	return result
-}
-
 func (c Criteria) ChildPlaylistIds() []string {
 	if c.Expression == nil {
 		return nil
 	}
 
-	if parent := c.Expression.(interface{ ChildPlaylistIds() (ids []string) }); parent != nil {
-		return parent.ChildPlaylistIds()
+	parent, ok := c.Expression.(conjunction)
+	if !ok {
+		return nil
 	}
 
-	return nil
+	ids := parent.ChildPlaylistIds()
+	slices.Sort(ids)
+	return slices.Compact(ids)
 }
 
 func (c Criteria) MarshalJSON() ([]byte, error) {

model/criteria/criteria_test.go

@@ -65,16 +65,6 @@ var _ = Describe("Criteria", func() {
 			}
 			jsonObj = b.String()
 		})
-		It("generates valid SQL", func() {
-			sql, args, err := goObj.ToSql()
-			gomega.Expect(err).ToNot(gomega.HaveOccurred())
-			gomega.Expect(sql).To(gomega.Equal(
-				`(media_file.title LIKE ? AND media_file.title NOT LIKE ? ` +
-					`AND (not exists (select 1 from json_tree(media_file.participants, '$.artist') where key='name' and value = ?) ` +
-					`OR media_file.album = ?) AND (media_file.comment LIKE ? AND (media_file.year >= ? AND media_file.year <= ?) ` +
-					`AND not exists (select 1 from json_tree(media_file.tags, '$.genre') where key='value' and value = ?) AND COALESCE(album_annotation.rating, 0) > ?))`))
-			gomega.Expect(args).To(gomega.HaveExactElements("%love%", "%hate%", "u2", "best of", "this%", 1980, 1990, "Rock", 3))
-		})
 		It("marshals to JSON", func() {
 			j, err := json.Marshal(goObj)
 			gomega.Expect(err).ToNot(gomega.HaveOccurred())
@@ -88,201 +78,6 @@ var _ = Describe("Criteria", func() {
 			gomega.Expect(err).ToNot(gomega.HaveOccurred())
 			gomega.Expect(string(j)).To(gomega.Equal(jsonObj))
 		})
-		Describe("OrderBy", func() {
-			It("sorts by regular fields", func() {
-				gomega.Expect(goObj.OrderBy()).To(gomega.Equal("media_file.title asc"))
-			})
-
-			It("sorts by tag fields", func() {
-				goObj.Sort = "genre"
-				gomega.Expect(goObj.OrderBy()).To(
-					gomega.Equal(
-						"COALESCE(json_extract(media_file.tags, '$.genre[0].value'), '') asc",
-					),
-				)
-			})
-
-			It("sorts by role fields", func() {
-				goObj.Sort = "artist"
-				gomega.Expect(goObj.OrderBy()).To(
-					gomega.Equal(
-						"COALESCE(json_extract(media_file.participants, '$.artist[0].name'), '') asc",
-					),
-				)
-			})
-
-			It("casts numeric tags when sorting", func() {
-				AddTagNames([]string{"rate"})
-				AddNumericTags([]string{"rate"})
-				goObj.Sort = "rate"
-				gomega.Expect(goObj.OrderBy()).To(
-					gomega.Equal("CAST(COALESCE(json_extract(media_file.tags, '$.rate[0].value'), '') AS REAL) asc"),
-				)
-			})
-
-			It("sorts by albumtype alias (resolves to releasetype)", func() {
-				AddTagNames([]string{"releasetype"})
-				goObj.Sort = "albumtype"
-				gomega.Expect(goObj.OrderBy()).To(
-					gomega.Equal(
-						"COALESCE(json_extract(media_file.tags, '$.releasetype[0].value'), '') asc",
-					),
-				)
-			})
-
-			It("sorts by random", func() {
-				newObj := goObj
-				newObj.Sort = "random"
-				gomega.Expect(newObj.OrderBy()).To(gomega.Equal("random() asc"))
-			})
-
-			It("sorts by multiple fields", func() {
-				goObj.Sort = "title,-rating"
-				gomega.Expect(goObj.OrderBy()).To(gomega.Equal(
-					"media_file.title asc, COALESCE(annotation.rating, 0) desc",
-				))
-			})
-
-			It("reverts order when order is desc", func() {
-				goObj.Sort = "-date,artist"
-				goObj.Order = "desc"
-				gomega.Expect(goObj.OrderBy()).To(gomega.Equal(
-					"media_file.date asc, COALESCE(json_extract(media_file.participants, '$.artist[0].name'), '') desc",
-				))
-			})
-
-			It("ignores invalid sort fields", func() {
-				goObj.Sort = "bogus,title"
-				gomega.Expect(goObj.OrderBy()).To(gomega.Equal(
-					"media_file.title asc",
-				))
-			})
-		})
-	})
-
-	Context("with artist roles", func() {
-		BeforeEach(func() {
-			goObj = Criteria{
-				Expression: All{
-					Is{"artist": "The Beatles"},
-					Contains{"composer": "Lennon"},
-				},
-			}
-		})
-
-		It("generates valid SQL", func() {
-			sql, args, err := goObj.ToSql()
-			gomega.Expect(err).ToNot(gomega.HaveOccurred())
-			gomega.Expect(sql).To(gomega.Equal(
-				`(exists (select 1 from json_tree(media_file.participants, '$.artist') where key='name' and value = ?) AND ` +
-					`exists (select 1 from json_tree(media_file.participants, '$.composer') where key='name' and value LIKE ?))`,
-			))
-			gomega.Expect(args).To(gomega.HaveExactElements("The Beatles", "%Lennon%"))
-		})
-	})
-
-	Describe("ExpressionJoins", func() {
-		It("excludes sort-only joins", func() {
-			c := Criteria{
-				Expression: All{
-					Contains{"title": "love"},
-				},
-				Sort: "albumRating",
-			}
-			gomega.Expect(c.ExpressionJoins()).To(gomega.Equal(JoinNone))
-			gomega.Expect(c.RequiredJoins().Has(JoinAlbumAnnotation)).To(gomega.BeTrue())
-		})
-
-		It("includes expression-based joins", func() {
-			c := Criteria{
-				Expression: All{
-					Gt{"albumRating": 3},
-				},
-			}
-			gomega.Expect(c.ExpressionJoins().Has(JoinAlbumAnnotation)).To(gomega.BeTrue())
-		})
-	})
-
-	Describe("RequiredJoins", func() {
-		It("returns JoinNone when no annotation fields are used", func() {
-			c := Criteria{
-				Expression: All{
-					Contains{"title": "love"},
-				},
-			}
-			gomega.Expect(c.RequiredJoins()).To(gomega.Equal(JoinNone))
-		})
-		It("returns JoinNone for media_file annotation fields", func() {
-			c := Criteria{
-				Expression: All{
-					Is{"loved": true},
-					Gt{"playCount": 5},
-				},
-			}
-			gomega.Expect(c.RequiredJoins()).To(gomega.Equal(JoinNone))
-		})
-		It("returns JoinAlbumAnnotation for album annotation fields", func() {
-			c := Criteria{
-				Expression: All{
-					Gt{"albumRating": 3},
-				},
-			}
-			gomega.Expect(c.RequiredJoins()).To(gomega.Equal(JoinAlbumAnnotation))
-		})
-		It("returns JoinArtistAnnotation for artist annotation fields", func() {
-			c := Criteria{
-				Expression: All{
-					Is{"artistLoved": true},
-				},
-			}
-			gomega.Expect(c.RequiredJoins()).To(gomega.Equal(JoinArtistAnnotation))
-		})
-		It("returns both join types when both are used", func() {
-			c := Criteria{
-				Expression: All{
-					Gt{"albumRating": 3},
-					Is{"artistLoved": true},
-				},
-			}
-			j := c.RequiredJoins()
-			gomega.Expect(j.Has(JoinAlbumAnnotation)).To(gomega.BeTrue())
-			gomega.Expect(j.Has(JoinArtistAnnotation)).To(gomega.BeTrue())
-		})
-		It("detects join types in nested expressions", func() {
-			c := Criteria{
-				Expression: All{
-					Any{
-						All{
-							Is{"albumLoved": true},
-						},
-					},
-					Any{
-						Gt{"artistPlayCount": 10},
-					},
-				},
-			}
-			j := c.RequiredJoins()
-			gomega.Expect(j.Has(JoinAlbumAnnotation)).To(gomega.BeTrue())
-			gomega.Expect(j.Has(JoinArtistAnnotation)).To(gomega.BeTrue())
-		})
-		It("detects join types from Sort field", func() {
-			c := Criteria{
-				Expression: All{
-					Contains{"title": "love"},
-				},
-				Sort: "albumRating",
-			}
-			gomega.Expect(c.RequiredJoins().Has(JoinAlbumAnnotation)).To(gomega.BeTrue())
-		})
-		It("detects join types from Sort field with direction prefix", func() {
-			c := Criteria{
-				Expression: All{
-					Contains{"title": "love"},
-				},
-				Sort: "-artistRating",
-			}
-			gomega.Expect(c.RequiredJoins().Has(JoinArtistAnnotation)).To(gomega.BeTrue())
-		})
 	})
 
 	Describe("LimitPercent", func() {
@@ -382,6 +177,39 @@ var _ = Describe("Criteria", func() {
 			})
 		})
 
+		Describe("ResolveLimit", func() {
+			It("resolves percentage to absolute limit preserving LimitPercent", func() {
+				c := Criteria{LimitPercent: 10}
+				c.ResolveLimit(450)
+				gomega.Expect(c.Limit).To(gomega.Equal(45))
+			})
+
+			It("does nothing when Limit is already set", func() {
+				c := Criteria{Limit: 50, LimitPercent: 10}
+				c.ResolveLimit(1000)
+				gomega.Expect(c.Limit).To(gomega.Equal(50))
+			})
+
+			It("does nothing when no limit is configured", func() {
+				c := Criteria{}
+				c.ResolveLimit(1000)
+				gomega.Expect(c.Limit).To(gomega.Equal(0))
+			})
+
+			It("sets minimum 1 when percentage rounds to 0 and totalCount > 0", func() {
+				c := Criteria{LimitPercent: 1}
+				c.ResolveLimit(5)
+				gomega.Expect(c.Limit).To(gomega.Equal(1))
+			})
+
+			It("is idempotent when called twice", func() {
+				c := Criteria{LimitPercent: 10}
+				c.ResolveLimit(450)
+				c.ResolveLimit(450)
+				gomega.Expect(c.Limit).To(gomega.Equal(45))
+			})
+		})
+
 		Describe("IsPercentageLimit", func() {
 			It("returns true when LimitPercent is set and Limit is 0", func() {
 				c := Criteria{LimitPercent: 10}
@@ -470,5 +298,23 @@ var _ = Describe("Criteria", func() {
 			ids := Criteria{}.ChildPlaylistIds()
 			gomega.Expect(ids).To(gomega.BeEmpty())
 		})
+		It("returns empty list for leaf expressions", func() {
+			ids := Criteria{Expression: Is{"title": "Low Rider"}}.ChildPlaylistIds()
+			gomega.Expect(ids).To(gomega.BeEmpty())
+		})
+		It("deduplicates repeated playlist IDs", func() {
+			sharedID := uuid.NewString()
+			goObj = Criteria{
+				Expression: All{
+					InPlaylist{"id": sharedID},
+					Any{
+						InPlaylist{"id": sharedID},
+						NotInPlaylist{"id": sharedID},
+					},
+				},
+			}
+			ids := goObj.ChildPlaylistIds()
+			gomega.Expect(ids).To(gomega.Equal([]string{sharedID}))
+		})
 	})
 })

model/criteria/fields.go

@@ -1,280 +1,118 @@
 package criteria
 
-import (
-	"fmt"
-	"reflect"
-	"strings"
+import "strings"
 
-	"github.com/Masterminds/squirrel"
-	"github.com/navidrome/navidrome/log"
-)
-
-// JoinType is a bitmask indicating which additional JOINs are needed by a smart playlist expression.
-type JoinType int
-
-const (
-	JoinNone            JoinType = 0
-	JoinAlbumAnnotation JoinType = 1 << iota
-	JoinArtistAnnotation
-)
-
-// Has returns true if j contains all bits in other.
-func (j JoinType) Has(other JoinType) bool { return j&other != 0 }
-
-var fieldMap = map[string]*mappedField{
-	"title":           {field: "media_file.title"},
-	"album":           {field: "media_file.album"},
-	"hascoverart":     {field: "media_file.has_cover_art"},
-	"tracknumber":     {field: "media_file.track_number"},
-	"discnumber":      {field: "media_file.disc_number"},
-	"year":            {field: "media_file.year"},
-	"date":            {field: "media_file.date", alias: "recordingdate"},
-	"originalyear":    {field: "media_file.original_year"},
-	"originaldate":    {field: "media_file.original_date"},
-	"releaseyear":     {field: "media_file.release_year"},
-	"releasedate":     {field: "media_file.release_date"},
-	"size":            {field: "media_file.size"},
-	"compilation":     {field: "media_file.compilation"},
-	"missing":         {field: "media_file.missing"},
-	"explicitstatus":  {field: "media_file.explicit_status"},
-	"dateadded":       {field: "media_file.created_at"},
-	"datemodified":    {field: "media_file.updated_at"},
-	"discsubtitle":    {field: "media_file.disc_subtitle"},
-	"comment":         {field: "media_file.comment"},
-	"lyrics":          {field: "media_file.lyrics"},
-	"sorttitle":       {field: "media_file.sort_title"},
-	"sortalbum":       {field: "media_file.sort_album_name"},
-	"sortartist":      {field: "media_file.sort_artist_name"},
-	"sortalbumartist": {field: "media_file.sort_album_artist_name"},
-	"albumcomment":    {field: "media_file.mbz_album_comment"},
-	"catalognumber":   {field: "media_file.catalog_num"},
-	"filepath":        {field: "media_file.path"},
-	"filetype":        {field: "media_file.suffix"},
-	"codec":           {field: "media_file.codec"},
-	"duration":        {field: "media_file.duration"},
-	"bitrate":         {field: "media_file.bit_rate"},
-	"bitdepth":        {field: "media_file.bit_depth"},
-	"samplerate":      {field: "media_file.sample_rate"},
-	"bpm":             {field: "media_file.bpm"},
-	"channels":        {field: "media_file.channels"},
-	"loved":           {field: "COALESCE(annotation.starred, false)"},
-	"dateloved":       {field: "annotation.starred_at"},
-	"lastplayed":      {field: "annotation.play_date"},
-	"daterated":       {field: "annotation.rated_at"},
-	"playcount":       {field: "COALESCE(annotation.play_count, 0)"},
-	"rating":          {field: "COALESCE(annotation.rating, 0)"},
-	"averagerating":   {field: "media_file.average_rating", numeric: true},
-	"albumrating":     {field: "COALESCE(album_annotation.rating, 0)", joinType: JoinAlbumAnnotation},
-	"albumloved":      {field: "COALESCE(album_annotation.starred, false)", joinType: JoinAlbumAnnotation},
-	"albumplaycount":  {field: "COALESCE(album_annotation.play_count, 0)", joinType: JoinAlbumAnnotation},
-	"albumlastplayed": {field: "album_annotation.play_date", joinType: JoinAlbumAnnotation},
-	"albumdateloved":  {field: "album_annotation.starred_at", joinType: JoinAlbumAnnotation},
-	"albumdaterated":  {field: "album_annotation.rated_at", joinType: JoinAlbumAnnotation},
-
-	"artistrating":     {field: "COALESCE(artist_annotation.rating, 0)", joinType: JoinArtistAnnotation},
-	"artistloved":      {field: "COALESCE(artist_annotation.starred, false)", joinType: JoinArtistAnnotation},
-	"artistplaycount":  {field: "COALESCE(artist_annotation.play_count, 0)", joinType: JoinArtistAnnotation},
-	"artistlastplayed": {field: "artist_annotation.play_date", joinType: JoinArtistAnnotation},
-	"artistdateloved":  {field: "artist_annotation.starred_at", joinType: JoinArtistAnnotation},
-	"artistdaterated":  {field: "artist_annotation.rated_at", joinType: JoinArtistAnnotation},
-
-	"mbz_album_id":         {field: "media_file.mbz_album_id"},
-	"mbz_album_artist_id":  {field: "media_file.mbz_album_artist_id"},
-	"mbz_artist_id":        {field: "media_file.mbz_artist_id"},
-	"mbz_recording_id":     {field: "media_file.mbz_recording_id"},
-	"mbz_release_track_id": {field: "media_file.mbz_release_track_id"},
-	"mbz_release_group_id": {field: "media_file.mbz_release_group_id"},
-	"library_id":           {field: "media_file.library_id", numeric: true},
-
-	// Backward compatibility: albumtype is an alias for releasetype tag
-	"albumtype": {field: "releasetype", isTag: true},
-
-	// special fields
-	"random": {field: "", order: "random()"}, // pseudo-field for random sorting
-	"value":  {field: "value"},               // pseudo-field for tag and roles values
+// FieldInfo contains semantic metadata about a criteria field
+type FieldInfo struct {
+	Name    string
+	IsTag   bool
+	IsRole  bool
+	Numeric bool
+	alias   string
 }
 
-type mappedField struct {
-	field    string
-	order    string
-	isRole   bool     // true if the field is a role (e.g. "artist", "composer", "conductor", etc.)
-	isTag    bool     // true if the field is a tag imported from the file metadata
-	alias    string   // name from `mappings.yml` that may differ from the name used in the smart playlist
-	numeric  bool     // true if the field/tag should be treated as numeric
-	joinType JoinType // which additional JOINs this field requires
+var fieldMap = map[string]FieldInfo{
+	"title":                {Name: "title"},
+	"album":                {Name: "album"},
+	"hascoverart":          {Name: "hascoverart"},
+	"tracknumber":          {Name: "tracknumber"},
+	"discnumber":           {Name: "discnumber"},
+	"year":                 {Name: "year"},
+	"date":                 {Name: "date", alias: "recordingdate"},
+	"originalyear":         {Name: "originalyear"},
+	"originaldate":         {Name: "originaldate"},
+	"releaseyear":          {Name: "releaseyear"},
+	"releasedate":          {Name: "releasedate"},
+	"size":                 {Name: "size"},
+	"compilation":          {Name: "compilation"},
+	"missing":              {Name: "missing"},
+	"explicitstatus":       {Name: "explicitstatus"},
+	"dateadded":            {Name: "dateadded"},
+	"datemodified":         {Name: "datemodified"},
+	"discsubtitle":         {Name: "discsubtitle"},
+	"comment":              {Name: "comment"},
+	"lyrics":               {Name: "lyrics"},
+	"sorttitle":            {Name: "sorttitle"},
+	"sortalbum":            {Name: "sortalbum"},
+	"sortartist":           {Name: "sortartist"},
+	"sortalbumartist":      {Name: "sortalbumartist"},
+	"albumcomment":         {Name: "albumcomment"},
+	"catalognumber":        {Name: "catalognumber"},
+	"filepath":             {Name: "filepath"},
+	"filetype":             {Name: "filetype"},
+	"codec":                {Name: "codec"},
+	"duration":             {Name: "duration"},
+	"bitrate":              {Name: "bitrate"},
+	"bitdepth":             {Name: "bitdepth"},
+	"samplerate":           {Name: "samplerate"},
+	"bpm":                  {Name: "bpm"},
+	"channels":             {Name: "channels"},
+	"loved":                {Name: "loved"},
+	"dateloved":            {Name: "dateloved"},
+	"lastplayed":           {Name: "lastplayed"},
+	"daterated":            {Name: "daterated"},
+	"playcount":            {Name: "playcount"},
+	"rating":               {Name: "rating"},
+	"averagerating":        {Name: "averagerating", Numeric: true},
+	"albumrating":          {Name: "albumrating"},
+	"albumloved":           {Name: "albumloved"},
+	"albumplaycount":       {Name: "albumplaycount"},
+	"albumlastplayed":      {Name: "albumlastplayed"},
+	"albumdateloved":       {Name: "albumdateloved"},
+	"albumdaterated":       {Name: "albumdaterated"},
+	"artistrating":         {Name: "artistrating"},
+	"artistloved":          {Name: "artistloved"},
+	"artistplaycount":      {Name: "artistplaycount"},
+	"artistlastplayed":     {Name: "artistlastplayed"},
+	"artistdateloved":      {Name: "artistdateloved"},
+	"artistdaterated":      {Name: "artistdaterated"},
+	"mbz_album_id":         {Name: "mbz_album_id"},
+	"mbz_album_artist_id":  {Name: "mbz_album_artist_id"},
+	"mbz_artist_id":        {Name: "mbz_artist_id"},
+	"mbz_recording_id":     {Name: "mbz_recording_id"},
+	"mbz_release_track_id": {Name: "mbz_release_track_id"},
+	"mbz_release_group_id": {Name: "mbz_release_group_id"},
+	"library_id":           {Name: "library_id", Numeric: true},
+
+	// Backward compatibility: albumtype is an alias for the releasetype tag.
+	"albumtype": {Name: "releasetype", IsTag: true},
+
+	"random": {Name: "random"},
+	"value":  {Name: "value"},
 }
 
-func mapFields(expr map[string]any) map[string]any {
-	m := make(map[string]any)
-	for f, v := range expr {
-		if dbf := fieldMap[strings.ToLower(f)]; dbf != nil && dbf.field != "" {
-			m[dbf.field] = v
-		} else {
-			log.Error("Invalid field in criteria", "field", f)
-		}
+// AllFieldNames returns the names of all registered criteria fields.
+func AllFieldNames() []string {
+	names := make([]string, 0, len(fieldMap))
+	for name := range fieldMap {
+		names = append(names, name)
 	}
-	return m
+	return names
 }
 
-// mapExpr maps a normal field expression to a specific type of expression (tag or role).
-// This is required because tags are handled differently than other fields,
-// as they are stored as a JSON column in the database.
-func mapExpr(expr squirrel.Sqlizer, negate bool, exprFunc func(string, squirrel.Sqlizer, bool) squirrel.Sqlizer) squirrel.Sqlizer {
-	rv := reflect.ValueOf(expr)
-	if rv.Kind() != reflect.Map || rv.Type().Key().Kind() != reflect.String {
-		log.Fatal(fmt.Sprintf("expr is not a map-based operator: %T", expr))
-	}
-
-	// Extract the field name and value, then build a new map keyed by "value"
-	// for the inner condition. The original map is left untouched so that
-	// ToSql can be called multiple times without corruption.
-	var k string
-	var v any
-	for _, key := range rv.MapKeys() {
-		k = key.String()
-		v = rv.MapIndex(key).Interface()
-		break // only one key is expected (and supported)
-	}
-
-	// Create a new map-based expression with "value" as the key, matching the
-	// column name inside json_tree subqueries.
-	newMap := reflect.MakeMap(rv.Type())
-	newMap.SetMapIndex(reflect.ValueOf("value"), reflect.ValueOf(v))
-	newExpr := newMap.Interface().(squirrel.Sqlizer)
-
-	return exprFunc(k, newExpr, negate)
-}
-
-// mapTagExpr maps a normal field expression to a tag expression.
-func mapTagExpr(expr squirrel.Sqlizer, negate bool) squirrel.Sqlizer {
-	return mapExpr(expr, negate, tagExpr)
-}
-
-// mapRoleExpr maps a normal field expression to an artist role expression.
-func mapRoleExpr(expr squirrel.Sqlizer, negate bool) squirrel.Sqlizer {
-	return mapExpr(expr, negate, roleExpr)
-}
-
-func isTagExpr(expr map[string]any) bool {
-	for f := range expr {
-		if f2, ok := fieldMap[strings.ToLower(f)]; ok && f2.isTag {
-			return true
-		}
-	}
-	return false
-}
-
-func isRoleExpr(expr map[string]any) bool {
-	for f := range expr {
-		if f2, ok := fieldMap[strings.ToLower(f)]; ok && f2.isRole {
-			return true
-		}
-	}
-	return false
-}
-
-func tagExpr(tag string, cond squirrel.Sqlizer, negate bool) squirrel.Sqlizer {
-	return tagCond{tag: tag, cond: cond, not: negate}
-}
-
-type tagCond struct {
-	tag  string
-	cond squirrel.Sqlizer
-	not  bool
-}
-
-func (e tagCond) ToSql() (string, []any, error) {
-	cond, args, err := e.cond.ToSql()
-
-	// Resolve the actual tag name (handles aliases like albumtype -> releasetype)
-	tagName := e.tag
-	if fm, ok := fieldMap[e.tag]; ok {
-		if fm.field != "" {
-			tagName = fm.field
-		}
-		if fm.numeric {
-			cond = strings.ReplaceAll(cond, "value", "CAST(value AS REAL)")
-		}
-	}
-
-	cond = fmt.Sprintf("exists (select 1 from json_tree(media_file.tags, '$.%s') where key='value' and %s)",
-		tagName, cond)
-	if e.not {
-		cond = "not " + cond
-	}
-	return cond, args, err
-}
-
-func roleExpr(role string, cond squirrel.Sqlizer, negate bool) squirrel.Sqlizer {
-	return roleCond{role: role, cond: cond, not: negate}
-}
-
-type roleCond struct {
-	role string
-	cond squirrel.Sqlizer
-	not  bool
-}
-
-func (e roleCond) ToSql() (string, []any, error) {
-	cond, args, err := e.cond.ToSql()
-	cond = fmt.Sprintf(`exists (select 1 from json_tree(media_file.participants, '$.%s') where key='name' and %s)`,
-		e.role, cond)
-	if e.not {
-		cond = "not " + cond
-	}
-	return cond, args, err
-}
-
-// fieldJoinType returns the JoinType for a given field name (case-insensitive).
-func fieldJoinType(name string) JoinType {
-	if f, ok := fieldMap[strings.ToLower(name)]; ok {
-		return f.joinType
-	}
-	return JoinNone
-}
-
-// extractJoinTypes walks an expression tree and collects all required JoinType flags.
-func extractJoinTypes(expr any) JoinType {
-	result := JoinNone
-	switch e := expr.(type) {
-	case All:
-		for _, sub := range e {
-			result |= extractJoinTypes(sub)
-		}
-	case Any:
-		for _, sub := range e {
-			result |= extractJoinTypes(sub)
-		}
-	default:
-		// Leaf expression: use reflection to check if it's a map with field names
-		rv := reflect.ValueOf(expr)
-		if rv.Kind() == reflect.Map && rv.Type().Key().Kind() == reflect.String {
-			for _, key := range rv.MapKeys() {
-				result |= fieldJoinType(key.String())
-			}
-		}
-	}
-	return result
+// LookupField returns semantic metadata for a criteria field name.
+func LookupField(name string) (FieldInfo, bool) {
+	f, ok := fieldMap[strings.ToLower(name)]
+	return f, ok
 }
 
 // AddRoles adds roles to the field map. This is used to add all artist roles to the field map, so they can be used in
-// smart playlists. If a role already exists in the field map, it is ignored, so calls to this function are idempotent.
+// smart playlists.
 func AddRoles(roles []string) {
 	for _, role := range roles {
 		name := strings.ToLower(role)
 		if _, ok := fieldMap[name]; ok {
 			continue
 		}
-		fieldMap[name] = &mappedField{field: name, isRole: true}
+		fieldMap[name] = FieldInfo{Name: name, IsRole: true}
 	}
 }
 
 // AddTagNames adds tag names to the field map. This is used to add all tags mapped in the `mappings.yml`
-// file to the field map, so they can be used in smart playlists.
-// If a tag name already exists in the field map, it is ignored, so calls to this function are idempotent.
+// configuration file.
 func AddTagNames(tagNames []string) {
-	for _, name := range tagNames {
-		name := strings.ToLower(name)
+	for _, tagName := range tagNames {
+		name := strings.ToLower(tagName)
 		if _, ok := fieldMap[name]; ok {
 			continue
 		}
@@ -285,20 +123,20 @@ func AddTagNames(tagNames []string) {
 			}
 		}
 		if _, ok := fieldMap[name]; !ok {
-			fieldMap[name] = &mappedField{field: name, isTag: true}
+			fieldMap[name] = FieldInfo{Name: name, IsTag: true}
 		}
 	}
 }
 
-// AddNumericTags marks the given tag names as numeric so they can be cast
-// when used in comparisons or sorting.
+// AddNumericTags adds tags that should be treated as numbers.
 func AddNumericTags(tagNames []string) {
-	for _, name := range tagNames {
-		name := strings.ToLower(name)
+	for _, tagName := range tagNames {
+		name := strings.ToLower(tagName)
 		if fm, ok := fieldMap[name]; ok {
-			fm.numeric = true
+			fm.Numeric = true
+			fieldMap[name] = fm
 		} else {
-			fieldMap[name] = &mappedField{field: name, isTag: true, numeric: true}
+			fieldMap[name] = FieldInfo{Name: name, IsTag: true, Numeric: true}
 		}
 	}
 }

model/criteria/fields_test.go

@@ -6,11 +6,58 @@ import (
 )
 
 var _ = Describe("fields", func() {
-	Describe("mapFields", func() {
-		It("ignores random fields", func() {
-			m := map[string]any{"random": "123"}
-			m = mapFields(m)
-			gomega.Expect(m).To(gomega.BeEmpty())
+	Describe("LookupField", func() {
+		It("finds built-in fields case-insensitively", func() {
+			field, ok := LookupField("Title")
+
+			gomega.Expect(ok).To(gomega.BeTrue())
+			gomega.Expect(field).To(gomega.Equal(FieldInfo{Name: "title"}))
+		})
+
+		It("resolves aliases to their semantic field name", func() {
+			field, ok := LookupField("albumtype")
+
+			gomega.Expect(ok).To(gomega.BeTrue())
+			gomega.Expect(field.Name).To(gomega.Equal("releasetype"))
+			gomega.Expect(field.IsTag).To(gomega.BeTrue())
+		})
+
+		It("finds special fields", func() {
+			field, ok := LookupField("value")
+
+			gomega.Expect(ok).To(gomega.BeTrue())
+			gomega.Expect(field.Name).To(gomega.Equal("value"))
+		})
+
+		It("finds registered tag names", func() {
+			AddTagNames([]string{"task3_mood"})
+
+			field, ok := LookupField("task3_mood")
+
+			gomega.Expect(ok).To(gomega.BeTrue())
+			gomega.Expect(field.Name).To(gomega.Equal("task3_mood"))
+			gomega.Expect(field.IsTag).To(gomega.BeTrue())
+		})
+
+		It("marks registered numeric tags", func() {
+			AddTagNames([]string{"task3_score"})
+			AddNumericTags([]string{"task3_score"})
+
+			field, ok := LookupField("task3_score")
+
+			gomega.Expect(ok).To(gomega.BeTrue())
+			gomega.Expect(field.IsTag).To(gomega.BeTrue())
+			gomega.Expect(field.Numeric).To(gomega.BeTrue())
+		})
+
+		It("finds registered roles", func() {
+			AddRoles([]string{"task3_producer"})
+
+			field, ok := LookupField("task3_producer")
+
+			gomega.Expect(ok).To(gomega.BeTrue())
+			gomega.Expect(field.Name).To(gomega.Equal("task3_producer"))
+			gomega.Expect(field.IsRole).To(gomega.BeTrue())
 		})
 	})
 })

model/criteria/operators.go

@@ -1,23 +1,18 @@
 package criteria
 
-import (
-	"errors"
-	"fmt"
-	"reflect"
-	"strconv"
-	"time"
+import "time"
 
-	"github.com/Masterminds/squirrel"
-)
+// Conjunctions need to implement this interface, to allow Criteria to extract child playlist IDs recursively
+type conjunction interface {
+	ChildPlaylistIds() []string
+}
 
 type (
-	All squirrel.And
+	All []Expression
 	And = All
 )
 
-func (all All) ToSql() (sql string, args []any, err error) {
-	return squirrel.And(all).ToSql()
-}
+func (All) fields() map[string]any { return nil }
 
 func (all All) MarshalJSON() ([]byte, error) {
 	return marshalConjunction("all", all)
@@ -28,13 +23,11 @@ func (all All) ChildPlaylistIds() (ids []string) {
 }
 
 type (
-	Any squirrel.Or
+	Any []Expression
 	Or  = Any
 )
 
-func (any Any) ToSql() (sql string, args []any, err error) {
-	return squirrel.Or(any).ToSql()
-}
+func (Any) fields() map[string]any { return nil }
 
 func (any Any) MarshalJSON() ([]byte, error) {
 	return marshalConjunction("any", any)
@@ -44,236 +37,110 @@ func (any Any) ChildPlaylistIds() (ids []string) {
 	return extractPlaylistIds(any)
 }
 
-type Is squirrel.Eq
+type Is map[string]any
 type Eq = Is
 
-func (is Is) ToSql() (sql string, args []any, err error) {
-	if isRoleExpr(is) {
-		return mapRoleExpr(is, false).ToSql()
-	}
-	if isTagExpr(is) {
-		return mapTagExpr(is, false).ToSql()
-	}
-	return squirrel.Eq(mapFields(is)).ToSql()
-}
-
 func (is Is) MarshalJSON() ([]byte, error) {
 	return marshalExpression("is", is)
 }
 
-type IsNot squirrel.NotEq
+func (is Is) fields() map[string]any { return is }
 
-func (in IsNot) ToSql() (sql string, args []any, err error) {
-	if isRoleExpr(in) {
-		return mapRoleExpr(squirrel.Eq(in), true).ToSql()
-	}
-	if isTagExpr(in) {
-		return mapTagExpr(squirrel.Eq(in), true).ToSql()
-	}
-	return squirrel.NotEq(mapFields(in)).ToSql()
+type IsNot map[string]any
+
+func (isn IsNot) MarshalJSON() ([]byte, error) {
+	return marshalExpression("isNot", isn)
 }
 
-func (in IsNot) MarshalJSON() ([]byte, error) {
-	return marshalExpression("isNot", in)
-}
+func (isn IsNot) fields() map[string]any { return isn }
 
-type Gt squirrel.Gt
-
-func (gt Gt) ToSql() (sql string, args []any, err error) {
-	if isTagExpr(gt) {
-		return mapTagExpr(gt, false).ToSql()
-	}
-	return squirrel.Gt(mapFields(gt)).ToSql()
-}
+type Gt map[string]any
 
 func (gt Gt) MarshalJSON() ([]byte, error) {
 	return marshalExpression("gt", gt)
 }
 
-type Lt squirrel.Lt
+func (gt Gt) fields() map[string]any { return gt }
 
-func (lt Lt) ToSql() (sql string, args []any, err error) {
-	if isTagExpr(lt) {
-		return mapTagExpr(squirrel.Lt(lt), false).ToSql()
-	}
-	return squirrel.Lt(mapFields(lt)).ToSql()
-}
+type Lt map[string]any
 
 func (lt Lt) MarshalJSON() ([]byte, error) {
 	return marshalExpression("lt", lt)
 }
 
-type Before squirrel.Lt
+func (lt Lt) fields() map[string]any { return lt }
 
-func (bf Before) ToSql() (sql string, args []any, err error) {
-	return Lt(bf).ToSql()
-}
+type Before map[string]any
 
 func (bf Before) MarshalJSON() ([]byte, error) {
 	return marshalExpression("before", bf)
 }
 
-type After Gt
+func (bf Before) fields() map[string]any { return bf }
 
-func (af After) ToSql() (sql string, args []any, err error) {
-	return Gt(af).ToSql()
-}
+type After Gt
 
 func (af After) MarshalJSON() ([]byte, error) {
 	return marshalExpression("after", af)
 }
 
-type Contains map[string]any
+func (af After) fields() map[string]any { return af }
 
-func (ct Contains) ToSql() (sql string, args []any, err error) {
-	lk := squirrel.Like{}
-	for f, v := range mapFields(ct) {
-		lk[f] = fmt.Sprintf("%%%s%%", v)
-	}
-	if isRoleExpr(ct) {
-		return mapRoleExpr(lk, false).ToSql()
-	}
-	if isTagExpr(ct) {
-		return mapTagExpr(lk, false).ToSql()
-	}
-	return lk.ToSql()
-}
+type Contains map[string]any
 
 func (ct Contains) MarshalJSON() ([]byte, error) {
 	return marshalExpression("contains", ct)
 }
 
-type NotContains map[string]any
+func (ct Contains) fields() map[string]any { return ct }
 
-func (nct NotContains) ToSql() (sql string, args []any, err error) {
-	lk := squirrel.NotLike{}
-	for f, v := range mapFields(nct) {
-		lk[f] = fmt.Sprintf("%%%s%%", v)
-	}
-	if isRoleExpr(nct) {
-		return mapRoleExpr(squirrel.Like(lk), true).ToSql()
-	}
-	if isTagExpr(nct) {
-		return mapTagExpr(squirrel.Like(lk), true).ToSql()
-	}
-	return lk.ToSql()
-}
+type NotContains map[string]any
 
 func (nct NotContains) MarshalJSON() ([]byte, error) {
 	return marshalExpression("notContains", nct)
 }
 
-type StartsWith map[string]any
+func (nct NotContains) fields() map[string]any { return nct }
 
-func (sw StartsWith) ToSql() (sql string, args []any, err error) {
-	lk := squirrel.Like{}
-	for f, v := range mapFields(sw) {
-		lk[f] = fmt.Sprintf("%s%%", v)
-	}
-	if isRoleExpr(sw) {
-		return mapRoleExpr(lk, false).ToSql()
-	}
-	if isTagExpr(sw) {
-		return mapTagExpr(lk, false).ToSql()
-	}
-	return lk.ToSql()
-}
+type StartsWith map[string]any
 
 func (sw StartsWith) MarshalJSON() ([]byte, error) {
 	return marshalExpression("startsWith", sw)
 }
 
+func (sw StartsWith) fields() map[string]any { return sw }
+
 type EndsWith map[string]any
 
-func (sw EndsWith) ToSql() (sql string, args []any, err error) {
-	lk := squirrel.Like{}
-	for f, v := range mapFields(sw) {
-		lk[f] = fmt.Sprintf("%%%s", v)
-	}
-	if isRoleExpr(sw) {
-		return mapRoleExpr(lk, false).ToSql()
-	}
-	if isTagExpr(sw) {
-		return mapTagExpr(lk, false).ToSql()
-	}
-	return lk.ToSql()
+func (ew EndsWith) MarshalJSON() ([]byte, error) {
+	return marshalExpression("endsWith", ew)
 }
 
-func (sw EndsWith) MarshalJSON() ([]byte, error) {
-	return marshalExpression("endsWith", sw)
-}
+func (ew EndsWith) fields() map[string]any { return ew }
 
 type InTheRange map[string]any
 
-func (itr InTheRange) ToSql() (sql string, args []any, err error) {
-	and := squirrel.And{}
-	for f, v := range mapFields(itr) {
-		s := reflect.ValueOf(v)
-		if s.Kind() != reflect.Slice || s.Len() != 2 {
-			return "", nil, fmt.Errorf("invalid range for 'in' operator: %s", v)
-		}
-		and = append(and,
-			squirrel.GtOrEq{f: s.Index(0).Interface()},
-			squirrel.LtOrEq{f: s.Index(1).Interface()},
-		)
-	}
-	return and.ToSql()
-}
-
 func (itr InTheRange) MarshalJSON() ([]byte, error) {
 	return marshalExpression("inTheRange", itr)
 }
 
-type InTheLast map[string]any
+func (itr InTheRange) fields() map[string]any { return itr }
 
-func (itl InTheLast) ToSql() (sql string, args []any, err error) {
-	exp, err := inPeriod(itl, false)
-	if err != nil {
-		return "", nil, err
-	}
-	return exp.ToSql()
-}
+type InTheLast map[string]any
 
 func (itl InTheLast) MarshalJSON() ([]byte, error) {
 	return marshalExpression("inTheLast", itl)
 }
 
-type NotInTheLast map[string]any
+func (itl InTheLast) fields() map[string]any { return itl }
 
-func (nitl NotInTheLast) ToSql() (sql string, args []any, err error) {
-	exp, err := inPeriod(nitl, true)
-	if err != nil {
-		return "", nil, err
-	}
-	return exp.ToSql()
-}
+type NotInTheLast map[string]any
 
 func (nitl NotInTheLast) MarshalJSON() ([]byte, error) {
 	return marshalExpression("notInTheLast", nitl)
 }
 
-func inPeriod(m map[string]any, negate bool) (Expression, error) {
-	var field string
-	var value any
-	for f, v := range mapFields(m) {
-		field, value = f, v
-		break
-	}
-	str := fmt.Sprintf("%v", value)
-	v, err := strconv.ParseInt(str, 10, 64)
-	if err != nil {
-		return nil, err
-	}
-	firstDate := startOfPeriod(v, time.Now())
-
-	if negate {
-		return Or{
-			squirrel.Lt{field: firstDate},
-			squirrel.Eq{field: nil},
-		}, nil
-	}
-	return squirrel.Gt{field: firstDate}, nil
-}
+func (nitl NotInTheLast) fields() map[string]any { return nitl }
 
 func startOfPeriod(numDays int64, from time.Time) string {
 	return from.Add(time.Duration(-24*numDays) * time.Hour).Format("2006-01-02")
@@ -281,50 +148,19 @@ func startOfPeriod(numDays int64, from time.Time) string {
 
 type InPlaylist map[string]any
 
-func (ipl InPlaylist) ToSql() (sql string, args []any, err error) {
-	return inList(ipl, false)
-}
-
 func (ipl InPlaylist) MarshalJSON() ([]byte, error) {
 	return marshalExpression("inPlaylist", ipl)
 }
 
+func (ipl InPlaylist) fields() map[string]any { return ipl }
+
 type NotInPlaylist map[string]any
 
-func (ipl NotInPlaylist) ToSql() (sql string, args []any, err error) {
-	return inList(ipl, true)
+func (nipl NotInPlaylist) MarshalJSON() ([]byte, error) {
+	return marshalExpression("notInPlaylist", nipl)
 }
 
-func (ipl NotInPlaylist) MarshalJSON() ([]byte, error) {
-	return marshalExpression("notInPlaylist", ipl)
-}
-
-func inList(m map[string]any, negate bool) (sql string, args []any, err error) {
-	var playlistid string
-	var ok bool
-	if playlistid, ok = m["id"].(string); !ok {
-		return "", nil, errors.New("playlist id not given")
-	}
-
-	// Subquery to fetch all media files that are contained in given playlist
-	// Only evaluate playlist if it is public
-	subQuery := squirrel.Select("media_file_id").
-		From("playlist_tracks pl").
-		LeftJoin("playlist on pl.playlist_id = playlist.id").
-		Where(squirrel.And{
-			squirrel.Eq{"pl.playlist_id": playlistid},
-			squirrel.Eq{"playlist.public": 1}})
-	subQText, subQArgs, err := subQuery.PlaceholderFormat(squirrel.Question).ToSql()
-
-	if err != nil {
-		return "", nil, err
-	}
-	if negate {
-		return "media_file.id NOT IN (" + subQText + ")", subQArgs, nil
-	} else {
-		return "media_file.id IN (" + subQText + ")", subQArgs, nil
-	}
-}
+func (nipl NotInPlaylist) fields() map[string]any { return nipl }
 
 func extractPlaylistIds(inputRule any) (ids []string) {
 	var id string

model/criteria/operators_test.go

@@ -3,7 +3,6 @@ package criteria_test
 import (
 	"encoding/json"
 	"fmt"
-	"time"
 
 	. "github.com/navidrome/navidrome/model/criteria"
 	. "github.com/onsi/ginkgo/v2"
@@ -17,182 +16,6 @@ var _ = BeforeSuite(func() {
 })
 
 var _ = Describe("Operators", func() {
-	rangeStart := time.Date(2021, 10, 01, 0, 0, 0, 0, time.Local)
-	rangeEnd := time.Date(2021, 11, 01, 0, 0, 0, 0, time.Local)
-
-	DescribeTable("ToSQL",
-		func(op Expression, expectedSql string, expectedArgs ...any) {
-			sql, args, err := op.ToSql()
-			gomega.Expect(err).ToNot(gomega.HaveOccurred())
-			gomega.Expect(sql).To(gomega.Equal(expectedSql))
-			gomega.Expect(args).To(gomega.HaveExactElements(expectedArgs...))
-		},
-		Entry("is [string]", Is{"title": "Low Rider"}, "media_file.title = ?", "Low Rider"),
-		Entry("is [bool]", Is{"loved": true}, "COALESCE(annotation.starred, false) = ?", true),
-		Entry("is [numeric]", Is{"library_id": 1}, "media_file.library_id = ?", 1),
-		Entry("is [numeric list]", Is{"library_id": []int{1, 2}}, "media_file.library_id IN (?,?)", 1, 2),
-		Entry("isNot", IsNot{"title": "Low Rider"}, "media_file.title <> ?", "Low Rider"),
-		Entry("isNot [numeric]", IsNot{"library_id": 1}, "media_file.library_id <> ?", 1),
-		Entry("isNot [numeric list]", IsNot{"library_id": []int{1, 2}}, "media_file.library_id NOT IN (?,?)", 1, 2),
-		Entry("gt", Gt{"playCount": 10}, "COALESCE(annotation.play_count, 0) > ?", 10),
-		Entry("lt", Lt{"playCount": 10}, "COALESCE(annotation.play_count, 0) < ?", 10),
-		Entry("contains", Contains{"title": "Low Rider"}, "media_file.title LIKE ?", "%Low Rider%"),
-		Entry("notContains", NotContains{"title": "Low Rider"}, "media_file.title NOT LIKE ?", "%Low Rider%"),
-		Entry("startsWith", StartsWith{"title": "Low Rider"}, "media_file.title LIKE ?", "Low Rider%"),
-		Entry("endsWith", EndsWith{"title": "Low Rider"}, "media_file.title LIKE ?", "%Low Rider"),
-		Entry("inTheRange [number]", InTheRange{"year": []int{1980, 1990}}, "(media_file.year >= ? AND media_file.year <= ?)", 1980, 1990),
-		Entry("inTheRange [date]", InTheRange{"lastPlayed": []time.Time{rangeStart, rangeEnd}}, "(annotation.play_date >= ? AND annotation.play_date <= ?)", rangeStart, rangeEnd),
-		Entry("before", Before{"lastPlayed": rangeStart}, "annotation.play_date < ?", rangeStart),
-		Entry("after", After{"lastPlayed": rangeStart}, "annotation.play_date > ?", rangeStart),
-
-		// InPlaylist and NotInPlaylist are special cases
-		Entry("inPlaylist", InPlaylist{"id": "deadbeef-dead-beef"}, "media_file.id IN "+
-			"(SELECT media_file_id FROM playlist_tracks pl LEFT JOIN playlist on pl.playlist_id = playlist.id WHERE (pl.playlist_id = ? AND playlist.public = ?))", "deadbeef-dead-beef", 1),
-		Entry("notInPlaylist", NotInPlaylist{"id": "deadbeef-dead-beef"}, "media_file.id NOT IN "+
-			"(SELECT media_file_id FROM playlist_tracks pl LEFT JOIN playlist on pl.playlist_id = playlist.id WHERE (pl.playlist_id = ? AND playlist.public = ?))", "deadbeef-dead-beef", 1),
-
-		Entry("inTheLast", InTheLast{"lastPlayed": 30}, "annotation.play_date > ?", StartOfPeriod(30, time.Now())),
-		Entry("notInTheLast", NotInTheLast{"lastPlayed": 30}, "(annotation.play_date < ? OR annotation.play_date IS NULL)", StartOfPeriod(30, time.Now())),
-
-		// Album annotation fields
-		Entry("albumRating", Gt{"albumRating": 3}, "COALESCE(album_annotation.rating, 0) > ?", 3),
-		Entry("albumLoved", Is{"albumLoved": true}, "COALESCE(album_annotation.starred, false) = ?", true),
-		Entry("albumPlayCount", Gt{"albumPlayCount": 5}, "COALESCE(album_annotation.play_count, 0) > ?", 5),
-		Entry("albumLastPlayed", After{"albumLastPlayed": rangeStart}, "album_annotation.play_date > ?", rangeStart),
-		Entry("albumDateLoved", Before{"albumDateLoved": rangeStart}, "album_annotation.starred_at < ?", rangeStart),
-		Entry("albumDateRated", After{"albumDateRated": rangeStart}, "album_annotation.rated_at > ?", rangeStart),
-		Entry("albumLastPlayed inTheLast", InTheLast{"albumLastPlayed": 30}, "album_annotation.play_date > ?", StartOfPeriod(30, time.Now())),
-		Entry("albumLastPlayed notInTheLast", NotInTheLast{"albumLastPlayed": 30}, "(album_annotation.play_date < ? OR album_annotation.play_date IS NULL)", StartOfPeriod(30, time.Now())),
-
-		// Artist annotation fields
-		Entry("artistRating", Gt{"artistRating": 3}, "COALESCE(artist_annotation.rating, 0) > ?", 3),
-		Entry("artistLoved", Is{"artistLoved": true}, "COALESCE(artist_annotation.starred, false) = ?", true),
-		Entry("artistPlayCount", Gt{"artistPlayCount": 5}, "COALESCE(artist_annotation.play_count, 0) > ?", 5),
-		Entry("artistLastPlayed", After{"artistLastPlayed": rangeStart}, "artist_annotation.play_date > ?", rangeStart),
-		Entry("artistDateLoved", Before{"artistDateLoved": rangeStart}, "artist_annotation.starred_at < ?", rangeStart),
-		Entry("artistDateRated", After{"artistDateRated": rangeStart}, "artist_annotation.rated_at > ?", rangeStart),
-		Entry("artistLastPlayed inTheLast", InTheLast{"artistLastPlayed": 30}, "artist_annotation.play_date > ?", StartOfPeriod(30, time.Now())),
-		Entry("artistLastPlayed notInTheLast", NotInTheLast{"artistLastPlayed": 30}, "(artist_annotation.play_date < ? OR artist_annotation.play_date IS NULL)", StartOfPeriod(30, time.Now())),
-
-		// Tag tests
-		Entry("tag is [string]", Is{"genre": "Rock"}, "exists (select 1 from json_tree(media_file.tags, '$.genre') where key='value' and value = ?)", "Rock"),
-		Entry("tag isNot [string]", IsNot{"genre": "Rock"}, "not exists (select 1 from json_tree(media_file.tags, '$.genre') where key='value' and value = ?)", "Rock"),
-		Entry("tag gt", Gt{"genre": "A"}, "exists (select 1 from json_tree(media_file.tags, '$.genre') where key='value' and value > ?)", "A"),
-		Entry("tag lt", Lt{"genre": "Z"}, "exists (select 1 from json_tree(media_file.tags, '$.genre') where key='value' and value < ?)", "Z"),
-		Entry("tag contains", Contains{"genre": "Rock"}, "exists (select 1 from json_tree(media_file.tags, '$.genre') where key='value' and value LIKE ?)", "%Rock%"),
-		Entry("tag not contains", NotContains{"genre": "Rock"}, "not exists (select 1 from json_tree(media_file.tags, '$.genre') where key='value' and value LIKE ?)", "%Rock%"),
-		Entry("tag startsWith", StartsWith{"genre": "Soft"}, "exists (select 1 from json_tree(media_file.tags, '$.genre') where key='value' and value LIKE ?)", "Soft%"),
-		Entry("tag endsWith", EndsWith{"genre": "Rock"}, "exists (select 1 from json_tree(media_file.tags, '$.genre') where key='value' and value LIKE ?)", "%Rock"),
-
-		// Artist roles tests
-		Entry("role is [string]", Is{"artist": "u2"}, "exists (select 1 from json_tree(media_file.participants, '$.artist') where key='name' and value = ?)", "u2"),
-		Entry("role isNot [string]", IsNot{"artist": "u2"}, "not exists (select 1 from json_tree(media_file.participants, '$.artist') where key='name' and value = ?)", "u2"),
-		Entry("role contains [string]", Contains{"artist": "u2"}, "exists (select 1 from json_tree(media_file.participants, '$.artist') where key='name' and value LIKE ?)", "%u2%"),
-		Entry("role not contains [string]", NotContains{"artist": "u2"}, "not exists (select 1 from json_tree(media_file.participants, '$.artist') where key='name' and value LIKE ?)", "%u2%"),
-		Entry("role startsWith [string]", StartsWith{"composer": "John"}, "exists (select 1 from json_tree(media_file.participants, '$.composer') where key='name' and value LIKE ?)", "John%"),
-		Entry("role endsWith [string]", EndsWith{"composer": "Lennon"}, "exists (select 1 from json_tree(media_file.participants, '$.composer') where key='name' and value LIKE ?)", "%Lennon"),
-	)
-
-	// TODO Validate operators that are not valid for each field type.
-	XDescribeTable("ToSQL - Invalid Operators",
-		func(op Expression, expectedError string) {
-			_, _, err := op.ToSql()
-			gomega.Expect(err).To(gomega.MatchError(expectedError))
-		},
-		Entry("numeric tag contains", Contains{"rate": 5}, "numeric tag 'rate' cannot be used with Contains operator"),
-	)
-
-	Describe("Custom Tags", func() {
-		It("generates valid SQL", func() {
-			AddTagNames([]string{"mood"})
-			op := EndsWith{"mood": "Soft"}
-			sql, args, err := op.ToSql()
-			gomega.Expect(err).ToNot(gomega.HaveOccurred())
-			gomega.Expect(sql).To(gomega.Equal("exists (select 1 from json_tree(media_file.tags, '$.mood') where key='value' and value LIKE ?)"))
-			gomega.Expect(args).To(gomega.HaveExactElements("%Soft"))
-		})
-		It("casts numeric comparisons", func() {
-			AddNumericTags([]string{"rate"})
-			op := Lt{"rate": 6}
-			sql, args, err := op.ToSql()
-			gomega.Expect(err).ToNot(gomega.HaveOccurred())
-			gomega.Expect(sql).To(gomega.Equal("exists (select 1 from json_tree(media_file.tags, '$.rate') where key='value' and CAST(value AS REAL) < ?)"))
-			gomega.Expect(args).To(gomega.HaveExactElements(6))
-		})
-		It("skips unknown tag names", func() {
-			op := EndsWith{"unknown": "value"}
-			sql, args, _ := op.ToSql()
-			gomega.Expect(sql).To(gomega.BeEmpty())
-			gomega.Expect(args).To(gomega.BeEmpty())
-		})
-		It("supports releasetype as multi-valued tag", func() {
-			AddTagNames([]string{"releasetype"})
-			op := Contains{"releasetype": "soundtrack"}
-			sql, args, err := op.ToSql()
-			gomega.Expect(err).ToNot(gomega.HaveOccurred())
-			gomega.Expect(sql).To(gomega.Equal("exists (select 1 from json_tree(media_file.tags, '$.releasetype') where key='value' and value LIKE ?)"))
-			gomega.Expect(args).To(gomega.HaveExactElements("%soundtrack%"))
-		})
-		It("supports albumtype as alias for releasetype", func() {
-			AddTagNames([]string{"releasetype"})
-			op := Contains{"albumtype": "live"}
-			sql, args, err := op.ToSql()
-			gomega.Expect(err).ToNot(gomega.HaveOccurred())
-			gomega.Expect(sql).To(gomega.Equal("exists (select 1 from json_tree(media_file.tags, '$.releasetype') where key='value' and value LIKE ?)"))
-			gomega.Expect(args).To(gomega.HaveExactElements("%live%"))
-		})
-		It("supports albumtype alias with Is operator", func() {
-			AddTagNames([]string{"releasetype"})
-			op := Is{"albumtype": "album"}
-			sql, args, err := op.ToSql()
-			gomega.Expect(err).ToNot(gomega.HaveOccurred())
-			// Should query $.releasetype, not $.albumtype
-			gomega.Expect(sql).To(gomega.Equal("exists (select 1 from json_tree(media_file.tags, '$.releasetype') where key='value' and value = ?)"))
-			gomega.Expect(args).To(gomega.HaveExactElements("album"))
-		})
-		It("supports albumtype alias with IsNot operator", func() {
-			AddTagNames([]string{"releasetype"})
-			op := IsNot{"albumtype": "compilation"}
-			sql, args, err := op.ToSql()
-			gomega.Expect(err).ToNot(gomega.HaveOccurred())
-			// Should query $.releasetype, not $.albumtype
-			gomega.Expect(sql).To(gomega.Equal("not exists (select 1 from json_tree(media_file.tags, '$.releasetype') where key='value' and value = ?)"))
-			gomega.Expect(args).To(gomega.HaveExactElements("compilation"))
-		})
-	})
-
-	Describe("Custom Roles", func() {
-		It("generates valid SQL", func() {
-			AddRoles([]string{"producer"})
-			op := EndsWith{"producer": "Eno"}
-			sql, args, err := op.ToSql()
-			gomega.Expect(err).ToNot(gomega.HaveOccurred())
-			gomega.Expect(sql).To(gomega.Equal("exists (select 1 from json_tree(media_file.participants, '$.producer') where key='name' and value LIKE ?)"))
-			gomega.Expect(args).To(gomega.HaveExactElements("%Eno"))
-		})
-		It("skips unknown roles", func() {
-			op := Contains{"groupie": "Penny Lane"}
-			sql, args, _ := op.ToSql()
-			gomega.Expect(sql).To(gomega.BeEmpty())
-			gomega.Expect(args).To(gomega.BeEmpty())
-		})
-	})
-
-	DescribeTable("ToSql idempotency",
-		func(expr Expression) {
-			sql1, args1, err1 := expr.ToSql()
-			sql2, args2, err2 := expr.ToSql()
-
-			gomega.Expect(err1).ToNot(gomega.HaveOccurred())
-			gomega.Expect(err2).ToNot(gomega.HaveOccurred())
-			gomega.Expect(sql2).To(gomega.Equal(sql1))
-			gomega.Expect(args2).To(gomega.Equal(args1))
-		},
-		Entry("tag expression", Is{"genre": "Rock"}),
-		Entry("role expression", Contains{"artist": "Beatles"}),
-		Entry("nested criteria", Criteria{Expression: All{Is{"genre": "Rock"}, Contains{"artist": "Beatles"}}}),
-	)
-
 	DescribeTable("JSON Marshaling",
 		func(op Expression, jsonString string) {
 			obj := And{op}

model/criteria/sort.go

@@ -0,0 +1,62 @@
+package criteria
+
+import (
+	"strings"
+
+	"github.com/navidrome/navidrome/log"
+)
+
+type SortField struct {
+	Field string
+	Desc  bool
+}
+
+func (c Criteria) OrderByFields() []SortField {
+	sortValue := c.Sort
+	if sortValue == "" {
+		sortValue = "title"
+	}
+
+	order := strings.ToLower(strings.TrimSpace(c.Order))
+	if order != "" && order != "asc" && order != "desc" {
+		log.Error("Invalid value in 'order' field. Valid values: 'asc', 'desc'", "order", c.Order)
+		order = ""
+	}
+
+	parts := strings.Split(sortValue, ",")
+	fields := make([]SortField, 0, len(parts))
+	for _, part := range parts {
+		part = strings.TrimSpace(part)
+		if part == "" {
+			continue
+		}
+		desc := false
+		if strings.HasPrefix(part, "+") || strings.HasPrefix(part, "-") {
+			desc = strings.HasPrefix(part, "-")
+			part = strings.TrimSpace(part[1:])
+		}
+		info, ok := LookupField(part)
+		if !ok {
+			log.Error("Invalid field in 'sort' field", "sort", part)
+			continue
+		}
+		if order == "desc" {
+			desc = !desc
+		}
+		fields = append(fields, SortField{Field: info.Name, Desc: desc})
+	}
+	if len(fields) == 0 {
+		log.Warn("No valid sort fields found in 'sort', falling back to 'title'", "sort", sortValue)
+		return []SortField{{Field: "title", Desc: false}}
+	}
+	return fields
+}
+
+func (c Criteria) SortFieldNames() []string {
+	sortFields := c.OrderByFields()
+	names := make([]string, len(sortFields))
+	for i, sf := range sortFields {
+		names[i] = sf.Field
+	}
+	return names
+}

model/criteria/sort_test.go

@@ -0,0 +1,103 @@
+package criteria
+
+import (
+	. "github.com/onsi/ginkgo/v2"
+	"github.com/onsi/gomega"
+)
+
+var _ = Describe("OrderByFields", func() {
+	It("defaults to title ascending when Sort is empty", func() {
+		c := Criteria{}
+		gomega.Expect(c.OrderByFields()).To(gomega.Equal([]SortField{{Field: "title", Desc: false}}))
+	})
+
+	It("parses a single field", func() {
+		c := Criteria{Sort: "title"}
+		gomega.Expect(c.OrderByFields()).To(gomega.Equal([]SortField{{Field: "title", Desc: false}}))
+	})
+
+	It("parses descending prefix", func() {
+		c := Criteria{Sort: "-rating"}
+		gomega.Expect(c.OrderByFields()).To(gomega.Equal([]SortField{{Field: "rating", Desc: true}}))
+	})
+
+	It("parses ascending prefix", func() {
+		c := Criteria{Sort: "+title"}
+		gomega.Expect(c.OrderByFields()).To(gomega.Equal([]SortField{{Field: "title", Desc: false}}))
+	})
+
+	It("parses multiple comma-separated fields", func() {
+		c := Criteria{Sort: "title,-rating"}
+		gomega.Expect(c.OrderByFields()).To(gomega.Equal([]SortField{
+			{Field: "title", Desc: false},
+			{Field: "rating", Desc: true},
+		}))
+	})
+
+	It("inverts directions when Order is desc", func() {
+		c := Criteria{Sort: "-date,title", Order: "desc"}
+		gomega.Expect(c.OrderByFields()).To(gomega.Equal([]SortField{
+			{Field: "date", Desc: false},
+			{Field: "title", Desc: true},
+		}))
+	})
+
+	It("skips invalid fields", func() {
+		c := Criteria{Sort: "bogus,title"}
+		gomega.Expect(c.OrderByFields()).To(gomega.Equal([]SortField{{Field: "title", Desc: false}}))
+	})
+
+	It("falls back to title when all fields are invalid", func() {
+		c := Criteria{Sort: "bogus,invalid"}
+		gomega.Expect(c.OrderByFields()).To(gomega.Equal([]SortField{{Field: "title", Desc: false}}))
+	})
+
+	It("resolves tag aliases (albumtype -> releasetype)", func() {
+		c := Criteria{Sort: "albumtype"}
+		gomega.Expect(c.OrderByFields()).To(gomega.Equal([]SortField{{Field: "releasetype", Desc: false}}))
+	})
+
+	It("resolves field aliases (recordingdate -> date)", func() {
+		AddTagNames([]string{"recordingdate"})
+		c := Criteria{Sort: "recordingdate"}
+		gomega.Expect(c.OrderByFields()).To(gomega.Equal([]SortField{{Field: "date", Desc: false}}))
+	})
+
+	It("handles the random field", func() {
+		c := Criteria{Sort: "random"}
+		gomega.Expect(c.OrderByFields()).To(gomega.Equal([]SortField{{Field: "random", Desc: false}}))
+	})
+
+	It("ignores invalid Order value", func() {
+		c := Criteria{Sort: "-title", Order: "invalid"}
+		gomega.Expect(c.OrderByFields()).To(gomega.Equal([]SortField{{Field: "title", Desc: true}}))
+	})
+
+	It("handles whitespace in fields", func() {
+		c := Criteria{Sort: " title , -rating "}
+		gomega.Expect(c.OrderByFields()).To(gomega.Equal([]SortField{
+			{Field: "title", Desc: false},
+			{Field: "rating", Desc: true},
+		}))
+	})
+
+	It("skips empty parts from trailing commas", func() {
+		c := Criteria{Sort: "title,,rating,"}
+		gomega.Expect(c.OrderByFields()).To(gomega.Equal([]SortField{
+			{Field: "title", Desc: false},
+			{Field: "rating", Desc: false},
+		}))
+	})
+})
+
+var _ = Describe("SortFieldNames", func() {
+	It("returns canonical field names", func() {
+		c := Criteria{Sort: "title,-rating,albumtype"}
+		gomega.Expect(c.SortFieldNames()).To(gomega.Equal([]string{"title", "rating", "releasetype"}))
+	})
+
+	It("defaults to title when Sort is empty", func() {
+		c := Criteria{}
+		gomega.Expect(c.SortFieldNames()).To(gomega.Equal([]string{"title"}))
+	})
+})

model/criteria/walk.go

@@ -0,0 +1,37 @@
+package criteria
+
+import "fmt"
+
+type Visitor func(Expression) error
+
+func Walk(expr Expression, visit Visitor) error {
+	if expr == nil {
+		return nil
+	}
+	if err := visit(expr); err != nil {
+		return err
+	}
+	switch e := expr.(type) {
+	case All:
+		for _, child := range e {
+			if err := Walk(child, visit); err != nil {
+				return err
+			}
+		}
+	case Any:
+		for _, child := range e {
+			if err := Walk(child, visit); err != nil {
+				return err
+			}
+		}
+	case Is, IsNot, Gt, Lt, Before, After, Contains, NotContains, StartsWith, EndsWith, InTheRange, InTheLast, NotInTheLast, InPlaylist, NotInPlaylist:
+		return nil
+	default:
+		return fmt.Errorf("unknown criteria expression type %T", expr)
+	}
+	return nil
+}
+
+func Fields(expr Expression) map[string]any {
+	return expr.fields()
+}

model/criteria/walk_test.go

@@ -0,0 +1,64 @@
+package criteria
+
+import (
+	"fmt"
+
+	. "github.com/onsi/ginkgo/v2"
+	"github.com/onsi/gomega"
+)
+
+type unknownExpression struct{}
+
+func (unknownExpression) fields() map[string]any { return nil }
+
+var _ = Describe("Walk", func() {
+	It("visits the expression tree depth-first", func() {
+		expr := All{
+			Contains{"title": "love"},
+			Any{
+				Is{"album": "best of"},
+				Gt{"rating": 3},
+			},
+		}
+
+		var visited []string
+		err := Walk(expr, func(expr Expression) error {
+			visited = append(visited, fmt.Sprintf("%T", expr))
+			return nil
+		})
+
+		gomega.Expect(err).ToNot(gomega.HaveOccurred())
+		gomega.Expect(visited).To(gomega.Equal([]string{
+			"criteria.All",
+			"criteria.Contains",
+			"criteria.Any",
+			"criteria.Is",
+			"criteria.Gt",
+		}))
+	})
+
+	It("stops when the visitor returns an error", func() {
+		expectedErr := fmt.Errorf("stop")
+
+		err := Walk(All{Contains{"title": "love"}}, func(Expression) error {
+			return expectedErr
+		})
+
+		gomega.Expect(err).To(gomega.MatchError(expectedErr))
+	})
+
+	It("returns fields for leaf expressions", func() {
+		gomega.Expect(Fields(Contains{"title": "love"})).To(gomega.Equal(map[string]any{"title": "love"}))
+		gomega.Expect(Fields(After{"date": "2020-01-01"})).To(gomega.Equal(map[string]any{"date": "2020-01-01"}))
+	})
+
+	It("returns nil fields for group expressions", func() {
+		gomega.Expect(Fields(All{Contains{"title": "love"}})).To(gomega.BeNil())
+	})
+
+	It("returns an error for unknown expression types", func() {
+		err := Walk(unknownExpression{}, func(Expression) error { return nil })
+
+		gomega.Expect(err).To(gomega.MatchError("unknown criteria expression type criteria.unknownExpression"))
+	})
+})

model/folder_test.go

@@ -7,6 +7,7 @@ import (
 
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/id"
+	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -66,6 +67,7 @@ var _ = Describe("Folder", func() {
 
 		When("the folder has multiple subdirs", func() {
 			It("should return the correct folder ID", func() {
+				tests.SkipOnWindows("path separator bug (#TBD-path-sep-model)")
 				folderPath := filepath.FromSlash("/music/rock/metal")
 				expectedID := id.NewHash("1:rock/metal")
 				Expect(model.FolderID(lib, folderPath)).To(Equal(expectedID))
@@ -75,6 +77,7 @@ var _ = Describe("Folder", func() {
 
 	Describe("NewFolder", func() {
 		It("should create a new SubFolder with the correct attributes", func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-model)")
 			folderPath := filepath.FromSlash("rock/metal")
 			folder := model.NewFolder(lib, folderPath)
 

model/mediafile_test.go

@@ -6,6 +6,7 @@ import (
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
 	. "github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -22,7 +23,7 @@ var _ = Describe("MediaFiles", func() {
 						SortAlbumName: "SortAlbumName", SortArtistName: "SortArtistName", SortAlbumArtistName: "SortAlbumArtistName",
 						OrderAlbumName: "OrderAlbumName", OrderAlbumArtistName: "OrderAlbumArtistName",
 						MbzAlbumArtistID: "MbzAlbumArtistID", MbzAlbumType: "MbzAlbumType", MbzAlbumComment: "MbzAlbumComment",
-						MbzReleaseGroupID: "MbzReleaseGroupID", Compilation: false, CatalogNum: "", Path: "/music1/file1.mp3", FolderID: "Folder1",
+						MbzReleaseGroupID: "MbzReleaseGroupID", Compilation: false, CatalogNum: "", Path: "music1/file1.mp3", FolderID: "Folder1",
 					},
 					{
 						ID: "2", Album: "Album", ArtistID: "ArtistID", Artist: "Artist", AlbumArtistID: "AlbumArtistID", AlbumArtist: "AlbumArtist", AlbumID: "AlbumID",
@@ -30,7 +31,7 @@ var _ = Describe("MediaFiles", func() {
 						OrderAlbumName: "OrderAlbumName", OrderArtistName: "OrderArtistName", OrderAlbumArtistName: "OrderAlbumArtistName",
 						MbzAlbumArtistID: "MbzAlbumArtistID", MbzAlbumType: "MbzAlbumType", MbzAlbumComment: "MbzAlbumComment",
 						MbzReleaseGroupID: "MbzReleaseGroupID",
-						Compilation:       true, CatalogNum: "CatalogNum", HasCoverArt: true, Path: "/music2/file2.mp3", FolderID: "Folder2",
+						Compilation:       true, CatalogNum: "CatalogNum", HasCoverArt: true, Path: "music2/file2.mp3", FolderID: "Folder2",
 					},
 				}
 			})
@@ -51,7 +52,7 @@ var _ = Describe("MediaFiles", func() {
 				Expect(album.MbzReleaseGroupID).To(Equal("MbzReleaseGroupID"))
 				Expect(album.CatalogNum).To(Equal("CatalogNum"))
 				Expect(album.Compilation).To(BeTrue())
-				Expect(album.EmbedArtPath).To(Equal("/music2/file2.mp3"))
+				Expect(album.EmbedArtPath).To(Equal("music2/file2.mp3"))
 				Expect(album.FolderIDs).To(ConsistOf("Folder1", "Folder2"))
 			})
 		})
@@ -447,6 +448,9 @@ var _ = Describe("MediaFiles", func() {
 
 			DescribeTable("generates correct output",
 				func(absolutePaths bool, expectedContent string) {
+					if absolutePaths {
+						tests.SkipOnWindows("path separator bug (#TBD-path-sep-model)")
+					}
 					result := mfs.ToM3U8("Multi Track", absolutePaths)
 					Expect(result).To(Equal(expectedContent))
 				},
@@ -467,6 +471,7 @@ var _ = Describe("MediaFiles", func() {
 
 		Context("path variations", func() {
 			It("handles different path structures", func() {
+				tests.SkipOnWindows("path separator bug (#TBD-path-sep-model)")
 				mfs = MediaFiles{
 					{Title: "Root", Artist: "Artist", Duration: 60, Path: "song.mp3", LibraryPath: "/lib"},
 					{Title: "Nested", Artist: "Artist", Duration: 60, Path: "deep/nested/song.mp3", LibraryPath: "/lib"},

model/metadata/persistent_ids_test.go

@@ -6,6 +6,7 @@ import (
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -79,6 +80,7 @@ var _ = Describe("getPID", func() {
 		})
 		When("field is folder", func() {
 			It("should return the pid", func() {
+				tests.SkipOnWindows("path separator bug (#TBD-path-sep-metadata)")
 				spec := "folder|title"
 				md.tags = map[model.TagName][]string{"title": {"title"}}
 				mf.Path = "/path/to/file.mp3"

model/playlist.go

@@ -123,7 +123,7 @@ type PlaylistRepository interface {
 	ResourceRepository
 	CountAll(options ...QueryOptions) (int64, error)
 	Exists(id string) (bool, error)
-	Put(pls *Playlist) error
+	Put(pls *Playlist, cols ...string) error
 	Get(id string) (*Playlist, error)
 	GetWithTracks(id string, refreshSmartPlaylist, includeMissing bool) (*Playlist, error)
 	GetAll(options ...QueryOptions) (Playlists, error)

model/playlist_test.go

@@ -2,6 +2,7 @@ package model_test
 
 import (
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -27,6 +28,7 @@ var _ = Describe("Playlist", func() {
 			}
 		})
 		It("generates the correct M3U format", func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-model)")
 			expected := `#EXTM3U
 #PLAYLIST:Mellow sunset
 #EXTINF:378,Morcheeba feat. Kurt Wagner - What New York Couples Fight About

persistence/criteria_sql.go

@@ -0,0 +1,464 @@
+package persistence
+
+import (
+	"errors"
+	"fmt"
+	"reflect"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/criteria"
+)
+
+type smartPlaylistJoinType int
+
+const (
+	smartPlaylistJoinNone            smartPlaylistJoinType = 0
+	smartPlaylistJoinAlbumAnnotation smartPlaylistJoinType = 1 << iota
+	smartPlaylistJoinArtistAnnotation
+)
+
+func (j smartPlaylistJoinType) has(other smartPlaylistJoinType) bool {
+	return j&other != 0
+}
+
+type smartPlaylistField struct {
+	expr     string
+	order    string
+	joinType smartPlaylistJoinType
+}
+
+type smartPlaylistCriteria struct {
+	criteria.Criteria
+	owner model.User
+}
+
+func newSmartPlaylistCriteria(c criteria.Criteria, opts ...func(*smartPlaylistCriteria)) smartPlaylistCriteria {
+	cSQL := smartPlaylistCriteria{Criteria: c}
+	for _, opt := range opts {
+		opt(&cSQL)
+	}
+	return cSQL
+}
+
+func withSmartPlaylistOwner(owner model.User) func(*smartPlaylistCriteria) {
+	return func(c *smartPlaylistCriteria) {
+		c.owner = owner
+	}
+}
+
+var smartPlaylistFields = map[string]smartPlaylistField{
+	"title":                {expr: "media_file.title"},
+	"album":                {expr: "media_file.album"},
+	"hascoverart":          {expr: "media_file.has_cover_art"},
+	"tracknumber":          {expr: "media_file.track_number"},
+	"discnumber":           {expr: "media_file.disc_number"},
+	"year":                 {expr: "media_file.year"},
+	"date":                 {expr: "media_file.date"},
+	"originalyear":         {expr: "media_file.original_year"},
+	"originaldate":         {expr: "media_file.original_date"},
+	"releaseyear":          {expr: "media_file.release_year"},
+	"releasedate":          {expr: "media_file.release_date"},
+	"size":                 {expr: "media_file.size"},
+	"compilation":          {expr: "media_file.compilation"},
+	"missing":              {expr: "media_file.missing"},
+	"explicitstatus":       {expr: "media_file.explicit_status"},
+	"dateadded":            {expr: "media_file.created_at"},
+	"datemodified":         {expr: "media_file.updated_at"},
+	"discsubtitle":         {expr: "media_file.disc_subtitle"},
+	"comment":              {expr: "media_file.comment"},
+	"lyrics":               {expr: "media_file.lyrics"},
+	"sorttitle":            {expr: "media_file.sort_title"},
+	"sortalbum":            {expr: "media_file.sort_album_name"},
+	"sortartist":           {expr: "media_file.sort_artist_name"},
+	"sortalbumartist":      {expr: "media_file.sort_album_artist_name"},
+	"albumcomment":         {expr: "media_file.mbz_album_comment"},
+	"catalognumber":        {expr: "media_file.catalog_num"},
+	"filepath":             {expr: "media_file.path"},
+	"filetype":             {expr: "media_file.suffix"},
+	"codec":                {expr: "media_file.codec"},
+	"duration":             {expr: "media_file.duration"},
+	"bitrate":              {expr: "media_file.bit_rate"},
+	"bitdepth":             {expr: "media_file.bit_depth"},
+	"samplerate":           {expr: "media_file.sample_rate"},
+	"bpm":                  {expr: "media_file.bpm"},
+	"channels":             {expr: "media_file.channels"},
+	"loved":                {expr: "COALESCE(annotation.starred, false)"},
+	"dateloved":            {expr: "annotation.starred_at"},
+	"lastplayed":           {expr: "annotation.play_date"},
+	"daterated":            {expr: "annotation.rated_at"},
+	"playcount":            {expr: "COALESCE(annotation.play_count, 0)"},
+	"rating":               {expr: "COALESCE(annotation.rating, 0)"},
+	"averagerating":        {expr: "media_file.average_rating"},
+	"albumrating":          {expr: "COALESCE(album_annotation.rating, 0)", joinType: smartPlaylistJoinAlbumAnnotation},
+	"albumloved":           {expr: "COALESCE(album_annotation.starred, false)", joinType: smartPlaylistJoinAlbumAnnotation},
+	"albumplaycount":       {expr: "COALESCE(album_annotation.play_count, 0)", joinType: smartPlaylistJoinAlbumAnnotation},
+	"albumlastplayed":      {expr: "album_annotation.play_date", joinType: smartPlaylistJoinAlbumAnnotation},
+	"albumdateloved":       {expr: "album_annotation.starred_at", joinType: smartPlaylistJoinAlbumAnnotation},
+	"albumdaterated":       {expr: "album_annotation.rated_at", joinType: smartPlaylistJoinAlbumAnnotation},
+	"artistrating":         {expr: "COALESCE(artist_annotation.rating, 0)", joinType: smartPlaylistJoinArtistAnnotation},
+	"artistloved":          {expr: "COALESCE(artist_annotation.starred, false)", joinType: smartPlaylistJoinArtistAnnotation},
+	"artistplaycount":      {expr: "COALESCE(artist_annotation.play_count, 0)", joinType: smartPlaylistJoinArtistAnnotation},
+	"artistlastplayed":     {expr: "artist_annotation.play_date", joinType: smartPlaylistJoinArtistAnnotation},
+	"artistdateloved":      {expr: "artist_annotation.starred_at", joinType: smartPlaylistJoinArtistAnnotation},
+	"artistdaterated":      {expr: "artist_annotation.rated_at", joinType: smartPlaylistJoinArtistAnnotation},
+	"mbz_album_id":         {expr: "media_file.mbz_album_id"},
+	"mbz_album_artist_id":  {expr: "media_file.mbz_album_artist_id"},
+	"mbz_artist_id":        {expr: "media_file.mbz_artist_id"},
+	"mbz_recording_id":     {expr: "media_file.mbz_recording_id"},
+	"mbz_release_track_id": {expr: "media_file.mbz_release_track_id"},
+	"mbz_release_group_id": {expr: "media_file.mbz_release_group_id"},
+	"library_id":           {expr: "media_file.library_id"},
+	"random":               {order: "random()"},
+	"value":                {expr: "value"},
+}
+
+func (c smartPlaylistCriteria) Where() (squirrel.Sqlizer, error) {
+	if c.Criteria.Expression == nil {
+		return squirrel.Expr("1 = 1"), nil
+	}
+	return c.exprSQL(c.Criteria.Expression)
+}
+
+func (c smartPlaylistCriteria) exprSQL(expr criteria.Expression) (squirrel.Sqlizer, error) {
+	switch e := expr.(type) {
+	case criteria.All:
+		and := squirrel.And{}
+		for _, child := range e {
+			cond, err := c.exprSQL(child)
+			if err != nil {
+				return nil, err
+			}
+			and = append(and, cond)
+		}
+		return and, nil
+	case criteria.Any:
+		or := squirrel.Or{}
+		for _, child := range e {
+			cond, err := c.exprSQL(child)
+			if err != nil {
+				return nil, err
+			}
+			or = append(or, cond)
+		}
+		return or, nil
+	case criteria.Is:
+		return mapExpr(e, func(fields map[string]any) squirrel.Sqlizer {
+			return squirrel.Eq(fields)
+		}, false)
+	case criteria.IsNot:
+		return isNotExpr(e)
+	case criteria.Gt:
+		return mapExpr(e, func(fields map[string]any) squirrel.Sqlizer {
+			return squirrel.Gt(fields)
+		}, false)
+	case criteria.Lt:
+		return mapExpr(e, func(fields map[string]any) squirrel.Sqlizer {
+			return squirrel.Lt(fields)
+		}, false)
+	case criteria.Before:
+		return mapExpr(e, func(fields map[string]any) squirrel.Sqlizer {
+			return squirrel.Lt(fields)
+		}, false)
+	case criteria.After:
+		return mapExpr(e, func(fields map[string]any) squirrel.Sqlizer {
+			return squirrel.Gt(fields)
+		}, false)
+	case criteria.Contains:
+		return likeExpr(e, "%%%v%%", false)
+	case criteria.NotContains:
+		return likeExpr(e, "%%%v%%", true)
+	case criteria.StartsWith:
+		return likeExpr(e, "%v%%", false)
+	case criteria.EndsWith:
+		return likeExpr(e, "%%%v", false)
+	case criteria.InTheRange:
+		return rangeExpr(e)
+	case criteria.InTheLast:
+		return periodExpr(e, false)
+	case criteria.NotInTheLast:
+		return periodExpr(e, true)
+	case criteria.InPlaylist:
+		return c.inList(e, false)
+	case criteria.NotInPlaylist:
+		return c.inList(e, true)
+	default:
+		return nil, fmt.Errorf("unknown criteria expression type %T", expr)
+	}
+}
+
+func isNotExpr(values map[string]any) (squirrel.Sqlizer, error) {
+	if _, value, info, ok := singleField(values); ok && (info.IsTag || info.IsRole) {
+		return jsonExpr(info, squirrel.Eq{"value": value}, true), nil
+	}
+	fields, err := sqlFields(values)
+	if err != nil {
+		return nil, err
+	}
+	return squirrel.NotEq(fields), nil
+}
+
+func mapExpr(values map[string]any, makeCond func(map[string]any) squirrel.Sqlizer, negateJSON bool) (squirrel.Sqlizer, error) {
+	if _, value, info, ok := singleField(values); ok && (info.IsTag || info.IsRole) {
+		return jsonExpr(info, makeCond(map[string]any{"value": value}), negateJSON), nil
+	}
+	fields, err := sqlFields(values)
+	if err != nil {
+		return nil, err
+	}
+	return makeCond(fields), nil
+}
+
+func likeExpr(values map[string]any, pattern string, negate bool) (squirrel.Sqlizer, error) {
+	if _, value, info, ok := singleField(values); ok && (info.IsTag || info.IsRole) {
+		return jsonExpr(info, squirrel.Like{"value": fmt.Sprintf(pattern, value)}, negate), nil
+	}
+	fields, err := sqlFields(values)
+	if err != nil {
+		return nil, err
+	}
+	if negate {
+		lk := squirrel.NotLike{}
+		for field, value := range fields {
+			lk[field] = fmt.Sprintf(pattern, value)
+		}
+		return lk, nil
+	}
+	lk := squirrel.Like{}
+	for field, value := range fields {
+		lk[field] = fmt.Sprintf(pattern, value)
+	}
+	return lk, nil
+}
+
+func rangeExpr(values map[string]any) (squirrel.Sqlizer, error) {
+	fields, err := sqlFields(values)
+	if err != nil {
+		return nil, err
+	}
+	and := squirrel.And{}
+	for field, value := range fields {
+		s := reflect.ValueOf(value)
+		if s.Kind() != reflect.Slice || s.Len() != 2 {
+			return nil, fmt.Errorf("invalid range for 'in' operator: %s", value)
+		}
+		and = append(and,
+			squirrel.GtOrEq{field: s.Index(0).Interface()},
+			squirrel.LtOrEq{field: s.Index(1).Interface()},
+		)
+	}
+	return and, nil
+}
+
+func periodExpr(values map[string]any, negate bool) (squirrel.Sqlizer, error) {
+	fields, err := sqlFields(values)
+	if err != nil {
+		return nil, err
+	}
+	var field string
+	var value any
+	for f, v := range fields {
+		field, value = f, v
+		break
+	}
+	days, err := strconv.ParseInt(fmt.Sprintf("%v", value), 10, 64)
+	if err != nil {
+		return nil, err
+	}
+	firstDate := startOfPeriod(days, time.Now())
+	if negate {
+		return squirrel.Or{
+			squirrel.Lt{field: firstDate},
+			squirrel.Eq{field: nil},
+		}, nil
+	}
+	return squirrel.Gt{field: firstDate}, nil
+}
+
+func startOfPeriod(numDays int64, from time.Time) string {
+	return from.Add(time.Duration(-24*numDays) * time.Hour).Format("2006-01-02")
+}
+
+func (c smartPlaylistCriteria) inList(values map[string]any, negate bool) (squirrel.Sqlizer, error) {
+	playlistID, ok := values["id"].(string)
+	if !ok {
+		return nil, errors.New("playlist id not given")
+	}
+	filters := squirrel.And{squirrel.Eq{"pl.playlist_id": playlistID}}
+	if !c.owner.IsAdmin {
+		if c.owner.ID == "" {
+			filters = append(filters, squirrel.Eq{"playlist.public": 1})
+		} else {
+			filters = append(filters, squirrel.Or{
+				squirrel.Eq{"playlist.public": 1},
+				squirrel.Eq{"playlist.owner_id": c.owner.ID},
+			})
+		}
+	}
+	subQuery := squirrel.Select("media_file_id").
+		From("playlist_tracks pl").
+		LeftJoin("playlist on pl.playlist_id = playlist.id").
+		Where(filters)
+	subSQL, subArgs, err := subQuery.PlaceholderFormat(squirrel.Question).ToSql()
+	if err != nil {
+		return nil, err
+	}
+	if negate {
+		return squirrel.Expr("media_file.id NOT IN ("+subSQL+")", subArgs...), nil
+	}
+	return squirrel.Expr("media_file.id IN ("+subSQL+")", subArgs...), nil
+}
+
+func jsonExpr(info criteria.FieldInfo, cond squirrel.Sqlizer, negate bool) squirrel.Sqlizer {
+	if info.IsRole {
+		return roleCond{role: info.Name, cond: cond, not: negate}
+	}
+	return tagCond{tag: info.Name, numeric: info.Numeric, cond: cond, not: negate}
+}
+
+type tagCond struct {
+	tag     string
+	numeric bool
+	cond    squirrel.Sqlizer
+	not     bool
+}
+
+func (e tagCond) ToSql() (string, []any, error) {
+	cond, args, err := e.cond.ToSql()
+	if e.numeric {
+		cond = strings.ReplaceAll(cond, "value", "CAST(value AS REAL)")
+	}
+	cond = fmt.Sprintf("exists (select 1 from json_tree(media_file.tags, '$.%s') where key='value' and %s)", e.tag, cond)
+	if e.not {
+		cond = "not " + cond
+	}
+	return cond, args, err
+}
+
+type roleCond struct {
+	role string
+	cond squirrel.Sqlizer
+	not  bool
+}
+
+func (e roleCond) ToSql() (string, []any, error) {
+	cond, args, err := e.cond.ToSql()
+	cond = fmt.Sprintf("exists (select 1 from json_tree(media_file.participants, '$.%s') where key='name' and %s)", e.role, cond)
+	if e.not {
+		cond = "not " + cond
+	}
+	return cond, args, err
+}
+
+func singleField(values map[string]any) (string, any, criteria.FieldInfo, bool) {
+	if len(values) != 1 {
+		return "", nil, criteria.FieldInfo{}, false
+	}
+	for field, value := range values {
+		info, ok := criteria.LookupField(field)
+		return field, value, info, ok
+	}
+	return "", nil, criteria.FieldInfo{}, false
+}
+
+func sqlFields(values map[string]any) (map[string]any, error) {
+	fields := make(map[string]any, len(values))
+	for field, value := range values {
+		info, ok := criteria.LookupField(field)
+		if !ok {
+			return nil, fmt.Errorf("invalid field in criteria: %s", field)
+		}
+		if info.IsTag || info.IsRole {
+			return nil, fmt.Errorf("tag and role criteria must contain exactly one field: %s", field)
+		}
+		sqlField, ok := fieldExpr(info.Name)
+		if !ok || sqlField == "" {
+			return nil, fmt.Errorf("invalid field in criteria: %s", field)
+		}
+		fields[sqlField] = value
+	}
+	return fields, nil
+}
+
+func fieldExpr(name string) (string, bool) {
+	field, ok := smartPlaylistFields[strings.ToLower(name)]
+	return field.expr, ok
+}
+
+func fieldJoinType(name string) smartPlaylistJoinType {
+	info, ok := criteria.LookupField(name)
+	if !ok {
+		return smartPlaylistJoinNone
+	}
+	field, ok := smartPlaylistFields[info.Name]
+	if !ok {
+		return smartPlaylistJoinNone
+	}
+	return field.joinType
+}
+
+func (c smartPlaylistCriteria) ExpressionJoins() smartPlaylistJoinType {
+	var joins smartPlaylistJoinType
+	_ = criteria.Walk(c.Criteria.Expression, func(expr criteria.Expression) error {
+		for field := range criteria.Fields(expr) {
+			joins |= fieldJoinType(field)
+		}
+		return nil
+	})
+	return joins
+}
+
+func (c smartPlaylistCriteria) RequiredJoins() smartPlaylistJoinType {
+	joins := c.ExpressionJoins()
+	for _, name := range c.Criteria.SortFieldNames() {
+		joins |= fieldJoinType(name)
+	}
+	return joins
+}
+
+func (c smartPlaylistCriteria) OrderBy() string {
+	sortFields := c.Criteria.OrderByFields()
+	parts := make([]string, 0, len(sortFields))
+	for _, sf := range sortFields {
+		mapped, ok := sortExpr(sf.Field)
+		if !ok {
+			continue
+		}
+		dir := "asc"
+		if sf.Desc {
+			dir = "desc"
+		}
+		parts = append(parts, mapped+" "+dir)
+	}
+	return strings.Join(parts, ", ")
+}
+
+func sortExpr(sortField string) (string, bool) {
+	info, ok := criteria.LookupField(sortField)
+	if !ok {
+		return "", false
+	}
+	if field, ok := smartPlaylistFields[info.Name]; ok && field.order != "" {
+		return field.order, true
+	}
+	var mapped string
+	switch {
+	case info.IsTag:
+		mapped = "COALESCE(json_extract(media_file.tags, '$." + info.Name + "[0].value'), '')"
+	case info.IsRole:
+		mapped = "COALESCE(json_extract(media_file.participants, '$." + info.Name + "[0].name'), '')"
+	default:
+		field, ok := smartPlaylistFields[info.Name]
+		if !ok || field.expr == "" {
+			return "", false
+		}
+		mapped = field.expr
+	}
+	if info.Numeric {
+		mapped = fmt.Sprintf("CAST(%s AS REAL)", mapped)
+	}
+	return mapped, true
+}

persistence/criteria_sql_test.go

@@ -0,0 +1,200 @@
+package persistence
+
+import (
+	"time"
+
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/criteria"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Smart playlist criteria SQL", func() {
+	BeforeEach(func() {
+		criteria.AddRoles([]string{"artist", "composer", "producer"})
+		criteria.AddTagNames([]string{"genre", "mood", "releasetype", "recordingdate"})
+		criteria.AddNumericTags([]string{"rate"})
+	})
+
+	DescribeTable("expressions",
+		func(expr criteria.Expression, expectedSQL string, expectedArgs ...any) {
+			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).Where()
+			Expect(err).ToNot(HaveOccurred())
+
+			sql, args, err := sqlizer.ToSql()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(sql).To(Equal(expectedSQL))
+			Expect(args).To(HaveExactElements(expectedArgs...))
+		},
+		Entry("all group",
+			criteria.All{criteria.Contains{"title": "love"}, criteria.Gt{"rating": 3}},
+			"(media_file.title LIKE ? AND COALESCE(annotation.rating, 0) > ?)", "%love%", 3),
+		Entry("any group",
+			criteria.Any{criteria.Is{"title": "Low Rider"}, criteria.Is{"album": "Best Of"}},
+			"(media_file.title = ? OR media_file.album = ?)", "Low Rider", "Best Of"),
+		Entry("is string", criteria.Is{"title": "Low Rider"}, "media_file.title = ?", "Low Rider"),
+		Entry("is bool", criteria.Is{"loved": true}, "COALESCE(annotation.starred, false) = ?", true),
+		Entry("is numeric list", criteria.Is{"library_id": []int{1, 2}}, "media_file.library_id IN (?,?)", 1, 2),
+		Entry("is not", criteria.IsNot{"title": "Low Rider"}, "media_file.title <> ?", "Low Rider"),
+		Entry("gt", criteria.Gt{"playCount": 10}, "COALESCE(annotation.play_count, 0) > ?", 10),
+		Entry("lt", criteria.Lt{"playCount": 10}, "COALESCE(annotation.play_count, 0) < ?", 10),
+		Entry("contains", criteria.Contains{"title": "Low Rider"}, "media_file.title LIKE ?", "%Low Rider%"),
+		Entry("not contains", criteria.NotContains{"title": "Low Rider"}, "media_file.title NOT LIKE ?", "%Low Rider%"),
+		Entry("starts with", criteria.StartsWith{"title": "Low Rider"}, "media_file.title LIKE ?", "Low Rider%"),
+		Entry("ends with", criteria.EndsWith{"title": "Low Rider"}, "media_file.title LIKE ?", "%Low Rider"),
+		Entry("in range", criteria.InTheRange{"year": []int{1980, 1990}}, "(media_file.year >= ? AND media_file.year <= ?)", 1980, 1990),
+		Entry("before", criteria.Before{"lastPlayed": time.Date(2021, 10, 1, 0, 0, 0, 0, time.Local)}, "annotation.play_date < ?", time.Date(2021, 10, 1, 0, 0, 0, 0, time.Local)),
+		Entry("after", criteria.After{"lastPlayed": time.Date(2021, 10, 1, 0, 0, 0, 0, time.Local)}, "annotation.play_date > ?", time.Date(2021, 10, 1, 0, 0, 0, 0, time.Local)),
+		Entry("in playlist", criteria.InPlaylist{"id": "deadbeef-dead-beef"}, "media_file.id IN (SELECT media_file_id FROM playlist_tracks pl LEFT JOIN playlist on pl.playlist_id = playlist.id WHERE (pl.playlist_id = ? AND playlist.public = ?))", "deadbeef-dead-beef", 1),
+		Entry("not in playlist", criteria.NotInPlaylist{"id": "deadbeef-dead-beef"}, "media_file.id NOT IN (SELECT media_file_id FROM playlist_tracks pl LEFT JOIN playlist on pl.playlist_id = playlist.id WHERE (pl.playlist_id = ? AND playlist.public = ?))", "deadbeef-dead-beef", 1),
+		Entry("album annotation", criteria.Gt{"albumRating": 3}, "COALESCE(album_annotation.rating, 0) > ?", 3),
+		Entry("artist annotation", criteria.Is{"artistLoved": true}, "COALESCE(artist_annotation.starred, false) = ?", true),
+		Entry("tag is", criteria.Is{"genre": "Rock"}, "exists (select 1 from json_tree(media_file.tags, '$.genre') where key='value' and value = ?)", "Rock"),
+		Entry("tag is not", criteria.IsNot{"genre": "Rock"}, "not exists (select 1 from json_tree(media_file.tags, '$.genre') where key='value' and value = ?)", "Rock"),
+		Entry("tag contains", criteria.Contains{"genre": "Rock"}, "exists (select 1 from json_tree(media_file.tags, '$.genre') where key='value' and value LIKE ?)", "%Rock%"),
+		Entry("tag not contains", criteria.NotContains{"genre": "Rock"}, "not exists (select 1 from json_tree(media_file.tags, '$.genre') where key='value' and value LIKE ?)", "%Rock%"),
+		Entry("numeric tag", criteria.Lt{"rate": 6}, "exists (select 1 from json_tree(media_file.tags, '$.rate') where key='value' and CAST(value AS REAL) < ?)", 6),
+		Entry("tag alias", criteria.Is{"albumtype": "album"}, "exists (select 1 from json_tree(media_file.tags, '$.releasetype') where key='value' and value = ?)", "album"),
+		Entry("field alias via tag registration", criteria.Is{"recordingdate": "2024-01-01"}, "media_file.date = ?", "2024-01-01"),
+		Entry("role is", criteria.Is{"artist": "u2"}, "exists (select 1 from json_tree(media_file.participants, '$.artist') where key='name' and value = ?)", "u2"),
+		Entry("role contains", criteria.Contains{"composer": "Lennon"}, "exists (select 1 from json_tree(media_file.participants, '$.composer') where key='name' and value LIKE ?)", "%Lennon%"),
+		Entry("role not contains", criteria.NotContains{"artist": "u2"}, "not exists (select 1 from json_tree(media_file.participants, '$.artist') where key='name' and value LIKE ?)", "%u2%"),
+	)
+
+	Describe("playlist permissions", func() {
+		It("allows public or same-owner playlist references for regular users", func() {
+			sqlizer, err := newSmartPlaylistCriteria(
+				criteria.Criteria{Expression: criteria.InPlaylist{"id": "deadbeef-dead-beef"}},
+				withSmartPlaylistOwner(model.User{ID: "owner-id", IsAdmin: false}),
+			).Where()
+			Expect(err).ToNot(HaveOccurred())
+
+			sql, args, err := sqlizer.ToSql()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(sql).To(Equal("media_file.id IN (SELECT media_file_id FROM playlist_tracks pl LEFT JOIN playlist on pl.playlist_id = playlist.id WHERE (pl.playlist_id = ? AND (playlist.public = ? OR playlist.owner_id = ?)))"))
+			Expect(args).To(HaveExactElements("deadbeef-dead-beef", 1, "owner-id"))
+		})
+
+		It("allows all playlist references for admins", func() {
+			sqlizer, err := newSmartPlaylistCriteria(
+				criteria.Criteria{Expression: criteria.InPlaylist{"id": "deadbeef-dead-beef"}},
+				withSmartPlaylistOwner(model.User{ID: "admin-id", IsAdmin: true}),
+			).Where()
+			Expect(err).ToNot(HaveOccurred())
+
+			sql, args, err := sqlizer.ToSql()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(sql).To(Equal("media_file.id IN (SELECT media_file_id FROM playlist_tracks pl LEFT JOIN playlist on pl.playlist_id = playlist.id WHERE (pl.playlist_id = ?))"))
+			Expect(args).To(HaveExactElements("deadbeef-dead-beef"))
+		})
+	})
+
+	It("builds relative date expressions", func() {
+		sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: criteria.InTheLast{"lastPlayed": 30}}).Where()
+		Expect(err).ToNot(HaveOccurred())
+
+		sql, args, err := sqlizer.ToSql()
+		Expect(err).ToNot(HaveOccurred())
+		Expect(sql).To(Equal("annotation.play_date > ?"))
+		Expect(args).To(HaveExactElements(startOfPeriod(30, time.Now())))
+	})
+
+	It("builds negated relative date expressions", func() {
+		sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: criteria.NotInTheLast{"lastPlayed": 30}}).Where()
+		Expect(err).ToNot(HaveOccurred())
+
+		sql, args, err := sqlizer.ToSql()
+		Expect(err).ToNot(HaveOccurred())
+		Expect(sql).To(Equal("(annotation.play_date < ? OR annotation.play_date IS NULL)"))
+		Expect(args).To(HaveExactElements(startOfPeriod(30, time.Now())))
+	})
+
+	It("returns an error for unknown fields", func() {
+		_, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: criteria.EndsWith{"unknown": "value"}}).Where()
+
+		Expect(err).To(MatchError("invalid field in criteria: unknown"))
+	})
+
+	Describe("sort", func() {
+		It("sorts by regular fields", func() {
+			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "title"}).OrderBy()).To(Equal("media_file.title asc"))
+		})
+
+		It("sorts by tag fields", func() {
+			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "genre"}).OrderBy()).To(Equal("COALESCE(json_extract(media_file.tags, '$.genre[0].value'), '') asc"))
+		})
+
+		It("sorts by role fields", func() {
+			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "artist"}).OrderBy()).To(Equal("COALESCE(json_extract(media_file.participants, '$.artist[0].name'), '') asc"))
+		})
+
+		It("casts numeric tags when sorting", func() {
+			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "rate"}).OrderBy()).To(Equal("CAST(COALESCE(json_extract(media_file.tags, '$.rate[0].value'), '') AS REAL) asc"))
+		})
+
+		It("sorts by albumtype alias", func() {
+			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "albumtype"}).OrderBy()).To(Equal("COALESCE(json_extract(media_file.tags, '$.releasetype[0].value'), '') asc"))
+		})
+
+		It("sorts by random", func() {
+			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "random"}).OrderBy()).To(Equal("random() asc"))
+		})
+
+		It("sorts by multiple fields", func() {
+			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "title,-rating"}).OrderBy()).To(Equal("media_file.title asc, COALESCE(annotation.rating, 0) desc"))
+		})
+
+		It("reverts order when order is desc", func() {
+			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "-date,artist", Order: "desc"}).OrderBy()).To(Equal("media_file.date asc, COALESCE(json_extract(media_file.participants, '$.artist[0].name'), '') desc"))
+		})
+
+		It("ignores invalid sort fields", func() {
+			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "bogus,title"}).OrderBy()).To(Equal("media_file.title asc"))
+		})
+	})
+
+	It("has SQL mappings for all non-tag/non-role criteria fields", func() {
+		for _, name := range criteria.AllFieldNames() {
+			info, ok := criteria.LookupField(name)
+			Expect(ok).To(BeTrue(), "field %q registered but LookupField fails", name)
+			if info.IsTag || info.IsRole {
+				continue
+			}
+			_, hasSQLField := smartPlaylistFields[info.Name]
+			Expect(hasSQLField).To(BeTrue(), "criteria field %q (name=%q) has no entry in smartPlaylistFields", name, info.Name)
+		}
+	})
+
+	Describe("joins", func() {
+		It("excludes sort-only joins from expression joins", func() {
+			c := criteria.Criteria{Expression: criteria.All{criteria.Contains{"title": "love"}}, Sort: "albumRating"}
+			cSQL := newSmartPlaylistCriteria(c)
+
+			Expect(cSQL.ExpressionJoins()).To(Equal(smartPlaylistJoinNone))
+			Expect(cSQL.RequiredJoins().has(smartPlaylistJoinAlbumAnnotation)).To(BeTrue())
+		})
+
+		It("includes expression-based joins", func() {
+			c := criteria.Criteria{Expression: criteria.All{criteria.Gt{"albumRating": 3}}}
+
+			Expect(newSmartPlaylistCriteria(c).ExpressionJoins().has(smartPlaylistJoinAlbumAnnotation)).To(BeTrue())
+		})
+
+		It("detects nested album and artist joins", func() {
+			c := criteria.Criteria{Expression: criteria.All{
+				criteria.Any{criteria.All{criteria.Is{"albumLoved": true}}},
+				criteria.Any{criteria.Gt{"artistPlayCount": 10}},
+			}}
+
+			joins := newSmartPlaylistCriteria(c).RequiredJoins()
+			Expect(joins.has(smartPlaylistJoinAlbumAnnotation)).To(BeTrue())
+			Expect(joins.has(smartPlaylistJoinArtistAnnotation)).To(BeTrue())
+		})
+
+		It("detects join types from sort fields with direction prefixes", func() {
+			c := criteria.Criteria{Expression: criteria.All{criteria.Contains{"title": "love"}}, Sort: "-artistRating"}
+
+			Expect(newSmartPlaylistCriteria(c).RequiredJoins().has(smartPlaylistJoinArtistAnnotation)).To(BeTrue())
+		})
+	})
+})

persistence/e2e/e2e_suite_test.go

@@ -0,0 +1,345 @@
+package e2e
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"sort"
+	"testing"
+	"testing/fstest"
+	"time"
+
+	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/core/artwork"
+	"github.com/navidrome/navidrome/core/metrics"
+	"github.com/navidrome/navidrome/core/playlists"
+	"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/criteria"
+	"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 TestSmartPlaylistE2E(t *testing.T) {
+	tests.Init(t, false)
+	defer db.Close(t.Context())
+	log.SetLevel(log.LevelFatal)
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "Smart Playlist E2E Suite")
+}
+
+type _t = map[string]any
+
+var template = storagetest.Template
+var track = storagetest.Track
+
+var (
+	ctx context.Context
+	ds  *tests.MockDataStore
+	lib model.Library
+
+	dbFilePath     string
+	snapshotPath   string
+	snapshotTables []string
+
+	adminUser = model.User{
+		ID:       "sp-test-user-1",
+		UserName: "sptestuser",
+		Name:     "SP Test User",
+		IsAdmin:  true,
+	}
+
+	regularUser = model.User{
+		ID:       "sp-test-user-2",
+		UserName: "spotheruser",
+		Name:     "SP Other User",
+		IsAdmin:  false,
+	}
+)
+
+func buildTestFS() {
+	abbeyRoad := template(_t{
+		"albumartist": "The Beatles",
+		"artist":      "The Beatles",
+		"album":       "Abbey Road",
+		"year":        1969,
+		"genre":       "Rock;Blues",
+	})
+	ledZepIV := template(_t{
+		"albumartist": "Led Zeppelin",
+		"artist":      "Led Zeppelin",
+		"album":       "IV",
+		"year":        1971,
+	})
+	kindOfBlue := template(_t{
+		"albumartist": "Miles Davis",
+		"artist":      "Miles Davis",
+		"album":       "Kind of Blue",
+		"year":        1959,
+		"genre":       "Jazz",
+		"composer":    "Miles Davis",
+	})
+	nightAtOpera := template(_t{
+		"albumartist": "Queen",
+		"artist":      "Queen",
+		"album":       "A Night at the Opera",
+		"year":        1975,
+		"genre":       "Rock",
+	})
+	electricLadyland := template(_t{
+		"albumartist": "Jimi Hendrix",
+		"artist":      "Jimi Hendrix",
+		"album":       "Electric Ladyland",
+		"year":        1968,
+		"genre":       "Rock;Blues",
+	})
+	newsOfWorld := template(_t{
+		"albumartist": "Queen",
+		"artist":      "Queen",
+		"album":       "News of the World",
+		"year":        1977,
+		"genre":       "Rock;Pop",
+		"compilation": "1",
+	})
+
+	fs := storagetest.FakeFS{}
+	fs.SetFiles(fstest.MapFS{
+		"Rock/The Beatles/Abbey Road/01 - Come Together.mp3": abbeyRoad(track(1, "Come Together",
+			_t{"genre": "Rock;Blues", "composer": "Lennon/McCartney", "bpm": 120})),
+		"Rock/The Beatles/Abbey Road/02 - Something.mp3": abbeyRoad(track(2, "Something",
+			_t{"genre": "Rock", "composer": "Harrison", "bpm": 100})),
+		"Rock/Led Zeppelin/IV/01 - Stairway To Heaven.flac": ledZepIV(track(1, "Stairway To Heaven",
+			_t{"genre": "Rock;Folk", "composer": "Page/Plant", "bpm": 82, "suffix": "flac",
+				"bitrate": 900, "samplerate": 44100, "bitdepth": 16})),
+		"Rock/Led Zeppelin/IV/02 - Black Dog.flac": ledZepIV(track(2, "Black Dog",
+			_t{"genre": "Rock;Blues", "composer": "Page/Plant/Jones", "bpm": 150, "suffix": "flac",
+				"bitrate": 900, "samplerate": 44100, "bitdepth": 16})),
+		"Jazz/Miles Davis/Kind of Blue/01 - So What.mp3": kindOfBlue(track(1, "So What",
+			_t{"bpm": 136})),
+		"Rock/Queen/A Night at the Opera/01 - Bohemian Rhapsody.mp3": nightAtOpera(track(1, "Bohemian Rhapsody",
+			_t{"composer": "Freddie Mercury", "bpm": 72})),
+		"Rock/Jimi Hendrix/Electric Ladyland/01 - All Along the Watchtower.mp3": electricLadyland(track(1, "All Along the Watchtower",
+			_t{"composer": "Bob Dylan", "bpm": 112})),
+		"Rock/Queen/News of the World/01 - We Are the Champions.mp3": newsOfWorld(track(1, "We Are the Champions",
+			_t{"composer": "Freddie Mercury", "bpm": 64})),
+	})
+	storagetest.Register("fake", &fs)
+}
+
+func findMediaFileByTitle(title string) string {
+	mfs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+		Filters: squirrel.Eq{"media_file.title": title},
+	})
+	Expect(err).ToNot(HaveOccurred())
+	Expect(mfs).To(HaveLen(1), "expected exactly one media file with title %q", title)
+	return mfs[0].ID
+}
+
+func evaluateRule(jsonRule string) []string {
+	titles := evaluateRuleOrderedAs(adminUser, jsonRule)
+	sort.Strings(titles)
+	return titles
+}
+
+func evaluateRuleOrdered(jsonRule string) []string {
+	return evaluateRuleOrderedAs(adminUser, jsonRule)
+}
+
+func evaluateRuleAs(owner model.User, jsonRule string) []string {
+	titles := evaluateRuleOrderedAs(owner, jsonRule)
+	sort.Strings(titles)
+	return titles
+}
+
+func evaluateRuleOrderedAs(owner model.User, jsonRule string) []string {
+	userCtx := request.WithUser(GinkgoT().Context(), owner)
+	var rules criteria.Criteria
+	err := json.Unmarshal([]byte(jsonRule), &rules)
+	Expect(err).ToNot(HaveOccurred(), "invalid criteria JSON: %s", jsonRule)
+
+	pls := &model.Playlist{
+		Name:    "test-smart-playlist",
+		OwnerID: owner.ID,
+		Rules:   &rules,
+	}
+	err = ds.Playlist(userCtx).Put(pls)
+	Expect(err).ToNot(HaveOccurred())
+
+	loaded, err := ds.Playlist(userCtx).GetWithTracks(pls.ID, true, false)
+	Expect(err).ToNot(HaveOccurred())
+
+	titles := make([]string, len(loaded.Tracks))
+	for i, t := range loaded.Tracks {
+		titles[i] = t.Title
+	}
+	return titles
+}
+
+func createPlaylist(owner model.User, public bool, titles ...string) string {
+	pls := &model.Playlist{
+		Name:    "ref-playlist",
+		OwnerID: owner.ID,
+		Public:  public,
+	}
+	for _, title := range titles {
+		mfID := findMediaFileByTitle(title)
+		pls.AddMediaFilesByID([]string{mfID})
+	}
+	Expect(ds.Playlist(ctx).Put(pls)).To(Succeed())
+	return pls.ID
+}
+
+func createPublicPlaylist(owner model.User, titles ...string) string {
+	return createPlaylist(owner, true, titles...)
+}
+
+func createPrivatePlaylist(owner model.User, titles ...string) string {
+	return createPlaylist(owner, false, titles...)
+}
+
+func createPublicSmartPlaylist(owner model.User, jsonRule string) string {
+	return createSmartPlaylist(owner, true, jsonRule)
+}
+
+func createPrivateSmartPlaylist(owner model.User, jsonRule string) string {
+	return createSmartPlaylist(owner, false, jsonRule)
+}
+
+func createSmartPlaylist(owner model.User, public bool, jsonRule string) string {
+	var rules criteria.Criteria
+	Expect(json.Unmarshal([]byte(jsonRule), &rules)).To(Succeed())
+	pls := &model.Playlist{
+		Name:    "ref-smart-playlist",
+		OwnerID: owner.ID,
+		Public:  public,
+		Rules:   &rules,
+	}
+	Expect(ds.Playlist(ctx).Put(pls)).To(Succeed())
+	return pls.ID
+}
+
+var _ = BeforeSuite(func() {
+	ctx = request.WithUser(GinkgoT().Context(), adminUser)
+	tmpDir := GinkgoT().TempDir()
+	dbFilePath = filepath.Join(tmpDir, "smartplaylist-e2e.db")
+	snapshotPath = filepath.Join(tmpDir, "smartplaylist-e2e.db.snapshot")
+	conf.Server.DbPath = dbFilePath + "?_journal_mode=WAL"
+	db.Db().SetMaxOpenConns(1)
+
+	conf.Server.MusicFolder = "fake:///music"
+	conf.Server.DevExternalScanner = false
+	conf.Server.SmartPlaylistRefreshDelay = 0
+
+	db.Init(ctx)
+
+	initDS := &tests.MockDataStore{RealDS: persistence.New(db.Db())}
+
+	userWithPass := adminUser
+	userWithPass.NewPassword = "password"
+	Expect(initDS.User(ctx).Put(&userWithPass)).To(Succeed())
+
+	regularUserWithPass := regularUser
+	regularUserWithPass.NewPassword = "password"
+	Expect(initDS.User(ctx).Put(&regularUserWithPass)).To(Succeed())
+
+	lib = model.Library{ID: 1, Name: "Music Library", Path: "fake:///music"}
+	Expect(initDS.Library(ctx).Put(&lib)).To(Succeed())
+	Expect(initDS.User(ctx).SetUserLibraries(adminUser.ID, []int{lib.ID})).To(Succeed())
+	Expect(initDS.User(ctx).SetUserLibraries(regularUser.ID, []int{lib.ID})).To(Succeed())
+
+	loadedUser, err := initDS.User(ctx).FindByUsername(adminUser.UserName)
+	Expect(err).ToNot(HaveOccurred())
+	adminUser.Libraries = loadedUser.Libraries
+
+	loadedOther, err := initDS.User(ctx).FindByUsername(regularUser.UserName)
+	Expect(err).ToNot(HaveOccurred())
+	regularUser.Libraries = loadedOther.Libraries
+
+	ctx = request.WithUser(GinkgoT().Context(), adminUser)
+
+	buildTestFS()
+	s := scanner.New(ctx, initDS, artwork.NoopCacheWarmer(), events.NoopBroker(),
+		playlists.NewPlaylists(initDS, core.NewImageUploadService()), metrics.NewNoopInstance())
+	_, err = s.ScanAll(ctx, true)
+	Expect(err).ToNot(HaveOccurred())
+
+	ds = &tests.MockDataStore{RealDS: persistence.New(db.Db())}
+
+	comeTogetherID := findMediaFileByTitle("Come Together")
+	Expect(ds.MediaFile(ctx).SetStar(true, comeTogetherID)).To(Succeed())
+	Expect(ds.MediaFile(ctx).SetStar(true, findMediaFileByTitle("So What"))).To(Succeed())
+	Expect(ds.MediaFile(ctx).SetRating(3, findMediaFileByTitle("Stairway To Heaven"))).To(Succeed())
+	Expect(ds.MediaFile(ctx).SetRating(5, findMediaFileByTitle("Bohemian Rhapsody"))).To(Succeed())
+	for range 10 {
+		Expect(ds.MediaFile(ctx).IncPlayCount(comeTogetherID, time.Now())).To(Succeed())
+	}
+	Expect(ds.MediaFile(ctx).IncPlayCount(findMediaFileByTitle("Black Dog"), time.Now())).To(Succeed())
+
+	rows, err := db.Db().Query("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '%_fts' AND name NOT LIKE '%_fts_%'")
+	Expect(err).ToNot(HaveOccurred())
+	defer rows.Close()
+	for rows.Next() {
+		var name string
+		Expect(rows.Scan(&name)).To(Succeed())
+		snapshotTables = append(snapshotTables, name)
+	}
+	Expect(rows.Err()).ToNot(HaveOccurred())
+
+	_, err = db.Db().Exec("PRAGMA wal_checkpoint(TRUNCATE)")
+	Expect(err).ToNot(HaveOccurred())
+	data, err := os.ReadFile(dbFilePath)
+	Expect(err).ToNot(HaveOccurred())
+	Expect(os.WriteFile(snapshotPath, data, 0600)).To(Succeed())
+})
+
+var _ = AfterSuite(func() {
+	db.Close(ctx)
+})
+
+func restoreDB() {
+	sqlDB := db.Db()
+
+	_, err := sqlDB.Exec("PRAGMA foreign_keys = OFF")
+	Expect(err).ToNot(HaveOccurred())
+	defer func() { _, _ = sqlDB.Exec("PRAGMA foreign_keys = ON") }()
+
+	_, err = sqlDB.Exec("ATTACH DATABASE ? AS snapshot", snapshotPath)
+	Expect(err).ToNot(HaveOccurred())
+	defer func() { _, _ = sqlDB.Exec("DETACH DATABASE snapshot") }()
+
+	_, err = sqlDB.Exec("BEGIN TRANSACTION")
+	Expect(err).ToNot(HaveOccurred())
+	defer func() { _, _ = sqlDB.Exec("ROLLBACK") }()
+
+	for _, table := range snapshotTables {
+		_, err = sqlDB.Exec(`DELETE FROM main."` + table + `"`) //nolint:gosec
+		Expect(err).ToNot(HaveOccurred())
+		_, err = sqlDB.Exec(`INSERT INTO main."` + table + `" SELECT * FROM snapshot."` + table + `"`) //nolint:gosec
+		Expect(err).ToNot(HaveOccurred())
+	}
+
+	_, err = sqlDB.Exec("COMMIT")
+	Expect(err).ToNot(HaveOccurred())
+}
+
+func setupTestDB() {
+	ctx = request.WithUser(GinkgoT().Context(), adminUser)
+	DeferCleanup(configtest.SetupConfig())
+	conf.Server.MusicFolder = "fake:///music"
+	conf.Server.DevExternalScanner = false
+	conf.Server.SmartPlaylistRefreshDelay = 0
+
+	restoreDB()
+	ds = &tests.MockDataStore{RealDS: persistence.New(db.Db())}
+}

persistence/e2e/smartplaylist_test.go

@@ -0,0 +1,333 @@
+package e2e
+
+import (
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"github.com/sirupsen/logrus"
+)
+
+var _ = Describe("Smart Playlists", func() {
+	BeforeEach(func() {
+		setupTestDB()
+	})
+
+	Describe("String fields", func() {
+		It("matches by exact title", func() {
+			results := evaluateRule(`{"all":[{"is":{"title":"Something"}}]}`)
+			Expect(results).To(ConsistOf("Something"))
+		})
+
+		It("matches by title contains", func() {
+			results := evaluateRule(`{"all":[{"contains":{"title":"the"}}]}`)
+			Expect(results).To(ConsistOf("Come Together", "All Along the Watchtower", "We Are the Champions"))
+		})
+
+		It("matches by artist startsWith", func() {
+			results := evaluateRule(`{"all":[{"startsWith":{"artist":"Led"}}]}`)
+			Expect(results).To(ConsistOf("Stairway To Heaven", "Black Dog"))
+		})
+
+		It("matches by title isNot", func() {
+			results := evaluateRule(`{"all":[{"isNot":{"title":"Something"}},{"is":{"artist":"The Beatles"}}]}`)
+			Expect(results).To(ConsistOf("Come Together"))
+		})
+
+		It("matches by artist endsWith", func() {
+			results := evaluateRule(`{"all":[{"endsWith":{"artist":"Davis"}}]}`)
+			Expect(results).To(ConsistOf("So What"))
+		})
+	})
+
+	Describe("Numeric fields", func() {
+		It("matches by year greater than", func() {
+			results := evaluateRule(`{"all":[{"gt":{"year":1970}}]}`)
+			Expect(results).To(ConsistOf("Stairway To Heaven", "Black Dog", "Bohemian Rhapsody", "We Are the Champions"))
+		})
+
+		It("matches by year less than", func() {
+			results := evaluateRule(`{"all":[{"lt":{"year":1969}}]}`)
+			Expect(results).To(ConsistOf("So What", "All Along the Watchtower"))
+		})
+
+		It("matches by BPM in range", func() {
+			results := evaluateRule(`{"all":[{"inTheRange":{"bpm":[100,130]}}]}`)
+			Expect(results).To(ConsistOf("Come Together", "Something", "All Along the Watchtower"))
+		})
+	})
+
+	Describe("Boolean fields", func() {
+		It("matches compilations", func() {
+			results := evaluateRule(`{"all":[{"is":{"compilation":true}}]}`)
+			Expect(results).To(ConsistOf("We Are the Champions"))
+		})
+
+		It("matches non-compilations", func() {
+			results := evaluateRule(`{"all":[{"is":{"compilation":false}}]}`)
+			Expect(results).To(ConsistOf("Come Together", "Something", "Stairway To Heaven", "Black Dog", "So What", "Bohemian Rhapsody", "All Along the Watchtower"))
+		})
+	})
+
+	Describe("File type fields", func() {
+		It("matches by filetype", func() {
+			results := evaluateRule(`{"all":[{"is":{"filetype":"flac"}}]}`)
+			Expect(results).To(ConsistOf("Stairway To Heaven", "Black Dog"))
+		})
+	})
+
+	Describe("Multi-valued tags", func() {
+		It("matches tracks with Blues genre", func() {
+			results := evaluateRule(`{"all":[{"is":{"genre":"Blues"}}]}`)
+			Expect(results).To(ConsistOf("Come Together", "Black Dog", "All Along the Watchtower"))
+		})
+
+		It("excludes tracks with Rock genre", func() {
+			results := evaluateRule(`{"all":[{"isNot":{"genre":"Rock"}}]}`)
+			Expect(results).To(ConsistOf("So What"))
+		})
+
+		It("matches genre contains", func() {
+			results := evaluateRule(`{"all":[{"contains":{"genre":"ol"}}]}`)
+			Expect(results).To(ConsistOf("Stairway To Heaven"))
+		})
+
+		It("matches tracks with Pop genre", func() {
+			results := evaluateRule(`{"all":[{"is":{"genre":"Pop"}}]}`)
+			Expect(results).To(ConsistOf("We Are the Champions"))
+		})
+
+		It("matches genre startsWith", func() {
+			results := evaluateRule(`{"all":[{"startsWith":{"genre":"Ro"}}]}`)
+			Expect(results).To(ConsistOf("Come Together", "Something", "Stairway To Heaven", "Black Dog",
+				"Bohemian Rhapsody", "All Along the Watchtower", "We Are the Champions"))
+		})
+	})
+
+	Describe("Participants", func() {
+		It("matches by exact composer", func() {
+			results := evaluateRule(`{"all":[{"is":{"composer":"Harrison"}}]}`)
+			Expect(results).To(ConsistOf("Something"))
+		})
+
+		It("matches by composer contains", func() {
+			results := evaluateRule(`{"all":[{"contains":{"composer":"Plant"}}]}`)
+			Expect(results).To(ConsistOf("Stairway To Heaven", "Black Dog"))
+		})
+
+		It("matches by composer isNot", func() {
+			results := evaluateRule(`{"all":[{"isNot":{"composer":"Freddie Mercury"}}]}`)
+			Expect(results).To(ConsistOf("Come Together", "Something", "Stairway To Heaven", "Black Dog", "So What", "All Along the Watchtower"))
+		})
+
+		It("matches by composer endsWith", func() {
+			results := evaluateRule(`{"all":[{"endsWith":{"composer":"Mercury"}}]}`)
+			Expect(results).To(ConsistOf("Bohemian Rhapsody", "We Are the Champions"))
+		})
+	})
+
+	Describe("Annotations", func() {
+		It("matches starred tracks", func() {
+			results := evaluateRule(`{"all":[{"is":{"loved":true}}]}`)
+			Expect(results).To(ConsistOf("Come Together", "So What"))
+		})
+
+		It("matches unstarred tracks", func() {
+			results := evaluateRule(`{"all":[{"is":{"loved":false}}]}`)
+			Expect(results).To(ConsistOf("Something", "Stairway To Heaven", "Black Dog", "Bohemian Rhapsody", "All Along the Watchtower", "We Are the Champions"))
+		})
+
+		It("matches by rating greater than", func() {
+			results := evaluateRule(`{"all":[{"gt":{"rating":3}}]}`)
+			Expect(results).To(ConsistOf("Bohemian Rhapsody"))
+		})
+
+		It("matches by rating greater than or equal via inTheRange", func() {
+			results := evaluateRule(`{"all":[{"inTheRange":{"rating":[3,5]}}]}`)
+			Expect(results).To(ConsistOf("Stairway To Heaven", "Bohemian Rhapsody"))
+		})
+
+		It("matches by play count greater than", func() {
+			results := evaluateRule(`{"all":[{"gt":{"playcount":5}}]}`)
+			Expect(results).To(ConsistOf("Come Together"))
+		})
+
+		It("matches by play count greater than zero", func() {
+			results := evaluateRule(`{"all":[{"gt":{"playcount":0}}]}`)
+			Expect(results).To(ConsistOf("Come Together", "Black Dog"))
+		})
+	})
+
+	Describe("Negated string operators", func() {
+		It("matches by title notContains", func() {
+			results := evaluateRule(`{"all":[{"notContains":{"title":"the"}}]}`)
+			Expect(results).To(ConsistOf("Something", "Stairway To Heaven", "Black Dog", "So What", "Bohemian Rhapsody"))
+		})
+	})
+
+	Describe("Date/time fields", func() {
+		It("matches dateAdded before a far-future date", func() {
+			results := evaluateRule(`{"all":[{"before":{"dateadded":"2099-01-01"}}]}`)
+			Expect(results).To(ConsistOf("Come Together", "Something", "Stairway To Heaven", "Black Dog",
+				"So What", "Bohemian Rhapsody", "All Along the Watchtower", "We Are the Champions"))
+		})
+
+		It("matches lastPlayed inTheLast 1 day", func() {
+			results := evaluateRule(`{"all":[{"inTheLast":{"lastplayed":1}}]}`)
+			Expect(results).To(ConsistOf("Come Together", "Black Dog"))
+		})
+
+		It("matches lastPlayed notInTheLast (far future)", func() {
+			results := evaluateRule(`{"all":[{"notInTheLast":{"lastplayed":99999}}]}`)
+			Expect(results).To(ConsistOf("Something", "Stairway To Heaven", "So What",
+				"Bohemian Rhapsody", "All Along the Watchtower", "We Are the Champions"))
+		})
+
+		It("matches dateLoved after a past date", func() {
+			results := evaluateRule(`{"all":[{"after":{"dateloved":"2020-01-01"}}]}`)
+			Expect(results).To(ConsistOf("Come Together", "So What"))
+		})
+
+		It("matches dateRated after a past date", func() {
+			results := evaluateRule(`{"all":[{"after":{"daterated":"2020-01-01"}}]}`)
+			Expect(results).To(ConsistOf("Stairway To Heaven", "Bohemian Rhapsody"))
+		})
+
+		It("matches dateAdded inTheLast 1 day", func() {
+			results := evaluateRule(`{"all":[{"inTheLast":{"dateadded":1}}]}`)
+			Expect(results).To(ConsistOf("Come Together", "Something", "Stairway To Heaven", "Black Dog",
+				"So What", "Bohemian Rhapsody", "All Along the Watchtower", "We Are the Champions"))
+		})
+
+		It("resolves recordingdate alias to the date column", func() {
+			results := evaluateRule(`{"all":[{"is":{"recordingdate":"1959"}}]}`)
+			Expect(results).To(ConsistOf("So What"))
+		})
+	})
+
+	Describe("Logic operators", func() {
+		It("matches with ALL (AND)", func() {
+			results := evaluateRule(`{"all":[{"is":{"genre":"Blues"}},{"gt":{"bpm":130}}]}`)
+			Expect(results).To(ConsistOf("Black Dog"))
+		})
+
+		It("matches with ANY (OR)", func() {
+			results := evaluateRule(`{"any":[{"is":{"genre":"Jazz"}},{"is":{"compilation":true}}]}`)
+			Expect(results).To(ConsistOf("So What", "We Are the Champions"))
+		})
+
+		It("matches nested all/any", func() {
+			results := evaluateRule(`{"all":[{"any":[{"is":{"genre":"Blues"}},{"is":{"genre":"Jazz"}}]},{"gt":{"year":1960}}]}`)
+			Expect(results).To(ConsistOf("Come Together", "Black Dog", "All Along the Watchtower"))
+		})
+	})
+
+	Describe("Sorting and limits", func() {
+		It("returns tracks sorted by year descending with limit", func() {
+			results := evaluateRuleOrdered(`{"all":[{"gt":{"year":0}}],"sort":"year","order":"desc","limit":2}`)
+			Expect(results).To(Equal([]string{"We Are the Champions", "Bohemian Rhapsody"}))
+		})
+
+		It("returns tracks sorted by title ascending", func() {
+			results := evaluateRuleOrdered(`{"all":[{"is":{"genre":"Blues"}}],"sort":"title","order":"asc"}`)
+			Expect(results).To(Equal([]string{"All Along the Watchtower", "Black Dog", "Come Together"}))
+		})
+	})
+
+	Describe("Combined real-world patterns", func() {
+		It("matches genre filter with exclusion and year range", func() {
+			results := evaluateRuleOrdered(`{
+				"all":[
+					{"any":[
+						{"is":{"genre":"Blues"}},
+						{"is":{"genre":"Folk"}}
+					]},
+					{"isNot":{"genre":"Jazz"}},
+					{"gt":{"year":1965}}
+				],
+				"sort":"-year,title"
+			}`)
+			Expect(results).To(Equal([]string{"Black Dog", "Stairway To Heaven", "Come Together", "All Along the Watchtower"}))
+		})
+	})
+
+	Describe("Playlist operators", func() {
+		It("matches tracks in a public regular playlist", func() {
+			refID := createPublicPlaylist(adminUser, "Come Together", "So What")
+			results := evaluateRuleAs(regularUser, `{"all":[{"inPlaylist":{"id":"`+refID+`"}}]}`)
+			Expect(results).To(ConsistOf("Come Together", "So What"))
+		})
+
+		It("matches tracks not in a public regular playlist", func() {
+			refID := createPublicPlaylist(adminUser, "Come Together", "So What")
+			results := evaluateRuleAs(regularUser, `{"all":[{"notInPlaylist":{"id":"`+refID+`"}}]}`)
+			Expect(results).To(ConsistOf("Something", "Stairway To Heaven", "Black Dog",
+				"Bohemian Rhapsody", "All Along the Watchtower", "We Are the Champions"))
+		})
+
+		It("recursively refreshes a referenced smart playlist owned by the same user", func() {
+			smartBID := createPublicSmartPlaylist(adminUser, `{"all":[{"is":{"genre":"Jazz"}}]}`)
+			results := evaluateRuleAs(adminUser, `{"all":[{"inPlaylist":{"id":"`+smartBID+`"}}]}`)
+			Expect(results).To(ConsistOf("So What"))
+		})
+
+		It("does not refresh a referenced smart playlist owned by another user", func() {
+			smartBID := createPublicSmartPlaylist(regularUser, `{"all":[{"is":{"genre":"Jazz"}}]}`)
+			results := evaluateRuleAs(adminUser, `{"all":[{"inPlaylist":{"id":"`+smartBID+`"}}]}`)
+			Expect(results).To(BeEmpty())
+		})
+
+		It("does not refresh a playlist or its children when an admin views another user's smart playlist", func() {
+			smartBID := createPrivateSmartPlaylist(adminUser, `{"all":[{"is":{"genre":"Jazz"}}]}`)
+			smartAID := createPublicSmartPlaylist(regularUser, `{"all":[{"inPlaylist":{"id":"`+smartBID+`"}}]}`)
+
+			loadedA, err := ds.Playlist(ctx).GetWithTracks(smartAID, true, false)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(loadedA.Tracks).To(BeEmpty())
+			Expect(loadedA.EvaluatedAt).To(BeNil())
+
+			loadedB, err := ds.Playlist(ctx).Get(smartBID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(loadedB.EvaluatedAt).To(BeNil())
+		})
+
+		It("matches tracks from a private playlist owned by the same user", func() {
+			refID := createPrivatePlaylist(regularUser, "Come Together", "So What")
+			results := evaluateRuleAs(regularUser, `{"all":[{"inPlaylist":{"id":"`+refID+`"}}]}`)
+			Expect(results).To(ConsistOf("Come Together", "So What"))
+		})
+
+		It("allows admin-owned smart playlists to reference private playlists owned by other users", func() {
+			refID := createPrivatePlaylist(regularUser, "Bohemian Rhapsody")
+			results := evaluateRuleAs(adminUser, `{"all":[{"inPlaylist":{"id":"`+refID+`"}}]}`)
+			Expect(results).To(ConsistOf("Bohemian Rhapsody"))
+		})
+
+		It("does not match tracks from a private playlist owned by another regular user", func() {
+			refID := createPrivatePlaylist(adminUser, "Come Together", "So What")
+			results := evaluateRuleAs(regularUser, `{"all":[{"inPlaylist":{"id":"`+refID+`"}}]}`)
+			Expect(results).To(BeEmpty())
+		})
+
+		It("warns when a referenced playlist is inaccessible to the smart playlist owner", func() {
+			hook, cleanup := tests.LogHook()
+			defer cleanup()
+
+			refID := createPrivatePlaylist(adminUser, "Come Together")
+			results := evaluateRuleAs(regularUser, `{"all":[{"notInPlaylist":{"id":"`+refID+`"}}]}`)
+			Expect(results).To(ConsistOf("Come Together", "Something", "Stairway To Heaven", "Black Dog",
+				"So What", "Bohemian Rhapsody", "All Along the Watchtower", "We Are the Champions"))
+
+			Expect(hook.LastEntry()).ToNot(BeNil())
+			Expect(hook.LastEntry().Level).To(Equal(logrus.WarnLevel))
+			Expect(hook.LastEntry().Message).To(Equal("Referenced playlist is not accessible to smart playlist owner"))
+			Expect(hook.LastEntry().Data).To(HaveKeyWithValue("childId", refID))
+		})
+
+		It("matches tracks in a public playlist owned by another user", func() {
+			refID := createPublicPlaylist(adminUser, "Bohemian Rhapsody")
+			results := evaluateRuleAs(regularUser, `{"all":[{"inPlaylist":{"id":"`+refID+`"}}]}`)
+			Expect(results).To(ConsistOf("Bohemian Rhapsody"))
+		})
+
+	})
+})

persistence/folder_repository_test.go

@@ -8,6 +8,7 @@ import (
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 	"github.com/pocketbase/dbx"
@@ -99,6 +100,7 @@ var _ = Describe("FolderRepository", func() {
 			})
 
 			It("includes all child folders when querying parent", func() {
+				tests.SkipOnWindows("path storage (#TBD-path-sep-persistence)")
 				// Create a parent folder with multiple children
 				parent := model.NewFolder(testLib, "TestParent/Music")
 				child1 := model.NewFolder(testLib, "TestParent/Music/Rock/Queen")
@@ -120,6 +122,7 @@ var _ = Describe("FolderRepository", func() {
 			})
 
 			It("excludes children from other libraries", func() {
+				tests.SkipOnWindows("path storage (#TBD-path-sep-persistence)")
 				// Create parent in testLib
 				parent := model.NewFolder(testLib, "TestIsolation/Parent")
 				child := model.NewFolder(testLib, "TestIsolation/Parent/Child")
@@ -145,6 +148,7 @@ var _ = Describe("FolderRepository", func() {
 			})
 
 			It("excludes missing children when querying parent", func() {
+				tests.SkipOnWindows("path storage (#TBD-path-sep-persistence)")
 				// Create parent and children, mark one as missing
 				parent := model.NewFolder(testLib, "TestMissingChild/Parent")
 				child1 := model.NewFolder(testLib, "TestMissingChild/Parent/Child1")
@@ -165,6 +169,7 @@ var _ = Describe("FolderRepository", func() {
 			})
 
 			It("handles mix of existing and non-existing target paths", func() {
+				tests.SkipOnWindows("path storage (#TBD-path-sep-persistence)")
 				// Create folders for one path but not the other
 				existingParent := model.NewFolder(testLib, "TestMixed/Exists")
 				existingChild := model.NewFolder(testLib, "TestMixed/Exists/Child")

persistence/library_repository_test.go

@@ -2,6 +2,7 @@ package persistence
 
 import (
 	"context"
+	"time"
 
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
@@ -64,6 +65,11 @@ var _ = Describe("LibraryRepository", func() {
 				originalID := lib.ID
 				originalCreatedAt := lib.CreatedAt
 
+				// Ensure the update's timestamp is strictly greater than the
+				// create's timestamp on platforms with coarse clock resolution
+				// (Windows' time.Now() is millisecond-granular).
+				time.Sleep(2 * time.Millisecond)
+
 				// Now update it
 				lib.Name = "Updated Library"
 				lib.Path = "/music/updated"

persistence/mediafile_repository_test.go

@@ -48,10 +48,10 @@ var _ = Describe("MediaRepository", func() {
 		var mp3File, flacFile1, flacFile2, flacUpperFile model.MediaFile
 
 		BeforeEach(func() {
-			mp3File = model.MediaFile{ID: "suffix-mp3", LibraryID: 1, Suffix: "mp3", Path: "/test/file.mp3"}
-			flacFile1 = model.MediaFile{ID: "suffix-flac1", LibraryID: 1, Suffix: "flac", Path: "/test/file1.flac"}
-			flacFile2 = model.MediaFile{ID: "suffix-flac2", LibraryID: 1, Suffix: "flac", Path: "/test/file2.flac"}
-			flacUpperFile = model.MediaFile{ID: "suffix-FLAC", LibraryID: 1, Suffix: "FLAC", Path: "/test/file.FLAC"}
+			mp3File = model.MediaFile{ID: "suffix-mp3", LibraryID: 1, Suffix: "mp3", Path: "test/file.mp3"}
+			flacFile1 = model.MediaFile{ID: "suffix-flac1", LibraryID: 1, Suffix: "flac", Path: "test/file1.flac"}
+			flacFile2 = model.MediaFile{ID: "suffix-flac2", LibraryID: 1, Suffix: "flac", Path: "test/file2.flac"}
+			flacUpperFile = model.MediaFile{ID: "suffix-FLAC", LibraryID: 1, Suffix: "FLAC", Path: "test/file.FLAC"}
 
 			Expect(mr.Put(&mp3File)).To(Succeed())
 			Expect(mr.Put(&flacFile1)).To(Succeed())
@@ -109,7 +109,7 @@ var _ = Describe("MediaRepository", func() {
 	Describe("Put CreatedAt behavior (#5050)", func() {
 		It("sets CreatedAt to now when inserting a new file with zero CreatedAt", func() {
 			before := time.Now().Add(-time.Second)
-			newFile := model.MediaFile{ID: id.NewRandom(), LibraryID: 1, Path: "/test/created-at-zero.mp3"}
+			newFile := model.MediaFile{ID: id.NewRandom(), LibraryID: 1, Path: "test/created-at-zero.mp3"}
 			Expect(mr.Put(&newFile)).To(Succeed())
 
 			retrieved, err := mr.Get(newFile.ID)
@@ -124,7 +124,7 @@ var _ = Describe("MediaRepository", func() {
 			newFile := model.MediaFile{
 				ID:        id.NewRandom(),
 				LibraryID: 1,
-				Path:      "/test/created-at-preserved.mp3",
+				Path:      "test/created-at-preserved.mp3",
 				CreatedAt: originalTime,
 			}
 			Expect(mr.Put(&newFile)).To(Succeed())
@@ -142,7 +142,7 @@ var _ = Describe("MediaRepository", func() {
 			newFile := model.MediaFile{
 				ID:        fileID,
 				LibraryID: 1,
-				Path:      "/test/created-at-update.mp3",
+				Path:      "test/created-at-update.mp3",
 				Title:     "Original Title",
 				CreatedAt: originalTime,
 			}
@@ -152,7 +152,7 @@ var _ = Describe("MediaRepository", func() {
 			updatedFile := model.MediaFile{
 				ID:        fileID,
 				LibraryID: 1,
-				Path:      "/test/created-at-update.mp3",
+				Path:      "test/created-at-update.mp3",
 				Title:     "Updated Title",
 				// CreatedAt is zero - should NOT overwrite the stored value
 			}
@@ -231,7 +231,7 @@ var _ = Describe("MediaRepository", func() {
 
 			It("returns 0 when no ratings exist", func() {
 				newID := id.NewRandom()
-				Expect(mr.Put(&model.MediaFile{LibraryID: 1, ID: newID, Path: "/test/no-rating.mp3"})).To(Succeed())
+				Expect(mr.Put(&model.MediaFile{LibraryID: 1, ID: newID, Path: "test/no-rating.mp3"})).To(Succeed())
 
 				mf, err := mr.Get(newID)
 				Expect(err).ToNot(HaveOccurred())
@@ -242,7 +242,7 @@ var _ = Describe("MediaRepository", func() {
 
 			It("returns the user's rating as average when only one user rated", func() {
 				newID := id.NewRandom()
-				Expect(mr.Put(&model.MediaFile{LibraryID: 1, ID: newID, Path: "/test/single-rating.mp3"})).To(Succeed())
+				Expect(mr.Put(&model.MediaFile{LibraryID: 1, ID: newID, Path: "test/single-rating.mp3"})).To(Succeed())
 				Expect(mr.SetRating(5, newID)).To(Succeed())
 
 				mf, err := mr.Get(newID)
@@ -255,7 +255,7 @@ var _ = Describe("MediaRepository", func() {
 
 			It("calculates average across multiple users", func() {
 				newID := id.NewRandom()
-				Expect(mr.Put(&model.MediaFile{LibraryID: 1, ID: newID, Path: "/test/multi-rating.mp3"})).To(Succeed())
+				Expect(mr.Put(&model.MediaFile{LibraryID: 1, ID: newID, Path: "test/multi-rating.mp3"})).To(Succeed())
 
 				Expect(mr.SetRating(3, newID)).To(Succeed())
 
@@ -273,7 +273,7 @@ var _ = Describe("MediaRepository", func() {
 
 			It("excludes zero ratings from average calculation", func() {
 				newID := id.NewRandom()
-				Expect(mr.Put(&model.MediaFile{LibraryID: 1, ID: newID, Path: "/test/zero-excluded.mp3"})).To(Succeed())
+				Expect(mr.Put(&model.MediaFile{LibraryID: 1, ID: newID, Path: "test/zero-excluded.mp3"})).To(Succeed())
 
 				Expect(mr.SetRating(4, newID)).To(Succeed())
 
@@ -343,19 +343,19 @@ var _ = Describe("MediaRepository", func() {
 						ID:        id.NewRandom(),
 						LibraryID: 1,
 						Title:     "Old Song",
-						Path:      "/test/old.mp3",
+						Path:      "test/old.mp3",
 					},
 					{
 						ID:        id.NewRandom(),
 						LibraryID: 1,
 						Title:     "Middle Song",
-						Path:      "/test/middle.mp3",
+						Path:      "test/middle.mp3",
 					},
 					{
 						ID:        id.NewRandom(),
 						LibraryID: 1,
 						Title:     "New Song",
-						Path:      "/test/new.mp3",
+						Path:      "test/new.mp3",
 					},
 				}
 
@@ -486,7 +486,7 @@ var _ = Describe("MediaRepository", func() {
 		var mfWithoutAnnotation model.MediaFile
 
 		BeforeEach(func() {
-			mfWithoutAnnotation = model.MediaFile{ID: "no-annotation-file", LibraryID: 1, Path: "/test/no-annotation.mp3", Title: "No Annotation"}
+			mfWithoutAnnotation = model.MediaFile{ID: "no-annotation-file", LibraryID: 1, Path: "test/no-annotation.mp3", Title: "No Annotation"}
 			Expect(mr.Put(&mfWithoutAnnotation)).To(Succeed())
 		})
 
@@ -566,7 +566,7 @@ var _ = Describe("MediaRepository", func() {
 					MbzRecordingID:    "550e8400-e29b-41d4-a716-446655440020", // Valid UUID v4
 					MbzReleaseTrackID: "550e8400-e29b-41d4-a716-446655440021", // Valid UUID v4
 					LibraryID:         1,
-					Path:              "/test/path/test.mp3",
+					Path:              "test/path/test.mp3",
 				}
 
 				// Insert the test media file into the database
@@ -608,7 +608,7 @@ var _ = Describe("MediaRepository", func() {
 					Title:          "Test Missing MBID MediaFile",
 					MbzRecordingID: "550e8400-e29b-41d4-a716-446655440022",
 					LibraryID:      1,
-					Path:           "/test/path/missing.mp3",
+					Path:           "test/path/missing.mp3",
 					Missing:        true,
 				}
 

persistence/persistence_suite_test.go

@@ -77,14 +77,14 @@ var (
 )
 
 var (
-	albumSgtPeppers    = al(model.Album{ID: "101", Name: "Sgt Peppers", AlbumArtist: "The Beatles", OrderAlbumName: "sgt peppers", AlbumArtistID: "3", EmbedArtPath: p("/beatles/1/sgt/a day.mp3"), SongCount: 1, MaxYear: 1967})
-	albumAbbeyRoad     = al(model.Album{ID: "102", Name: "Abbey Road", AlbumArtist: "The Beatles", OrderAlbumName: "abbey road", AlbumArtistID: "3", EmbedArtPath: p("/beatles/1/come together.mp3"), SongCount: 1, MaxYear: 1969})
-	albumRadioactivity = al(model.Album{ID: "103", Name: "Radioactivity", AlbumArtist: "Kraftwerk", OrderAlbumName: "radioactivity", AlbumArtistID: "2", EmbedArtPath: p("/kraft/radio/radio.mp3"), SongCount: 2})
-	albumMultiDisc     = al(model.Album{ID: "104", Name: "Multi Disc Album", AlbumArtist: "Test Artist", OrderAlbumName: "multi disc album", AlbumArtistID: "1", EmbedArtPath: p("/test/multi/disc1/track1.mp3"), SongCount: 4})
-	albumCJK           = al(model.Album{ID: "105", Name: "COWBOY BEBOP", AlbumArtist: "シートベルツ", OrderAlbumName: "cowboy bebop", AlbumArtistID: "4", EmbedArtPath: p("/seatbelts/cowboy-bebop/track1.mp3"), SongCount: 1})
-	albumWithVersion   = alWithTags(model.Album{ID: "106", Name: "Abbey Road", AlbumArtist: "The Beatles", OrderAlbumName: "abbey road", AlbumArtistID: "3", EmbedArtPath: p("/beatles/2/come together.mp3"), SongCount: 1, MaxYear: 2019},
+	albumSgtPeppers    = al(model.Album{ID: "101", Name: "Sgt Peppers", AlbumArtist: "The Beatles", OrderAlbumName: "sgt peppers", AlbumArtistID: "3", EmbedArtPath: p("beatles/1/sgt/a day.mp3"), SongCount: 1, MaxYear: 1967})
+	albumAbbeyRoad     = al(model.Album{ID: "102", Name: "Abbey Road", AlbumArtist: "The Beatles", OrderAlbumName: "abbey road", AlbumArtistID: "3", EmbedArtPath: p("beatles/1/come together.mp3"), SongCount: 1, MaxYear: 1969})
+	albumRadioactivity = al(model.Album{ID: "103", Name: "Radioactivity", AlbumArtist: "Kraftwerk", OrderAlbumName: "radioactivity", AlbumArtistID: "2", EmbedArtPath: p("kraft/radio/radio.mp3"), SongCount: 2})
+	albumMultiDisc     = al(model.Album{ID: "104", Name: "Multi Disc Album", AlbumArtist: "Test Artist", OrderAlbumName: "multi disc album", AlbumArtistID: "1", EmbedArtPath: p("test/multi/disc1/track1.mp3"), SongCount: 4})
+	albumCJK           = al(model.Album{ID: "105", Name: "COWBOY BEBOP", AlbumArtist: "シートベルツ", OrderAlbumName: "cowboy bebop", AlbumArtistID: "4", EmbedArtPath: p("seatbelts/cowboy-bebop/track1.mp3"), SongCount: 1})
+	albumWithVersion   = alWithTags(model.Album{ID: "106", Name: "Abbey Road", AlbumArtist: "The Beatles", OrderAlbumName: "abbey road", AlbumArtistID: "3", EmbedArtPath: p("beatles/2/come together.mp3"), SongCount: 1, MaxYear: 2019},
 		model.Tags{model.TagAlbumVersion: {"Deluxe Edition"}})
-	albumPunctuation = al(model.Album{ID: "107", Name: "Things Fall Apart", AlbumArtist: "The Roots", OrderAlbumName: "things fall apart", AlbumArtistID: "5", EmbedArtPath: p("/roots/things/track1.mp3"), SongCount: 1})
+	albumPunctuation = al(model.Album{ID: "107", Name: "Things Fall Apart", AlbumArtist: "The Roots", OrderAlbumName: "things fall apart", AlbumArtistID: "5", EmbedArtPath: p("roots/things/track1.mp3"), SongCount: 1})
 	testAlbums       = model.Albums{
 		albumSgtPeppers,
 		albumAbbeyRoad,
@@ -97,12 +97,12 @@ var (
 )
 
 var (
-	songDayInALife    = mf(model.MediaFile{ID: "1001", Title: "A Day In A Life", ArtistID: "3", Artist: "The Beatles", AlbumID: "101", Album: "Sgt Peppers", Path: p("/beatles/1/sgt/a day.mp3")})
-	songComeTogether  = mf(model.MediaFile{ID: "1002", Title: "Come Together", ArtistID: "3", Artist: "The Beatles", AlbumID: "102", Album: "Abbey Road", Path: p("/beatles/1/come together.mp3")})
-	songRadioactivity = mf(model.MediaFile{ID: "1003", Title: "Radioactivity", ArtistID: "2", Artist: "Kraftwerk", AlbumID: "103", Album: "Radioactivity", Path: p("/kraft/radio/radio.mp3")})
+	songDayInALife    = mf(model.MediaFile{ID: "1001", Title: "A Day In A Life", ArtistID: "3", Artist: "The Beatles", AlbumID: "101", Album: "Sgt Peppers", Path: p("beatles/1/sgt/a day.mp3")})
+	songComeTogether  = mf(model.MediaFile{ID: "1002", Title: "Come Together", ArtistID: "3", Artist: "The Beatles", AlbumID: "102", Album: "Abbey Road", Path: p("beatles/1/come together.mp3")})
+	songRadioactivity = mf(model.MediaFile{ID: "1003", Title: "Radioactivity", ArtistID: "2", Artist: "Kraftwerk", AlbumID: "103", Album: "Radioactivity", Path: p("kraft/radio/radio.mp3")})
 	songAntenna       = mf(model.MediaFile{ID: "1004", Title: "Antenna", ArtistID: "2", Artist: "Kraftwerk",
 		AlbumID:     "103",
-		Path:        p("/kraft/radio/antenna.mp3"),
+		Path:        p("kraft/radio/antenna.mp3"),
 		RGAlbumGain: gg.P(1.0), RGAlbumPeak: gg.P(2.0), RGTrackGain: gg.P(3.0), RGTrackPeak: gg.P(4.0),
 	})
 	songAntennaWithLyrics = mf(model.MediaFile{
@@ -115,13 +115,13 @@ var (
 	})
 	songAntenna2 = mf(model.MediaFile{ID: "1006", Title: "Antenna", ArtistID: "2", Artist: "Kraftwerk", AlbumID: "103"})
 	// Multi-disc album tracks (intentionally out of order to test sorting)
-	songDisc2Track11 = mf(model.MediaFile{ID: "2001", Title: "Disc 2 Track 11", ArtistID: "1", Artist: "Test Artist", AlbumID: "104", Album: "Multi Disc Album", DiscNumber: 2, TrackNumber: 11, Path: p("/test/multi/disc2/track11.mp3"), OrderAlbumName: "multi disc album", OrderArtistName: "test artist"})
-	songDisc1Track01 = mf(model.MediaFile{ID: "2002", Title: "Disc 1 Track 1", ArtistID: "1", Artist: "Test Artist", AlbumID: "104", Album: "Multi Disc Album", DiscNumber: 1, TrackNumber: 1, Path: p("/test/multi/disc1/track1.mp3"), OrderAlbumName: "multi disc album", OrderArtistName: "test artist"})
-	songDisc2Track01 = mf(model.MediaFile{ID: "2003", Title: "Disc 2 Track 1", ArtistID: "1", Artist: "Test Artist", AlbumID: "104", Album: "Multi Disc Album", DiscNumber: 2, TrackNumber: 1, Path: p("/test/multi/disc2/track1.mp3"), OrderAlbumName: "multi disc album", OrderArtistName: "test artist"})
-	songDisc1Track02 = mf(model.MediaFile{ID: "2004", Title: "Disc 1 Track 2", ArtistID: "1", Artist: "Test Artist", AlbumID: "104", Album: "Multi Disc Album", DiscNumber: 1, TrackNumber: 2, Path: p("/test/multi/disc1/track2.mp3"), OrderAlbumName: "multi disc album", OrderArtistName: "test artist"})
-	songCJK          = mf(model.MediaFile{ID: "3001", Title: "プラチナ・ジェット", ArtistID: "4", Artist: "シートベルツ", AlbumID: "105", Album: "COWBOY BEBOP", Path: p("/seatbelts/cowboy-bebop/track1.mp3")})
-	songVersioned    = mf(model.MediaFile{ID: "3002", Title: "Come Together", ArtistID: "3", Artist: "The Beatles", AlbumID: "106", Album: "Abbey Road", Path: p("/beatles/2/come together.mp3")})
-	songPunctuation  = mf(model.MediaFile{ID: "3003", Title: "!!!!!!!", ArtistID: "5", Artist: "The Roots", AlbumID: "107", Album: "Things Fall Apart", Path: p("/roots/things/track1.mp3")})
+	songDisc2Track11 = mf(model.MediaFile{ID: "2001", Title: "Disc 2 Track 11", ArtistID: "1", Artist: "Test Artist", AlbumID: "104", Album: "Multi Disc Album", DiscNumber: 2, TrackNumber: 11, Path: p("test/multi/disc2/track11.mp3"), OrderAlbumName: "multi disc album", OrderArtistName: "test artist"})
+	songDisc1Track01 = mf(model.MediaFile{ID: "2002", Title: "Disc 1 Track 1", ArtistID: "1", Artist: "Test Artist", AlbumID: "104", Album: "Multi Disc Album", DiscNumber: 1, TrackNumber: 1, Path: p("test/multi/disc1/track1.mp3"), OrderAlbumName: "multi disc album", OrderArtistName: "test artist"})
+	songDisc2Track01 = mf(model.MediaFile{ID: "2003", Title: "Disc 2 Track 1", ArtistID: "1", Artist: "Test Artist", AlbumID: "104", Album: "Multi Disc Album", DiscNumber: 2, TrackNumber: 1, Path: p("test/multi/disc2/track1.mp3"), OrderAlbumName: "multi disc album", OrderArtistName: "test artist"})
+	songDisc1Track02 = mf(model.MediaFile{ID: "2004", Title: "Disc 1 Track 2", ArtistID: "1", Artist: "Test Artist", AlbumID: "104", Album: "Multi Disc Album", DiscNumber: 1, TrackNumber: 2, Path: p("test/multi/disc1/track2.mp3"), OrderAlbumName: "multi disc album", OrderArtistName: "test artist"})
+	songCJK          = mf(model.MediaFile{ID: "3001", Title: "プラチナ・ジェット", ArtistID: "4", Artist: "シートベルツ", AlbumID: "105", Album: "COWBOY BEBOP", Path: p("seatbelts/cowboy-bebop/track1.mp3")})
+	songVersioned    = mf(model.MediaFile{ID: "3002", Title: "Come Together", ArtistID: "3", Artist: "The Beatles", AlbumID: "106", Album: "Abbey Road", Path: p("beatles/2/come together.mp3")})
+	songPunctuation  = mf(model.MediaFile{ID: "3003", Title: "!!!!!!!", ArtistID: "5", Artist: "The Roots", AlbumID: "107", Album: "Things Fall Apart", Path: p("roots/things/track1.mp3")})
 	testSongs        = model.MediaFiles{
 		songDayInALife,
 		songComeTogether,

persistence/playlist_repository.go

@@ -11,10 +11,8 @@ import (
 
 	. "github.com/Masterminds/squirrel"
 	"github.com/deluan/rest"
-	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
-	"github.com/navidrome/navidrome/model/criteria"
 	"github.com/pocketbase/dbx"
 )
 
@@ -99,8 +97,15 @@ func (r *playlistRepository) Delete(id string) error {
 	return r.delete(And{Eq{"id": id}, r.userFilter()})
 }
 
-func (r *playlistRepository) Put(p *model.Playlist) error {
+func (r *playlistRepository) Put(p *model.Playlist, cols ...string) error {
 	pls := dbPlaylist{Playlist: *p}
+	if len(cols) > 0 {
+		if pls.ID == "" {
+			return errors.New("playlist id is required for partial update")
+		}
+		_, err := r.put(pls.ID, pls, cols...)
+		return err
+	}
 	if pls.ID == "" {
 		pls.CreatedAt = time.Now()
 	}
@@ -202,141 +207,6 @@ func (r *playlistRepository) selectPlaylist(options ...model.QueryOptions) Selec
 		Columns(r.tableName+".*", "user.user_name as owner_name")
 }
 
-func (r *playlistRepository) refreshSmartPlaylist(pls *model.Playlist) bool {
-	// Only refresh if it is a smart playlist and was not refreshed within the interval provided by the refresh delay config
-	if !pls.IsSmartPlaylist() || (pls.EvaluatedAt != nil && time.Since(*pls.EvaluatedAt) < conf.Server.SmartPlaylistRefreshDelay) {
-		return false
-	}
-
-	// Never refresh other users' playlists
-	usr := loggedUser(r.ctx)
-	if pls.OwnerID != usr.ID {
-		log.Trace(r.ctx, "Not refreshing smart playlist from other user", "playlist", pls.Name, "id", pls.ID)
-		return false
-	}
-
-	log.Debug(r.ctx, "Refreshing smart playlist", "playlist", pls.Name, "id", pls.ID)
-	start := time.Now()
-
-	// Remove old tracks
-	del := Delete("playlist_tracks").Where(Eq{"playlist_id": pls.ID})
-	_, err := r.executeSQL(del)
-	if err != nil {
-		log.Error(r.ctx, "Error deleting old smart playlist tracks", "playlist", pls.Name, "id", pls.ID, err)
-		return false
-	}
-
-	// Re-populate playlist based on Smart Playlist criteria
-	rules := *pls.Rules
-
-	// If the playlist depends on other playlists, recursively refresh them first
-	childPlaylistIds := rules.ChildPlaylistIds()
-	for _, id := range childPlaylistIds {
-		childPls, err := r.Get(id)
-		if err != nil {
-			log.Error(r.ctx, "Error loading child playlist", "id", pls.ID, "childId", id, err)
-			return false
-		}
-		r.refreshSmartPlaylist(childPls)
-	}
-
-	sq := Select("row_number() over (order by "+rules.OrderBy()+") as id", "'"+pls.ID+"' as playlist_id", "media_file.id as media_file_id").
-		From("media_file").LeftJoin("annotation on ("+
-		"annotation.item_id = media_file.id"+
-		" AND annotation.item_type = 'media_file'"+
-		" AND annotation.user_id = ?)", usr.ID)
-
-	// Conditionally join album/artist annotation tables only when referenced by criteria or sort
-	requiredJoins := rules.RequiredJoins()
-	sq = r.addSmartPlaylistAnnotationJoins(sq, requiredJoins, usr.ID)
-
-	// Only include media files from libraries the user has access to
-	sq = r.applyLibraryFilter(sq, "media_file")
-
-	// Resolve percentage-based limit to an absolute number before applying criteria
-	if rules.IsPercentageLimit() {
-		// Use only expression-based joins for the COUNT query (sort joins are unnecessary)
-		exprJoins := rules.ExpressionJoins()
-		countSq := Select("count(*) as count").From("media_file").
-			LeftJoin("annotation on ("+
-				"annotation.item_id = media_file.id"+
-				" AND annotation.item_type = 'media_file'"+
-				" AND annotation.user_id = ?)", usr.ID)
-		countSq = r.addSmartPlaylistAnnotationJoins(countSq, exprJoins, usr.ID)
-		countSq = r.applyLibraryFilter(countSq, "media_file")
-		countSq = countSq.Where(rules)
-
-		var res struct{ Count int64 }
-		err = r.queryOne(countSq, &res)
-		if err != nil {
-			log.Error(r.ctx, "Error counting matching tracks for percentage limit", "playlist", pls.Name, "id", pls.ID, err)
-			return false
-		}
-		resolvedLimit := rules.EffectiveLimit(res.Count)
-		log.Debug(r.ctx, "Resolved percentage limit", "playlist", pls.Name, "percent", rules.LimitPercent, "totalMatching", res.Count, "resolvedLimit", resolvedLimit)
-		rules.Limit = resolvedLimit
-		rules.LimitPercent = 0
-	}
-
-	// Apply the criteria rules
-	sq = r.addCriteria(sq, rules)
-	insSql := Insert("playlist_tracks").Columns("id", "playlist_id", "media_file_id").Select(sq)
-	_, err = r.executeSQL(insSql)
-	if err != nil {
-		log.Error(r.ctx, "Error refreshing smart playlist tracks", "playlist", pls.Name, "id", pls.ID, err)
-		return false
-	}
-
-	// Update playlist stats
-	err = r.refreshCounters(pls)
-	if err != nil {
-		log.Error(r.ctx, "Error updating smart playlist stats", "playlist", pls.Name, "id", pls.ID, err)
-		return false
-	}
-
-	// Update when the playlist was last refreshed (for cache purposes)
-	now := time.Now()
-	updSql := Update(r.tableName).Set("evaluated_at", now).Where(Eq{"id": pls.ID})
-	_, err = r.executeSQL(updSql)
-	if err != nil {
-		log.Error(r.ctx, "Error updating smart playlist", "playlist", pls.Name, "id", pls.ID, err)
-		return false
-	}
-
-	pls.EvaluatedAt = &now
-
-	log.Debug(r.ctx, "Refreshed playlist", "playlist", pls.Name, "id", pls.ID, "numTracks", pls.SongCount, "elapsed", time.Since(start))
-
-	return true
-}
-
-func (r *playlistRepository) addSmartPlaylistAnnotationJoins(sq SelectBuilder, joins criteria.JoinType, userID string) SelectBuilder {
-	if joins.Has(criteria.JoinAlbumAnnotation) {
-		sq = sq.LeftJoin("annotation AS album_annotation ON ("+
-			"album_annotation.item_id = media_file.album_id"+
-			" AND album_annotation.item_type = 'album'"+
-			" AND album_annotation.user_id = ?)", userID)
-	}
-	if joins.Has(criteria.JoinArtistAnnotation) {
-		sq = sq.LeftJoin("annotation AS artist_annotation ON ("+
-			"artist_annotation.item_id = media_file.artist_id"+
-			" AND artist_annotation.item_type = 'artist'"+
-			" AND artist_annotation.user_id = ?)", userID)
-	}
-	return sq
-}
-
-func (r *playlistRepository) addCriteria(sql SelectBuilder, c criteria.Criteria) SelectBuilder {
-	sql = sql.Where(c)
-	if c.Limit > 0 {
-		sql = sql.Limit(uint64(c.Limit)).Offset(uint64(c.Offset))
-	}
-	if order := c.OrderBy(); order != "" {
-		sql = sql.OrderBy(order)
-	}
-	return sql
-}
-
 func (r *playlistRepository) updateTracks(id string, tracks model.MediaFiles) error {
 	ids := make([]string, len(tracks))
 	for i := range tracks {

persistence/playlist_repository_test.go

@@ -1,17 +1,11 @@
 package persistence
 
 import (
-	"time"
-
-	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
-	"github.com/navidrome/navidrome/model/criteria"
 	"github.com/navidrome/navidrome/model/request"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
-	"github.com/pocketbase/dbx"
 )
 
 var _ = Describe("PlaylistRepository", func() {
@@ -128,379 +122,6 @@ var _ = Describe("PlaylistRepository", func() {
 		})
 	})
 
-	Context("Smart Playlists", func() {
-		var rules *criteria.Criteria
-		BeforeEach(func() {
-			rules = &criteria.Criteria{
-				Expression: criteria.All{
-					criteria.Contains{"title": "love"},
-				},
-			}
-		})
-		Context("valid rules", func() {
-			Specify("Put/Get", func() {
-				newPls := model.Playlist{Name: "Great!", OwnerID: "userid", Rules: rules}
-				Expect(repo.Put(&newPls)).To(Succeed())
-
-				savedPls, err := repo.Get(newPls.ID)
-				Expect(err).ToNot(HaveOccurred())
-				Expect(savedPls.Rules).To(Equal(rules))
-			})
-		})
-
-		Context("invalid rules", func() {
-			It("fails to Put it in the DB", func() {
-				rules = &criteria.Criteria{
-					// This is invalid because "contains" cannot have multiple fields
-					Expression: criteria.All{
-						criteria.Contains{"genre": "Hardcore", "filetype": "mp3"},
-					},
-				}
-				newPls := model.Playlist{Name: "Great!", OwnerID: "userid", Rules: rules}
-				Expect(repo.Put(&newPls)).To(MatchError(ContainSubstring("invalid criteria expression")))
-			})
-		})
-
-		Context("child smart playlists", func() {
-			BeforeEach(func() {
-				DeferCleanup(configtest.SetupConfig())
-			})
-
-			When("refresh delay has expired", func() {
-				It("should refresh tracks for smart playlist referenced in parent smart playlist criteria", func() {
-					conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second
-
-					childRules := &criteria.Criteria{
-						Expression: criteria.All{
-							criteria.Contains{"title": "Day"},
-						},
-					}
-					nestedPls := model.Playlist{Name: "Nested", OwnerID: "userid", Public: true, Rules: childRules}
-					Expect(repo.Put(&nestedPls)).To(Succeed())
-					DeferCleanup(func() { _ = repo.Delete(nestedPls.ID) })
-
-					parentPls := model.Playlist{Name: "Parent", OwnerID: "userid", Rules: &criteria.Criteria{
-						Expression: criteria.All{
-							criteria.InPlaylist{"id": nestedPls.ID},
-						},
-					}}
-					Expect(repo.Put(&parentPls)).To(Succeed())
-					DeferCleanup(func() { _ = repo.Delete(parentPls.ID) })
-
-					// Nested playlist has not been evaluated yet
-					nestedPlsRead, err := repo.Get(nestedPls.ID)
-					Expect(err).ToNot(HaveOccurred())
-					Expect(nestedPlsRead.EvaluatedAt).To(BeNil())
-
-					// Getting parent with refresh should recursively refresh the nested playlist
-					pls, err := repo.GetWithTracks(parentPls.ID, true, false)
-					Expect(err).ToNot(HaveOccurred())
-					Expect(pls.EvaluatedAt).ToNot(BeNil())
-					Expect(*pls.EvaluatedAt).To(BeTemporally("~", time.Now(), 2*time.Second))
-
-					// Parent should have tracks from the nested playlist
-					Expect(pls.Tracks).To(HaveLen(1))
-					Expect(pls.Tracks[0].MediaFileID).To(Equal(songDayInALife.ID))
-
-					// Nested playlist should now have been refreshed (EvaluatedAt set)
-					nestedPlsAfterParentGet, err := repo.Get(nestedPls.ID)
-					Expect(err).ToNot(HaveOccurred())
-					Expect(nestedPlsAfterParentGet.EvaluatedAt).ToNot(BeNil())
-					Expect(*nestedPlsAfterParentGet.EvaluatedAt).To(BeTemporally("~", time.Now(), 2*time.Second))
-				})
-			})
-
-			When("refresh delay has not expired", func() {
-				It("should NOT refresh tracks for smart playlist referenced in parent smart playlist criteria", func() {
-					conf.Server.SmartPlaylistRefreshDelay = 1 * time.Hour
-					childEvaluatedAt := time.Now().Add(-30 * time.Minute)
-
-					childRules := &criteria.Criteria{
-						Expression: criteria.All{
-							criteria.Contains{"title": "Day"},
-						},
-					}
-					nestedPls := model.Playlist{Name: "Nested", OwnerID: "userid", Public: true, Rules: childRules, EvaluatedAt: &childEvaluatedAt}
-					Expect(repo.Put(&nestedPls)).To(Succeed())
-					DeferCleanup(func() { _ = repo.Delete(nestedPls.ID) })
-
-					// Parent has no EvaluatedAt, so it WILL refresh, but the child should not
-					parentPls := model.Playlist{Name: "Parent", OwnerID: "userid", Rules: &criteria.Criteria{
-						Expression: criteria.All{
-							criteria.InPlaylist{"id": nestedPls.ID},
-						},
-					}}
-					Expect(repo.Put(&parentPls)).To(Succeed())
-					DeferCleanup(func() { _ = repo.Delete(parentPls.ID) })
-
-					nestedPlsRead, err := repo.Get(nestedPls.ID)
-					Expect(err).ToNot(HaveOccurred())
-
-					// Getting parent with refresh should NOT recursively refresh the nested playlist
-					parent, err := repo.GetWithTracks(parentPls.ID, true, false)
-					Expect(err).ToNot(HaveOccurred())
-
-					// Parent should have been refreshed (its EvaluatedAt was nil)
-					Expect(parent.EvaluatedAt).ToNot(BeNil())
-					Expect(*parent.EvaluatedAt).To(BeTemporally("~", time.Now(), 2*time.Second))
-
-					// Nested playlist should NOT have been refreshed (still within delay window)
-					nestedPlsAfterParentGet, err := repo.Get(nestedPls.ID)
-					Expect(err).ToNot(HaveOccurred())
-					Expect(*nestedPlsAfterParentGet.EvaluatedAt).To(BeTemporally("~", childEvaluatedAt, time.Second))
-					Expect(*nestedPlsAfterParentGet.EvaluatedAt).To(Equal(*nestedPlsRead.EvaluatedAt))
-				})
-			})
-		})
-	})
-
-	Describe("Playlist Track Sorting", func() {
-		var testPlaylistID string
-
-		AfterEach(func() {
-			if testPlaylistID != "" {
-				Expect(repo.Delete(testPlaylistID)).To(BeNil())
-				testPlaylistID = ""
-			}
-		})
-
-		It("sorts tracks correctly by album (disc and track number)", func() {
-			By("creating a playlist with multi-disc album tracks in arbitrary order")
-			newPls := model.Playlist{Name: "Multi-Disc Test", OwnerID: "userid"}
-			// Add tracks in intentionally scrambled order
-			newPls.AddMediaFilesByID([]string{"2001", "2002", "2003", "2004"})
-			Expect(repo.Put(&newPls)).To(Succeed())
-			testPlaylistID = newPls.ID
-
-			By("retrieving tracks sorted by album")
-			tracksRepo := repo.Tracks(newPls.ID, false)
-			tracks, err := tracksRepo.GetAll(model.QueryOptions{Sort: "album", Order: "asc"})
-			Expect(err).ToNot(HaveOccurred())
-
-			By("verifying tracks are sorted by disc number then track number")
-			Expect(tracks).To(HaveLen(4))
-			// Expected order: Disc 1 Track 1, Disc 1 Track 2, Disc 2 Track 1, Disc 2 Track 11
-			Expect(tracks[0].MediaFileID).To(Equal("2002")) // Disc 1, Track 1
-			Expect(tracks[1].MediaFileID).To(Equal("2004")) // Disc 1, Track 2
-			Expect(tracks[2].MediaFileID).To(Equal("2003")) // Disc 2, Track 1
-			Expect(tracks[3].MediaFileID).To(Equal("2001")) // Disc 2, Track 11
-		})
-	})
-
-	Describe("Smart Playlists with Album/Artist Annotation Criteria", func() {
-		var testPlaylistID string
-
-		AfterEach(func() {
-			if testPlaylistID != "" {
-				_ = repo.Delete(testPlaylistID)
-				testPlaylistID = ""
-			}
-		})
-
-		It("matches tracks from starred albums using albumLoved", func() {
-			// albumRadioactivity (ID "103") is starred in test fixtures
-			// Songs in album 103: 1003, 1004, 1005, 1006
-			rules := &criteria.Criteria{
-				Expression: criteria.All{
-					criteria.Is{"albumLoved": true},
-				},
-			}
-			newPls := model.Playlist{Name: "Starred Album Songs", OwnerID: "userid", Rules: rules}
-			Expect(repo.Put(&newPls)).To(Succeed())
-			testPlaylistID = newPls.ID
-
-			conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second
-			pls, err := repo.GetWithTracks(newPls.ID, true, false)
-			Expect(err).ToNot(HaveOccurred())
-
-			trackIDs := make([]string, len(pls.Tracks))
-			for i, t := range pls.Tracks {
-				trackIDs[i] = t.MediaFileID
-			}
-			Expect(trackIDs).To(ConsistOf("1003", "1004", "1005", "1006"))
-		})
-
-		It("matches tracks from starred artists using artistLoved", func() {
-			// artistBeatles (ID "3") is starred in test fixtures
-			// Songs with ArtistID "3": 1001, 1002, 3002
-			rules := &criteria.Criteria{
-				Expression: criteria.All{
-					criteria.Is{"artistLoved": true},
-				},
-			}
-			newPls := model.Playlist{Name: "Starred Artist Songs", OwnerID: "userid", Rules: rules}
-			Expect(repo.Put(&newPls)).To(Succeed())
-			testPlaylistID = newPls.ID
-
-			conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second
-			pls, err := repo.GetWithTracks(newPls.ID, true, false)
-			Expect(err).ToNot(HaveOccurred())
-
-			trackIDs := make([]string, len(pls.Tracks))
-			for i, t := range pls.Tracks {
-				trackIDs[i] = t.MediaFileID
-			}
-			Expect(trackIDs).To(ConsistOf("1001", "1002", "3002"))
-		})
-
-		It("matches tracks with combined album and artist criteria", func() {
-			// albumLoved=true → songs from album 103 (1003, 1004, 1005, 1006)
-			// artistLoved=true → songs with artist 3 (1001, 1002)
-			// Using Any: union of both sets
-			rules := &criteria.Criteria{
-				Expression: criteria.Any{
-					criteria.Is{"albumLoved": true},
-					criteria.Is{"artistLoved": true},
-				},
-			}
-			newPls := model.Playlist{Name: "Combined Album+Artist", OwnerID: "userid", Rules: rules}
-			Expect(repo.Put(&newPls)).To(Succeed())
-			testPlaylistID = newPls.ID
-
-			conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second
-			pls, err := repo.GetWithTracks(newPls.ID, true, false)
-			Expect(err).ToNot(HaveOccurred())
-
-			trackIDs := make([]string, len(pls.Tracks))
-			for i, t := range pls.Tracks {
-				trackIDs[i] = t.MediaFileID
-			}
-			Expect(trackIDs).To(ConsistOf("1001", "1002", "1003", "1004", "1005", "1006", "3002"))
-		})
-
-		It("returns no tracks when no albums/artists match", func() {
-			// No album has rating 5 in fixtures
-			rules := &criteria.Criteria{
-				Expression: criteria.All{
-					criteria.Is{"albumRating": 5},
-				},
-			}
-			newPls := model.Playlist{Name: "No Match", OwnerID: "userid", Rules: rules}
-			Expect(repo.Put(&newPls)).To(Succeed())
-			testPlaylistID = newPls.ID
-
-			conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second
-			pls, err := repo.GetWithTracks(newPls.ID, true, false)
-			Expect(err).ToNot(HaveOccurred())
-
-			Expect(pls.Tracks).To(BeEmpty())
-		})
-	})
-
-	Describe("Smart Playlists with Tag Criteria", func() {
-		var mfRepo model.MediaFileRepository
-		var testPlaylistID string
-		var songWithGrouping, songWithoutGrouping model.MediaFile
-
-		BeforeEach(func() {
-			ctx := log.NewContext(GinkgoT().Context())
-			ctx = request.WithUser(ctx, model.User{ID: "userid", UserName: "userid", IsAdmin: true})
-			mfRepo = NewMediaFileRepository(ctx, GetDBXBuilder())
-
-			// Register 'grouping' as a valid tag for smart playlists
-			criteria.AddTagNames([]string{"grouping"})
-
-			// Create a song with the grouping tag
-			songWithGrouping = model.MediaFile{
-				ID:       "test-grouping-1",
-				Title:    "Song With Grouping",
-				Artist:   "Test Artist",
-				ArtistID: "1",
-				Album:    "Test Album",
-				AlbumID:  "101",
-				Path:     "/test/grouping/song1.mp3",
-				Tags: model.Tags{
-					"grouping": []string{"My Crate"},
-				},
-				Participants: model.Participants{},
-				LibraryID:    1,
-				Lyrics:       "[]",
-			}
-			Expect(mfRepo.Put(&songWithGrouping)).To(Succeed())
-
-			// Create a song without the grouping tag
-			songWithoutGrouping = model.MediaFile{
-				ID:           "test-grouping-2",
-				Title:        "Song Without Grouping",
-				Artist:       "Test Artist",
-				ArtistID:     "1",
-				Album:        "Test Album",
-				AlbumID:      "101",
-				Path:         "/test/grouping/song2.mp3",
-				Tags:         model.Tags{},
-				Participants: model.Participants{},
-				LibraryID:    1,
-				Lyrics:       "[]",
-			}
-			Expect(mfRepo.Put(&songWithoutGrouping)).To(Succeed())
-		})
-
-		AfterEach(func() {
-			if testPlaylistID != "" {
-				_ = repo.Delete(testPlaylistID)
-				testPlaylistID = ""
-			}
-			// Clean up test media files
-			_, _ = GetDBXBuilder().Delete("media_file", dbx.HashExp{"id": "test-grouping-1"}).Execute()
-			_, _ = GetDBXBuilder().Delete("media_file", dbx.HashExp{"id": "test-grouping-2"}).Execute()
-		})
-
-		It("matches tracks with a tag value using 'contains' with empty string (issue #4728 workaround)", func() {
-			By("creating a smart playlist that checks if grouping tag has any value")
-			// This is the workaround for issue #4728: using 'contains' with empty string
-			// generates SQL: value LIKE '%%' which matches any non-empty string
-			rules := &criteria.Criteria{
-				Expression: criteria.All{
-					criteria.Contains{"grouping": ""},
-				},
-			}
-			newPls := model.Playlist{Name: "Tracks with Grouping", OwnerID: "userid", Rules: rules}
-			Expect(repo.Put(&newPls)).To(Succeed())
-			testPlaylistID = newPls.ID
-
-			By("refreshing the smart playlist")
-			conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second // Force refresh
-			pls, err := repo.GetWithTracks(newPls.ID, true, false)
-			Expect(err).ToNot(HaveOccurred())
-
-			By("verifying only the track with grouping tag is matched")
-			Expect(pls.Tracks).To(HaveLen(1))
-			Expect(pls.Tracks[0].MediaFileID).To(Equal(songWithGrouping.ID))
-		})
-
-		It("excludes tracks with a tag value using 'notContains' with empty string", func() {
-			By("creating a smart playlist that checks if grouping tag is NOT set")
-			rules := &criteria.Criteria{
-				Expression: criteria.All{
-					criteria.NotContains{"grouping": ""},
-				},
-			}
-			newPls := model.Playlist{Name: "Tracks without Grouping", OwnerID: "userid", Rules: rules}
-			Expect(repo.Put(&newPls)).To(Succeed())
-			testPlaylistID = newPls.ID
-
-			By("refreshing the smart playlist")
-			conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second // Force refresh
-			pls, err := repo.GetWithTracks(newPls.ID, true, false)
-			Expect(err).ToNot(HaveOccurred())
-
-			By("verifying the track with grouping is NOT in the playlist")
-			for _, track := range pls.Tracks {
-				Expect(track.MediaFileID).ToNot(Equal(songWithGrouping.ID))
-			}
-
-			By("verifying the track without grouping IS in the playlist")
-			var foundWithoutGrouping bool
-			for _, track := range pls.Tracks {
-				if track.MediaFileID == songWithoutGrouping.ID {
-					foundWithoutGrouping = true
-					break
-				}
-			}
-			Expect(foundWithoutGrouping).To(BeTrue())
-		})
-	})
-
 	Describe("Track Deletion and Renumbering", func() {
 		var testPlaylistID string
 
@@ -573,136 +194,4 @@ var _ = Describe("PlaylistRepository", func() {
 			Expect(mediaFileIDs).To(Equal([]string{"1001", "1002"}))
 		})
 	})
-
-	Describe("Smart Playlists Library Filtering", func() {
-		var mfRepo model.MediaFileRepository
-		var testPlaylistID string
-		var lib2ID int
-		var restrictedUserID string
-		var uniqueLibPath string
-
-		BeforeEach(func() {
-			db := GetDBXBuilder()
-
-			// Generate unique IDs for this test run
-			uniqueSuffix := time.Now().Format("20060102150405.000")
-			restrictedUserID = "restricted-user-" + uniqueSuffix
-			uniqueLibPath = "/music/lib2-" + uniqueSuffix
-
-			// Create a second library with unique name and path to avoid conflicts with other tests
-			_, err := db.DB().Exec("INSERT INTO library (name, path, created_at, updated_at) VALUES (?, ?, datetime('now'), datetime('now'))", "Library 2-"+uniqueSuffix, uniqueLibPath)
-			Expect(err).ToNot(HaveOccurred())
-			err = db.DB().QueryRow("SELECT last_insert_rowid()").Scan(&lib2ID)
-			Expect(err).ToNot(HaveOccurred())
-
-			// Create a restricted user with access only to library 1
-			_, err = db.DB().Exec("INSERT INTO user (id, user_name, name, is_admin, password, created_at, updated_at) VALUES (?, ?, 'Restricted User', false, 'pass', datetime('now'), datetime('now'))", restrictedUserID, restrictedUserID)
-			Expect(err).ToNot(HaveOccurred())
-			_, err = db.DB().Exec("INSERT INTO user_library (user_id, library_id) VALUES (?, 1)", restrictedUserID)
-			Expect(err).ToNot(HaveOccurred())
-
-			// Create test media files in each library
-			ctx := log.NewContext(GinkgoT().Context())
-			ctx = request.WithUser(ctx, model.User{ID: "userid", UserName: "userid", IsAdmin: true})
-			mfRepo = NewMediaFileRepository(ctx, db)
-
-			// Song in library 1 (accessible by restricted user)
-			songLib1 := model.MediaFile{
-				ID:           "lib1-song",
-				Title:        "Song in Lib1",
-				Artist:       "Test Artist",
-				ArtistID:     "1",
-				Album:        "Test Album",
-				AlbumID:      "101",
-				Path:         "/music/lib1/song.mp3",
-				LibraryID:    1,
-				Participants: model.Participants{},
-				Tags:         model.Tags{},
-				Lyrics:       "[]",
-			}
-			Expect(mfRepo.Put(&songLib1)).To(Succeed())
-
-			// Song in library 2 (NOT accessible by restricted user)
-			songLib2 := model.MediaFile{
-				ID:           "lib2-song",
-				Title:        "Song in Lib2",
-				Artist:       "Test Artist",
-				ArtistID:     "1",
-				Album:        "Test Album",
-				AlbumID:      "101",
-				Path:         uniqueLibPath + "/song.mp3",
-				LibraryID:    lib2ID,
-				Participants: model.Participants{},
-				Tags:         model.Tags{},
-				Lyrics:       "[]",
-			}
-			Expect(mfRepo.Put(&songLib2)).To(Succeed())
-		})
-
-		AfterEach(func() {
-			db := GetDBXBuilder()
-			if testPlaylistID != "" {
-				_ = repo.Delete(testPlaylistID)
-				testPlaylistID = ""
-			}
-			// Clean up test data
-			_, _ = db.Delete("media_file", dbx.HashExp{"id": "lib1-song"}).Execute()
-			_, _ = db.Delete("media_file", dbx.HashExp{"id": "lib2-song"}).Execute()
-			_, _ = db.Delete("user_library", dbx.HashExp{"user_id": restrictedUserID}).Execute()
-			_, _ = db.Delete("user", dbx.HashExp{"id": restrictedUserID}).Execute()
-			_, _ = db.DB().Exec("DELETE FROM library WHERE id = ?", lib2ID)
-		})
-
-		It("should only include tracks from libraries the user has access to (issue #4738)", func() {
-			db := GetDBXBuilder()
-			ctx := log.NewContext(GinkgoT().Context())
-
-			// Create the smart playlist as the restricted user
-			restrictedUser := model.User{ID: restrictedUserID, UserName: restrictedUserID, IsAdmin: false}
-			ctx = request.WithUser(ctx, restrictedUser)
-			restrictedRepo := NewPlaylistRepository(ctx, db)
-
-			// Create a smart playlist that matches all songs
-			rules := &criteria.Criteria{
-				Expression: criteria.All{
-					criteria.Gt{"playCount": -1}, // Matches everything
-				},
-			}
-			newPls := model.Playlist{Name: "All Songs", OwnerID: restrictedUserID, Rules: rules}
-			Expect(restrictedRepo.Put(&newPls)).To(Succeed())
-			testPlaylistID = newPls.ID
-
-			By("refreshing the smart playlist")
-			conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second // Force refresh
-			pls, err := restrictedRepo.GetWithTracks(newPls.ID, true, false)
-			Expect(err).ToNot(HaveOccurred())
-
-			By("verifying only the track from library 1 is in the playlist")
-			var foundLib1Song, foundLib2Song bool
-			for _, track := range pls.Tracks {
-				if track.MediaFileID == "lib1-song" {
-					foundLib1Song = true
-				}
-				if track.MediaFileID == "lib2-song" {
-					foundLib2Song = true
-				}
-			}
-			Expect(foundLib1Song).To(BeTrue(), "Song from library 1 should be in the playlist")
-			Expect(foundLib2Song).To(BeFalse(), "Song from library 2 should NOT be in the playlist")
-
-			By("verifying playlist_tracks table only contains the accessible track")
-			var playlistTracksCount int
-			err = db.DB().QueryRow("SELECT count(*) FROM playlist_tracks WHERE playlist_id = ?", newPls.ID).Scan(&playlistTracksCount)
-			Expect(err).ToNot(HaveOccurred())
-			// Count should only include tracks visible to the user (lib1-song)
-			// The count may include other test songs from library 1, but NOT lib2-song
-			var lib2TrackCount int
-			err = db.DB().QueryRow("SELECT count(*) FROM playlist_tracks WHERE playlist_id = ? AND media_file_id = 'lib2-song'", newPls.ID).Scan(&lib2TrackCount)
-			Expect(err).ToNot(HaveOccurred())
-			Expect(lib2TrackCount).To(Equal(0), "lib2-song should not be in playlist_tracks")
-
-			By("verifying SongCount matches visible tracks")
-			Expect(pls.SongCount).To(Equal(len(pls.Tracks)), "SongCount should match the number of visible tracks")
-		})
-	})
 })

persistence/smart_playlist_repository.go

@@ -0,0 +1,203 @@
+package persistence
+
+import (
+	"time"
+
+	. "github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+)
+
+// PlaylistRepository methods to handle smart playlists, which are defined by criteria and automatically populated
+// based on their rules. The main method is refreshSmartPlaylist, which evaluates the criteria and updates the playlist
+// tracks accordingly. It also handles refreshing dependent playlists when a smart playlist references other playlists
+// in its criteria. To optimize performance, it only refreshes when necessary based on the last evaluated time and
+// configured refresh delay.
+
+// refreshSmartPlaylist evaluates the criteria of a smart playlist and updates its tracks accordingly.
+func (r *playlistRepository) refreshSmartPlaylist(pls *model.Playlist) bool {
+	usr := loggedUser(r.ctx)
+	if !r.shouldRefreshSmartPlaylist(pls, usr) {
+		return false
+	}
+
+	log.Debug(r.ctx, "Refreshing smart playlist", "playlist", pls.Name, "id", pls.ID)
+	start := time.Now()
+
+	del := Delete("playlist_tracks").Where(Eq{"playlist_id": pls.ID})
+	if _, err := r.executeSQL(del); err != nil {
+		log.Error(r.ctx, "Error deleting old smart playlist tracks", "playlist", pls.Name, "id", pls.ID, err)
+		return false
+	}
+
+	rulesSQL := newSmartPlaylistCriteria(*pls.Rules, withSmartPlaylistOwner(*usr))
+
+	if !r.refreshChildPlaylists(pls, rulesSQL) {
+		return false
+	}
+
+	if err := r.resolvePercentageLimit(pls, &rulesSQL, usr.ID); err != nil {
+		return false
+	}
+
+	sq := r.buildSmartPlaylistQuery(pls, rulesSQL, usr.ID)
+	sq, err := r.addCriteria(sq, rulesSQL)
+	if err != nil {
+		log.Error(r.ctx, "Error building smart playlist criteria", "playlist", pls.Name, "id", pls.ID, err)
+		return false
+	}
+
+	insSql := Insert("playlist_tracks").Columns("id", "playlist_id", "media_file_id").Select(sq)
+	if _, err = r.executeSQL(insSql); err != nil {
+		log.Error(r.ctx, "Error refreshing smart playlist tracks", "playlist", pls.Name, "id", pls.ID, err)
+		return false
+	}
+
+	if err = r.refreshCounters(pls); err != nil {
+		log.Error(r.ctx, "Error updating smart playlist stats", "playlist", pls.Name, "id", pls.ID, err)
+		return false
+	}
+
+	now := time.Now()
+	updSql := Update(r.tableName).Set("evaluated_at", now).Where(Eq{"id": pls.ID})
+	if _, err = r.executeSQL(updSql); err != nil {
+		log.Error(r.ctx, "Error updating smart playlist", "playlist", pls.Name, "id", pls.ID, err)
+		return false
+	}
+	pls.EvaluatedAt = &now
+
+	log.Debug(r.ctx, "Refreshed playlist", "playlist", pls.Name, "id", pls.ID, "numTracks", pls.SongCount, "elapsed", time.Since(start))
+	return true
+}
+
+// shouldRefreshSmartPlaylist determines if a smart playlist needs to be refreshed based on its type, last evaluated
+// time, and ownership.
+func (r *playlistRepository) shouldRefreshSmartPlaylist(pls *model.Playlist, usr *model.User) bool {
+	if !pls.IsSmartPlaylist() {
+		return false
+	}
+	if pls.EvaluatedAt != nil && time.Since(*pls.EvaluatedAt) < conf.Server.SmartPlaylistRefreshDelay {
+		return false
+	}
+	if pls.OwnerID != usr.ID {
+		log.Trace(r.ctx, "Not refreshing smart playlist from other user", "playlist", pls.Name, "id", pls.ID)
+		return false
+	}
+	return true
+}
+
+// refreshChildPlaylists handles refreshing any child playlists that are referenced in the smart playlist criteria.
+// Returns false if child playlists could not be loaded (DB error), signaling the parent refresh should abort.
+func (r *playlistRepository) refreshChildPlaylists(pls *model.Playlist, rulesSQL smartPlaylistCriteria) bool {
+	childPlaylistIds := rulesSQL.ChildPlaylistIds()
+	if len(childPlaylistIds) == 0 {
+		return true
+	}
+
+	childPlaylists, err := r.GetAll(model.QueryOptions{Filters: Eq{"playlist.id": childPlaylistIds}})
+	if err != nil {
+		log.Error(r.ctx, "Error loading child playlists for smart playlist refresh", "playlist", pls.Name, "id", pls.ID, "childIds", childPlaylistIds, err)
+		return false
+	}
+
+	found := make(map[string]struct{}, len(childPlaylists))
+	for i := range childPlaylists {
+		found[childPlaylists[i].ID] = struct{}{}
+		r.refreshSmartPlaylist(&childPlaylists[i])
+	}
+	for _, id := range childPlaylistIds {
+		if _, ok := found[id]; !ok {
+			log.Warn(r.ctx, "Referenced playlist is not accessible to smart playlist owner", "playlist", pls.Name, "id", pls.ID, "childId", id, "ownerId", pls.OwnerID)
+		}
+	}
+	return true
+}
+
+// resolvePercentageLimit calculates the actual limit for a smart playlist criteria that uses a percentage-based limit.
+func (r *playlistRepository) resolvePercentageLimit(pls *model.Playlist, rulesSQL *smartPlaylistCriteria, userID string) error {
+	if !rulesSQL.IsPercentageLimit() {
+		return nil
+	}
+
+	exprJoins := rulesSQL.ExpressionJoins()
+	countSq := Select("count(*) as count").From("media_file")
+	countSq = r.addMediaFileAnnotationJoin(countSq, userID)
+	countSq = r.addSmartPlaylistAnnotationJoins(countSq, exprJoins, userID)
+	countSq = r.applyLibraryFilter(countSq, "media_file")
+
+	cond, err := rulesSQL.Where()
+	if err != nil {
+		log.Error(r.ctx, "Error building smart playlist criteria", "playlist", pls.Name, "id", pls.ID, err)
+		return err
+	}
+	countSq = countSq.Where(cond)
+
+	var res struct{ Count int64 }
+	if err = r.queryOne(countSq, &res); err != nil {
+		log.Error(r.ctx, "Error counting matching tracks for percentage limit", "playlist", pls.Name, "id", pls.ID, err)
+		return err
+	}
+
+	rulesSQL.ResolveLimit(res.Count)
+	log.Debug(r.ctx, "Resolved percentage limit", "playlist", pls.Name, "percent", rulesSQL.LimitPercent, "totalMatching", res.Count, "resolvedLimit", rulesSQL.Limit)
+	return nil
+}
+
+// buildSmartPlaylistQuery constructs the SQL query to select media files matching the smart playlist criteria,
+// including necessary joins for annotations and library filtering.
+func (r *playlistRepository) buildSmartPlaylistQuery(pls *model.Playlist, rulesSQL smartPlaylistCriteria, userID string) SelectBuilder {
+	orderBy := rulesSQL.OrderBy()
+	sq := Select("row_number() over (order by "+orderBy+") as id", "'"+pls.ID+"' as playlist_id", "media_file.id as media_file_id").
+		From("media_file")
+	sq = r.addMediaFileAnnotationJoin(sq, userID)
+
+	requiredJoins := rulesSQL.RequiredJoins()
+	sq = r.addSmartPlaylistAnnotationJoins(sq, requiredJoins, userID)
+	sq = r.applyLibraryFilter(sq, "media_file")
+	return sq
+}
+
+// addMediaFileAnnotationJoin adds a left join to the annotation table for media files, filtering by user ID to include
+// user-specific annotations in the smart playlist criteria evaluation.
+func (r *playlistRepository) addMediaFileAnnotationJoin(sq SelectBuilder, userID string) SelectBuilder {
+	return sq.LeftJoin("annotation on ("+
+		"annotation.item_id = media_file.id"+
+		" AND annotation.item_type = 'media_file'"+
+		" AND annotation.user_id = ?)", userID)
+}
+
+// addSmartPlaylistAnnotationJoins adds left joins to the annotation table for albums and artists as needed based on
+// the smart playlist criteria, filtering by user ID to include user-specific annotations in the evaluation.
+func (r *playlistRepository) addSmartPlaylistAnnotationJoins(sq SelectBuilder, joins smartPlaylistJoinType, userID string) SelectBuilder {
+	if joins.has(smartPlaylistJoinAlbumAnnotation) {
+		sq = sq.LeftJoin("annotation AS album_annotation ON ("+
+			"album_annotation.item_id = media_file.album_id"+
+			" AND album_annotation.item_type = 'album'"+
+			" AND album_annotation.user_id = ?)", userID)
+	}
+	if joins.has(smartPlaylistJoinArtistAnnotation) {
+		sq = sq.LeftJoin("annotation AS artist_annotation ON ("+
+			"artist_annotation.item_id = media_file.artist_id"+
+			" AND artist_annotation.item_type = 'artist'"+
+			" AND artist_annotation.user_id = ?)", userID)
+	}
+	return sq
+}
+
+// addCriteria applies the where conditions, limit, offset, and order by clauses to the SQL query based on the
+// smart playlist criteria.
+func (r *playlistRepository) addCriteria(sql SelectBuilder, cSQL smartPlaylistCriteria) (SelectBuilder, error) {
+	cond, err := cSQL.Where()
+	if err != nil {
+		return sql, err
+	}
+	sql = sql.Where(cond)
+	if cSQL.Criteria.Limit > 0 {
+		sql = sql.Limit(uint64(cSQL.Criteria.Limit)).Offset(uint64(cSQL.Criteria.Offset))
+	}
+	if order := cSQL.OrderBy(); order != "" {
+		sql = sql.OrderBy(order)
+	}
+	return sql, nil
+}

persistence/smart_playlist_repository_test.go

@@ -0,0 +1,531 @@
+package persistence
+
+import (
+	"time"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/criteria"
+	"github.com/navidrome/navidrome/model/request"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"github.com/pocketbase/dbx"
+)
+
+var _ = Describe("PlaylistRepository - Smart Playlists", func() {
+	var repo model.PlaylistRepository
+
+	BeforeEach(func() {
+		ctx := log.NewContext(GinkgoT().Context())
+		ctx = request.WithUser(ctx, model.User{ID: "userid", UserName: "userid", IsAdmin: true})
+		repo = NewPlaylistRepository(ctx, GetDBXBuilder())
+	})
+
+	Context("Smart Playlists", func() {
+		var rules *criteria.Criteria
+		BeforeEach(func() {
+			rules = &criteria.Criteria{
+				Expression: criteria.All{
+					criteria.Contains{"title": "love"},
+				},
+			}
+		})
+		Context("valid rules", func() {
+			Specify("Put/Get", func() {
+				newPls := model.Playlist{Name: "Great!", OwnerID: "userid", Rules: rules}
+				Expect(repo.Put(&newPls)).To(Succeed())
+				DeferCleanup(func() { _ = repo.Delete(newPls.ID) })
+
+				savedPls, err := repo.Get(newPls.ID)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(savedPls.Rules).To(Equal(rules))
+			})
+		})
+
+		Context("invalid rules", func() {
+			It("fails to Put it in the DB", func() {
+				rules = &criteria.Criteria{
+					// This is invalid because "contains" cannot have multiple fields
+					Expression: criteria.All{
+						criteria.Contains{"genre": "Hardcore", "filetype": "mp3"},
+					},
+				}
+				newPls := model.Playlist{Name: "Great!", OwnerID: "userid", Rules: rules}
+				Expect(repo.Put(&newPls)).To(MatchError(ContainSubstring("invalid criteria expression")))
+			})
+		})
+
+		Context("child smart playlists", func() {
+			BeforeEach(func() {
+				DeferCleanup(configtest.SetupConfig())
+			})
+
+			When("refresh delay has expired", func() {
+				It("should refresh tracks for smart playlist referenced in parent smart playlist criteria", func() {
+					conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second
+
+					childRules := &criteria.Criteria{
+						Expression: criteria.All{
+							criteria.Contains{"title": "Day"},
+						},
+					}
+					nestedPls := model.Playlist{Name: "Nested", OwnerID: "userid", Public: true, Rules: childRules}
+					Expect(repo.Put(&nestedPls)).To(Succeed())
+					DeferCleanup(func() { _ = repo.Delete(nestedPls.ID) })
+
+					parentPls := model.Playlist{Name: "Parent", OwnerID: "userid", Rules: &criteria.Criteria{
+						Expression: criteria.All{
+							criteria.InPlaylist{"id": nestedPls.ID},
+						},
+					}}
+					Expect(repo.Put(&parentPls)).To(Succeed())
+					DeferCleanup(func() { _ = repo.Delete(parentPls.ID) })
+
+					// Nested playlist has not been evaluated yet
+					nestedPlsRead, err := repo.Get(nestedPls.ID)
+					Expect(err).ToNot(HaveOccurred())
+					Expect(nestedPlsRead.EvaluatedAt).To(BeNil())
+
+					// Getting parent with refresh should recursively refresh the nested playlist
+					pls, err := repo.GetWithTracks(parentPls.ID, true, false)
+					Expect(err).ToNot(HaveOccurred())
+					Expect(pls.EvaluatedAt).ToNot(BeNil())
+					Expect(*pls.EvaluatedAt).To(BeTemporally("~", time.Now(), 2*time.Second))
+
+					// Parent should have tracks from the nested playlist
+					Expect(pls.Tracks).To(HaveLen(1))
+					Expect(pls.Tracks[0].MediaFileID).To(Equal(songDayInALife.ID))
+
+					// Nested playlist should now have been refreshed (EvaluatedAt set)
+					nestedPlsAfterParentGet, err := repo.Get(nestedPls.ID)
+					Expect(err).ToNot(HaveOccurred())
+					Expect(nestedPlsAfterParentGet.EvaluatedAt).ToNot(BeNil())
+					Expect(*nestedPlsAfterParentGet.EvaluatedAt).To(BeTemporally("~", time.Now(), 2*time.Second))
+				})
+			})
+
+			When("refresh delay has not expired", func() {
+				It("should NOT refresh tracks for smart playlist referenced in parent smart playlist criteria", func() {
+					conf.Server.SmartPlaylistRefreshDelay = 1 * time.Hour
+					childEvaluatedAt := time.Now().Add(-30 * time.Minute)
+
+					childRules := &criteria.Criteria{
+						Expression: criteria.All{
+							criteria.Contains{"title": "Day"},
+						},
+					}
+					nestedPls := model.Playlist{Name: "Nested", OwnerID: "userid", Public: true, Rules: childRules, EvaluatedAt: &childEvaluatedAt}
+					Expect(repo.Put(&nestedPls)).To(Succeed())
+					DeferCleanup(func() { _ = repo.Delete(nestedPls.ID) })
+
+					// Parent has no EvaluatedAt, so it WILL refresh, but the child should not
+					parentPls := model.Playlist{Name: "Parent", OwnerID: "userid", Rules: &criteria.Criteria{
+						Expression: criteria.All{
+							criteria.InPlaylist{"id": nestedPls.ID},
+						},
+					}}
+					Expect(repo.Put(&parentPls)).To(Succeed())
+					DeferCleanup(func() { _ = repo.Delete(parentPls.ID) })
+
+					nestedPlsRead, err := repo.Get(nestedPls.ID)
+					Expect(err).ToNot(HaveOccurred())
+
+					// Getting parent with refresh should NOT recursively refresh the nested playlist
+					parent, err := repo.GetWithTracks(parentPls.ID, true, false)
+					Expect(err).ToNot(HaveOccurred())
+
+					// Parent should have been refreshed (its EvaluatedAt was nil)
+					Expect(parent.EvaluatedAt).ToNot(BeNil())
+					Expect(*parent.EvaluatedAt).To(BeTemporally("~", time.Now(), 2*time.Second))
+
+					// Nested playlist should NOT have been refreshed (still within delay window)
+					nestedPlsAfterParentGet, err := repo.Get(nestedPls.ID)
+					Expect(err).ToNot(HaveOccurred())
+					Expect(*nestedPlsAfterParentGet.EvaluatedAt).To(BeTemporally("~", childEvaluatedAt, time.Second))
+					Expect(*nestedPlsAfterParentGet.EvaluatedAt).To(Equal(*nestedPlsRead.EvaluatedAt))
+				})
+			})
+		})
+	})
+
+	Describe("Playlist Track Sorting", func() {
+		var testPlaylistID string
+
+		AfterEach(func() {
+			if testPlaylistID != "" {
+				Expect(repo.Delete(testPlaylistID)).To(BeNil())
+				testPlaylistID = ""
+			}
+		})
+
+		It("sorts tracks correctly by album (disc and track number)", func() {
+			By("creating a playlist with multi-disc album tracks in arbitrary order")
+			newPls := model.Playlist{Name: "Multi-Disc Test", OwnerID: "userid"}
+			// Add tracks in intentionally scrambled order
+			newPls.AddMediaFilesByID([]string{"2001", "2002", "2003", "2004"})
+			Expect(repo.Put(&newPls)).To(Succeed())
+			testPlaylistID = newPls.ID
+
+			By("retrieving tracks sorted by album")
+			tracksRepo := repo.Tracks(newPls.ID, false)
+			tracks, err := tracksRepo.GetAll(model.QueryOptions{Sort: "album", Order: "asc"})
+			Expect(err).ToNot(HaveOccurred())
+
+			By("verifying tracks are sorted by disc number then track number")
+			Expect(tracks).To(HaveLen(4))
+			// Expected order: Disc 1 Track 1, Disc 1 Track 2, Disc 2 Track 1, Disc 2 Track 11
+			Expect(tracks[0].MediaFileID).To(Equal("2002")) // Disc 1, Track 1
+			Expect(tracks[1].MediaFileID).To(Equal("2004")) // Disc 1, Track 2
+			Expect(tracks[2].MediaFileID).To(Equal("2003")) // Disc 2, Track 1
+			Expect(tracks[3].MediaFileID).To(Equal("2001")) // Disc 2, Track 11
+		})
+	})
+
+	Describe("Smart Playlists with Album/Artist Annotation Criteria", func() {
+		var testPlaylistID string
+
+		AfterEach(func() {
+			if testPlaylistID != "" {
+				_ = repo.Delete(testPlaylistID)
+				testPlaylistID = ""
+			}
+		})
+
+		It("matches tracks from starred albums using albumLoved", func() {
+			// albumRadioactivity (ID "103") is starred in test fixtures
+			// Songs in album 103: 1003, 1004, 1005, 1006
+			rules := &criteria.Criteria{
+				Expression: criteria.All{
+					criteria.Is{"albumLoved": true},
+				},
+			}
+			newPls := model.Playlist{Name: "Starred Album Songs", OwnerID: "userid", Rules: rules}
+			Expect(repo.Put(&newPls)).To(Succeed())
+			testPlaylistID = newPls.ID
+
+			conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second
+			pls, err := repo.GetWithTracks(newPls.ID, true, false)
+			Expect(err).ToNot(HaveOccurred())
+
+			trackIDs := make([]string, len(pls.Tracks))
+			for i, t := range pls.Tracks {
+				trackIDs[i] = t.MediaFileID
+			}
+			Expect(trackIDs).To(ConsistOf("1003", "1004", "1005", "1006"))
+		})
+
+		It("matches tracks from starred artists using artistLoved", func() {
+			// artistBeatles (ID "3") is starred in test fixtures
+			// Songs with ArtistID "3": 1001, 1002, 3002
+			rules := &criteria.Criteria{
+				Expression: criteria.All{
+					criteria.Is{"artistLoved": true},
+				},
+			}
+			newPls := model.Playlist{Name: "Starred Artist Songs", OwnerID: "userid", Rules: rules}
+			Expect(repo.Put(&newPls)).To(Succeed())
+			testPlaylistID = newPls.ID
+
+			conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second
+			pls, err := repo.GetWithTracks(newPls.ID, true, false)
+			Expect(err).ToNot(HaveOccurred())
+
+			trackIDs := make([]string, len(pls.Tracks))
+			for i, t := range pls.Tracks {
+				trackIDs[i] = t.MediaFileID
+			}
+			Expect(trackIDs).To(ConsistOf("1001", "1002", "3002"))
+		})
+
+		It("matches tracks with combined album and artist criteria", func() {
+			// albumLoved=true → songs from album 103 (1003, 1004, 1005, 1006)
+			// artistLoved=true → songs with artist 3 (1001, 1002)
+			// Using Any: union of both sets
+			rules := &criteria.Criteria{
+				Expression: criteria.Any{
+					criteria.Is{"albumLoved": true},
+					criteria.Is{"artistLoved": true},
+				},
+			}
+			newPls := model.Playlist{Name: "Combined Album+Artist", OwnerID: "userid", Rules: rules}
+			Expect(repo.Put(&newPls)).To(Succeed())
+			testPlaylistID = newPls.ID
+
+			conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second
+			pls, err := repo.GetWithTracks(newPls.ID, true, false)
+			Expect(err).ToNot(HaveOccurred())
+
+			trackIDs := make([]string, len(pls.Tracks))
+			for i, t := range pls.Tracks {
+				trackIDs[i] = t.MediaFileID
+			}
+			Expect(trackIDs).To(ConsistOf("1001", "1002", "1003", "1004", "1005", "1006", "3002"))
+		})
+
+		It("returns no tracks when no albums/artists match", func() {
+			// No album has rating 5 in fixtures
+			rules := &criteria.Criteria{
+				Expression: criteria.All{
+					criteria.Is{"albumRating": 5},
+				},
+			}
+			newPls := model.Playlist{Name: "No Match", OwnerID: "userid", Rules: rules}
+			Expect(repo.Put(&newPls)).To(Succeed())
+			testPlaylistID = newPls.ID
+
+			conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second
+			pls, err := repo.GetWithTracks(newPls.ID, true, false)
+			Expect(err).ToNot(HaveOccurred())
+
+			Expect(pls.Tracks).To(BeEmpty())
+		})
+	})
+
+	Describe("Smart Playlists with Tag Criteria", func() {
+		var mfRepo model.MediaFileRepository
+		var testPlaylistID string
+		var songWithGrouping, songWithoutGrouping model.MediaFile
+
+		BeforeEach(func() {
+			ctx := log.NewContext(GinkgoT().Context())
+			ctx = request.WithUser(ctx, model.User{ID: "userid", UserName: "userid", IsAdmin: true})
+			mfRepo = NewMediaFileRepository(ctx, GetDBXBuilder())
+
+			// Register 'grouping' as a valid tag for smart playlists
+			criteria.AddTagNames([]string{"grouping"})
+
+			// Create a song with the grouping tag
+			songWithGrouping = model.MediaFile{
+				ID:       "test-grouping-1",
+				Title:    "Song With Grouping",
+				Artist:   "Test Artist",
+				ArtistID: "1",
+				Album:    "Test Album",
+				AlbumID:  "101",
+				Path:     "test/grouping/song1.mp3",
+				Tags: model.Tags{
+					"grouping": []string{"My Crate"},
+				},
+				Participants: model.Participants{},
+				LibraryID:    1,
+				Lyrics:       "[]",
+			}
+			Expect(mfRepo.Put(&songWithGrouping)).To(Succeed())
+
+			// Create a song without the grouping tag
+			songWithoutGrouping = model.MediaFile{
+				ID:           "test-grouping-2",
+				Title:        "Song Without Grouping",
+				Artist:       "Test Artist",
+				ArtistID:     "1",
+				Album:        "Test Album",
+				AlbumID:      "101",
+				Path:         "test/grouping/song2.mp3",
+				Tags:         model.Tags{},
+				Participants: model.Participants{},
+				LibraryID:    1,
+				Lyrics:       "[]",
+			}
+			Expect(mfRepo.Put(&songWithoutGrouping)).To(Succeed())
+		})
+
+		AfterEach(func() {
+			if testPlaylistID != "" {
+				_ = repo.Delete(testPlaylistID)
+				testPlaylistID = ""
+			}
+			// Clean up test media files
+			_, _ = GetDBXBuilder().Delete("media_file", dbx.HashExp{"id": "test-grouping-1"}).Execute()
+			_, _ = GetDBXBuilder().Delete("media_file", dbx.HashExp{"id": "test-grouping-2"}).Execute()
+		})
+
+		It("matches tracks with a tag value using 'contains' with empty string (issue #4728 workaround)", func() {
+			By("creating a smart playlist that checks if grouping tag has any value")
+			// This is the workaround for issue #4728: using 'contains' with empty string
+			// generates SQL: value LIKE '%%' which matches any non-empty string
+			rules := &criteria.Criteria{
+				Expression: criteria.All{
+					criteria.Contains{"grouping": ""},
+				},
+			}
+			newPls := model.Playlist{Name: "Tracks with Grouping", OwnerID: "userid", Rules: rules}
+			Expect(repo.Put(&newPls)).To(Succeed())
+			testPlaylistID = newPls.ID
+
+			By("refreshing the smart playlist")
+			conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second // Force refresh
+			pls, err := repo.GetWithTracks(newPls.ID, true, false)
+			Expect(err).ToNot(HaveOccurred())
+
+			By("verifying only the track with grouping tag is matched")
+			Expect(pls.Tracks).To(HaveLen(1))
+			Expect(pls.Tracks[0].MediaFileID).To(Equal(songWithGrouping.ID))
+		})
+
+		It("excludes tracks with a tag value using 'notContains' with empty string", func() {
+			By("creating a smart playlist that checks if grouping tag is NOT set")
+			rules := &criteria.Criteria{
+				Expression: criteria.All{
+					criteria.NotContains{"grouping": ""},
+				},
+			}
+			newPls := model.Playlist{Name: "Tracks without Grouping", OwnerID: "userid", Rules: rules}
+			Expect(repo.Put(&newPls)).To(Succeed())
+			testPlaylistID = newPls.ID
+
+			By("refreshing the smart playlist")
+			conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second // Force refresh
+			pls, err := repo.GetWithTracks(newPls.ID, true, false)
+			Expect(err).ToNot(HaveOccurred())
+
+			By("verifying the track with grouping is NOT in the playlist")
+			for _, track := range pls.Tracks {
+				Expect(track.MediaFileID).ToNot(Equal(songWithGrouping.ID))
+			}
+
+			By("verifying the track without grouping IS in the playlist")
+			var foundWithoutGrouping bool
+			for _, track := range pls.Tracks {
+				if track.MediaFileID == songWithoutGrouping.ID {
+					foundWithoutGrouping = true
+					break
+				}
+			}
+			Expect(foundWithoutGrouping).To(BeTrue())
+		})
+	})
+
+	Describe("Smart Playlists Library Filtering", func() {
+		var mfRepo model.MediaFileRepository
+		var testPlaylistID string
+		var lib2ID int
+		var restrictedUserID string
+		var uniqueLibPath string
+
+		BeforeEach(func() {
+			db := GetDBXBuilder()
+
+			// Generate unique IDs for this test run
+			uniqueSuffix := time.Now().Format("20060102150405.000")
+			restrictedUserID = "restricted-user-" + uniqueSuffix
+			uniqueLibPath = "/music/lib2-" + uniqueSuffix
+
+			// Create a second library with unique name and path to avoid conflicts with other tests
+			_, err := db.DB().Exec("INSERT INTO library (name, path, created_at, updated_at) VALUES (?, ?, datetime('now'), datetime('now'))", "Library 2-"+uniqueSuffix, uniqueLibPath)
+			Expect(err).ToNot(HaveOccurred())
+			err = db.DB().QueryRow("SELECT last_insert_rowid()").Scan(&lib2ID)
+			Expect(err).ToNot(HaveOccurred())
+
+			// Create a restricted user with access only to library 1
+			_, err = db.DB().Exec("INSERT INTO user (id, user_name, name, is_admin, password, created_at, updated_at) VALUES (?, ?, 'Restricted User', false, 'pass', datetime('now'), datetime('now'))", restrictedUserID, restrictedUserID)
+			Expect(err).ToNot(HaveOccurred())
+			_, err = db.DB().Exec("INSERT INTO user_library (user_id, library_id) VALUES (?, 1)", restrictedUserID)
+			Expect(err).ToNot(HaveOccurred())
+
+			// Create test media files in each library
+			ctx := log.NewContext(GinkgoT().Context())
+			ctx = request.WithUser(ctx, model.User{ID: "userid", UserName: "userid", IsAdmin: true})
+			mfRepo = NewMediaFileRepository(ctx, db)
+
+			// Song in library 1 (accessible by restricted user)
+			songLib1 := model.MediaFile{
+				ID:           "lib1-song",
+				Title:        "Song in Lib1",
+				Artist:       "Test Artist",
+				ArtistID:     "1",
+				Album:        "Test Album",
+				AlbumID:      "101",
+				Path:         "lib1/song.mp3",
+				LibraryID:    1,
+				Participants: model.Participants{},
+				Tags:         model.Tags{},
+				Lyrics:       "[]",
+			}
+			Expect(mfRepo.Put(&songLib1)).To(Succeed())
+
+			// Song in library 2 (NOT accessible by restricted user)
+			songLib2 := model.MediaFile{
+				ID:           "lib2-song",
+				Title:        "Song in Lib2",
+				Artist:       "Test Artist",
+				ArtistID:     "1",
+				Album:        "Test Album",
+				AlbumID:      "101",
+				Path:         "lib2/song.mp3",
+				LibraryID:    lib2ID,
+				Participants: model.Participants{},
+				Tags:         model.Tags{},
+				Lyrics:       "[]",
+			}
+			Expect(mfRepo.Put(&songLib2)).To(Succeed())
+		})
+
+		AfterEach(func() {
+			db := GetDBXBuilder()
+			if testPlaylistID != "" {
+				_ = repo.Delete(testPlaylistID)
+				testPlaylistID = ""
+			}
+			// Clean up test data
+			_, _ = db.Delete("media_file", dbx.HashExp{"id": "lib1-song"}).Execute()
+			_, _ = db.Delete("media_file", dbx.HashExp{"id": "lib2-song"}).Execute()
+			_, _ = db.Delete("user_library", dbx.HashExp{"user_id": restrictedUserID}).Execute()
+			_, _ = db.Delete("user", dbx.HashExp{"id": restrictedUserID}).Execute()
+			_, _ = db.DB().Exec("DELETE FROM library WHERE id = ?", lib2ID)
+		})
+
+		It("should only include tracks from libraries the user has access to (issue #4738)", func() {
+			db := GetDBXBuilder()
+			ctx := log.NewContext(GinkgoT().Context())
+
+			// Create the smart playlist as the restricted user
+			restrictedUser := model.User{ID: restrictedUserID, UserName: restrictedUserID, IsAdmin: false}
+			ctx = request.WithUser(ctx, restrictedUser)
+			restrictedRepo := NewPlaylistRepository(ctx, db)
+
+			// Create a smart playlist that matches all songs
+			rules := &criteria.Criteria{
+				Expression: criteria.All{
+					criteria.Gt{"playCount": -1}, // Matches everything
+				},
+			}
+			newPls := model.Playlist{Name: "All Songs", OwnerID: restrictedUserID, Rules: rules}
+			Expect(restrictedRepo.Put(&newPls)).To(Succeed())
+			testPlaylistID = newPls.ID
+
+			By("refreshing the smart playlist")
+			conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second // Force refresh
+			pls, err := restrictedRepo.GetWithTracks(newPls.ID, true, false)
+			Expect(err).ToNot(HaveOccurred())
+
+			By("verifying only the track from library 1 is in the playlist")
+			var foundLib1Song, foundLib2Song bool
+			for _, track := range pls.Tracks {
+				if track.MediaFileID == "lib1-song" {
+					foundLib1Song = true
+				}
+				if track.MediaFileID == "lib2-song" {
+					foundLib2Song = true
+				}
+			}
+			Expect(foundLib1Song).To(BeTrue(), "Song from library 1 should be in the playlist")
+			Expect(foundLib2Song).To(BeFalse(), "Song from library 2 should NOT be in the playlist")
+
+			By("verifying playlist_tracks table only contains the accessible track")
+			var playlistTracksCount int
+			err = db.DB().QueryRow("SELECT count(*) FROM playlist_tracks WHERE playlist_id = ?", newPls.ID).Scan(&playlistTracksCount)
+			Expect(err).ToNot(HaveOccurred())
+			// Count should only include tracks visible to the user (lib1-song)
+			// The count may include other test songs from library 1, but NOT lib2-song
+			var lib2TrackCount int
+			err = db.DB().QueryRow("SELECT count(*) FROM playlist_tracks WHERE playlist_id = ? AND media_file_id = 'lib2-song'", newPls.ID).Scan(&lib2TrackCount)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(lib2TrackCount).To(Equal(0), "lib2-song should not be in playlist_tracks")
+
+			By("verifying SongCount matches visible tracks")
+			Expect(pls.SongCount).To(Equal(len(pls.Tracks)), "SongCount should match the number of visible tracks")
+		})
+	})
+})

persistence/sql_search_fts.go

@@ -8,6 +8,7 @@ import (
 	"unicode/utf8"
 
 	. "github.com/Masterminds/squirrel"
+	"github.com/deluan/sanitize"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 )
@@ -44,24 +45,33 @@ var fts5Operators = regexp.MustCompile(`(?i)\b(AND|OR|NOT|NEAR)\b`)
 // fts5LeadingStar matches a * at the start of a token. FTS5 only supports * at the end (prefix queries).
 var fts5LeadingStar = regexp.MustCompile(`(^|[\s])\*+`)
 
-// normalizeForFTS takes multiple strings, strips non-letter/non-number characters from each word,
-// and returns a space-separated string of words that changed after stripping (deduplicated).
-// This is used at index time to create concatenated forms: "R.E.M." → "REM", "AC/DC" → "ACDC".
+// normalizeForFTS takes multiple strings and returns a space-separated, deduplicated list of
+// alternative searchable forms for each word: punctuation-stripped (R.E.M. → REM, AC/DC → ACDC)
+// and ASCII-transliterated (Bjørk → Bjork, œuvre → oeuvre). The transliterated form is needed
+// because FTS5's `unicode61 remove_diacritics 2` only handles NFKD-decomposable diacritics —
+// atomic letters like ø/æ/œ/ß survive tokenization, so the query side and index side disagree
+// without an explicit transliterated entry here.
 func normalizeForFTS(values ...string) string {
 	seen := make(map[string]struct{})
 	var result []string
+	add := func(orig, variant string) {
+		if variant == "" || variant == orig {
+			return
+		}
+		lower := strings.ToLower(variant)
+		if _, ok := seen[lower]; ok {
+			return
+		}
+		seen[lower] = struct{}{}
+		result = append(result, variant)
+	}
 	for _, v := range values {
 		for _, word := range strings.Fields(v) {
-			stripped := fts5PunctStrip.ReplaceAllString(word, "")
-			if stripped == "" || stripped == word {
-				continue
-			}
-			lower := strings.ToLower(stripped)
-			if _, ok := seen[lower]; ok {
-				continue
-			}
-			seen[lower] = struct{}{}
-			result = append(result, stripped)
+			transliterated := sanitize.Accents(word)
+			// Concatenated ASCII form: R.E.M. → REM, AC/DC → ACDC, St-Étienne → StEtienne.
+			add(word, fts5PunctStrip.ReplaceAllString(transliterated, ""))
+			// Accent-only transliteration for words without name-punctuation (Bjørk → Bjork).
+			add(word, transliterated)
 		}
 	}
 	return strings.Join(result, " ")
@@ -158,6 +168,13 @@ func buildFTS5Query(userInput string) string {
 		result = result[:start] + fmt.Sprintf("\x00PHRASE%d\x00", len(phrases)-1) + result[end+1:]
 	}
 
+	// Transliterate non-ASCII letters in the unquoted portion (ø→o, æ→ae, œ→oe, ß→ss, …)
+	// so the query matches the ASCII variants emitted by normalizeForFTS at index time.
+	// FTS5's own `remove_diacritics 2` only strips NFKD-decomposable marks, so without
+	// this step queries for words containing these letters can miss. Quoted phrases are
+	// left untouched so they continue to match the original text in title/artist columns.
+	result = sanitize.Accents(result)
+
 	// Neutralize FTS5 operators by lowercasing them (FTS5 operators are case-sensitive:
 	// AND, OR, NOT, NEAR are operators, but and, or, not, near are plain tokens)
 	result = fts5Operators.ReplaceAllStringFunc(result, strings.ToLower)

persistence/sql_search_fts_test.go

@@ -37,7 +37,13 @@ var _ = DescribeTable("buildFTS5Query",
 	Entry("handles punctuated word mixed with plain words", "best of a-ha", `best* AND of* AND ("a ha" OR aha*)`),
 	Entry("handles contraction followed by plain words", "you've got", `("you ve" OR youve*) AND got*`),
 	Entry("strips miscellaneous punctuation", "rock & roll, vol. 2", "rock* AND roll* AND vol* AND 2*"),
-	Entry("preserves unicode characters with diacritics", "Björk début", "Björk* AND début*"),
+	Entry("transliterates NFKD-decomposable diacritics", "Björk début", "Bjork* AND debut*"),
+	Entry("transliterates ø to o", "Øystein", "Oystein*"),
+	Entry("transliterates œ ligature to oe", "œuvre", "oeuvre*"),
+	Entry("transliterates æ ligature to ae", "Brennæ", "Brennae*"),
+	Entry("transliterates mixed unicode words", "Mø Sigur Rós", "Mo* AND Sigur* AND Ros*"),
+	Entry("transliterates ß to ss", "Straße", "Strasse*"),
+	Entry("preserves quoted unicode phrase verbatim", `"Björk"`, `"Björk"`),
 	Entry("collapses dotted abbreviation into phrase", "R.E.M.", `"R E M"`),
 	Entry("collapses abbreviation without trailing dot", "R.E.M", `"R E M"`),
 	Entry("collapses abbreviation mixed with words", "best of R.E.M.", `best* AND of* AND "R E M"`),
@@ -75,11 +81,19 @@ var _ = DescribeTable("normalizeForFTS",
 	Entry("strips dots and concatenates", "REM", "R.E.M."),
 	Entry("strips slash", "ACDC", "AC/DC"),
 	Entry("strips hyphen", "Aha", "A-ha"),
-	Entry("skips unchanged words", "", "The Beatles"),
+	Entry("skips unchanged ASCII words", "", "The Beatles"),
 	Entry("handles mixed input", "REM", "R.E.M.", "Automatic for the People"),
 	Entry("deduplicates", "REM", "R.E.M.", "R.E.M."),
 	Entry("strips apostrophe from word", "N", "Guns N' Roses"),
 	Entry("handles multiple values with punctuation", "REM ACDC", "R.E.M.", "AC/DC"),
+	Entry("transliterates ø to o", "Bjork", "Bjørk"),
+	Entry("transliterates Ø to O", "Oystein", "Øystein"),
+	Entry("transliterates œ ligature to oe", "oeuvre", "œuvre"),
+	Entry("transliterates Latin diacritics", "cafe", "café"),
+	Entry("transliterates only the non-ASCII words", "Mo Ros", "Mø Rós"),
+	Entry("combines punctuation strip and transliteration", "StEtienne St-Etienne", "St-Étienne"),
+	Entry("deduplicates against punctuation form", "Cafe", "Café", "Cafe"),
+	Entry("transliterates ß to ss", "Strasse", "Straße"),
 )
 
 var _ = DescribeTable("containsCJK",

plugins/README.md

@@ -1,8 +1,8 @@
 # Navidrome Plugin System
 
-Navidrome supports WebAssembly (Wasm) plugins for extending functionality. Plugins run in a secure sandbox and can provide metadata agents, scrobblers, and other integrations through host services like scheduling, caching, WebSockets, and Subsonic API access.
+Navidrome supports WebAssembly (Wasm) plugins for extending functionality. Plugins run in a secure sandbox and can provide metadata agents, scrobblers, lyrics providers, audio similarity, and other integrations through host services like scheduling, caching, task queues, WebSockets, and Subsonic API access.
 
-The plugin system is built on **[Extism](https://extism.org/)**, a cross-language framework for building WebAssembly plugins. This means you can write plugins in any language that Extism supports (Go, Rust, Python, TypeScript, and more) using their Plugin Development Kits (PDKs).
+The plugin system is built on **[Extism](https://extism.org/)**, a cross-language framework for building WebAssembly plugins. You can write plugins in any language that Extism supports (Go, Rust, Python, TypeScript, and more) using their Plugin Development Kits (PDKs).
 
 **Essential Extism Resources:**
 - [Extism Documentation](https://extism.org/docs/overview) – Core concepts and architecture
@@ -19,12 +19,18 @@ The plugin system is built on **[Extism](https://extism.org/)**, a cross-languag
 - [Capabilities](#capabilities)
   - [MetadataAgent](#metadataagent)
   - [Scrobbler](#scrobbler)
+  - [Lyrics](#lyrics)
+  - [SonicSimilarity](#sonicsimilarity)
+  - [TaskWorker](#taskworker)
   - [Lifecycle](#lifecycle)
+  - [SchedulerCallback](#schedulercallback)
+  - [WebSocketCallback](#websocketcallback)
 - [Host Services](#host-services)
-  - [HTTP Requests](#http-requests)
+  - [HTTP](#http)
   - [Scheduler](#scheduler)
   - [Cache](#cache)
   - [KVStore](#kvstore)
+  - [Task](#task)
   - [WebSocket](#websocket)
   - [Library](#library)
   - [Artwork](#artwork)
@@ -95,14 +101,6 @@ A Navidrome plugin is an `.ndp` package file (zip archive) containing:
 1. **`manifest.json`** – Plugin metadata (name, author, version, permissions)
 2. **`plugin.wasm`** – Compiled WebAssembly module with capability functions
 
-### Plugin Package Structure
-
-```
-my-plugin.ndp (zip archive)
-├── manifest.json    # Required: Plugin metadata
-└── plugin.wasm      # Required: Compiled WebAssembly module
-```
-
 ### Plugin Naming
 
 Plugins are identified by their **filename** (without `.ndp` extension), not the manifest `name` field:
@@ -123,6 +121,10 @@ Every plugin must include a `manifest.json` file. Example:
   "version": "1.0.0",
   "description": "What this plugin does",
   "website": "https://example.com",
+  "config": {
+    "schema": { ... },
+    "uiSchema": { ... }
+  },
   "permissions": {
     "http": {
       "reason": "Fetch metadata from external API",
@@ -134,6 +136,30 @@ Every plugin must include a `manifest.json` file. Example:
 
 **Required fields:** `name`, `author`, `version`
 
+**Optional fields:** `description`, `website`, `config`, `permissions`, `experimental`
+
+#### Config Definition
+
+The `config` field defines the plugin's configuration schema using [JSON Schema (draft-07)](https://json-schema.org/) and an optional [JSONForms](https://jsonforms.io/) UI schema for rendering in the Navidrome web UI:
+
+```json
+{
+  "config": {
+    "schema": {
+      "type": "object",
+      "properties": {
+        "api_key": { "type": "string", "title": "API Key" },
+        "max_retries": { "type": "integer", "default": 3 }
+      },
+      "required": ["api_key"]
+    },
+    "uiSchema": {
+      "api_key": { "ui:widget": "password" }
+    }
+  }
+}
+```
+
 #### Experimental Features
 
 Plugins can opt-in to experimental WebAssembly features that may change or be removed in future versions. Currently supported:
@@ -142,9 +168,6 @@ Plugins can opt-in to experimental WebAssembly features that may change or be re
 
 ```json
 {
-  "name": "Threaded Plugin",
-  "author": "Author Name",
-  "version": "1.0.0",
   "experimental": {
     "threads": {
       "reason": "Required for concurrent audio processing"
@@ -159,50 +182,25 @@ Plugins can opt-in to experimental WebAssembly features that may change or be re
 
 ## Capabilities
 
-Capabilities define what your plugin can do. They're automatically detected based on which functions you export.
+Capabilities define what your plugin can do. They're automatically detected based on which functions you export. A plugin can implement multiple capabilities.
 
 ### MetadataAgent
 
-Provides artist and album metadata. Export one or more of these functions:
+Provides artist and album metadata. All methods are **optional** — implement only the ones your data source supports.
 
-| Function                  | Input                      | Output                           | Description          |
-|---------------------------|----------------------------|----------------------------------|----------------------|
-| `nd_get_artist_mbid`      | `{id, name}`               | `{mbid}`                         | Get MusicBrainz ID   |
-| `nd_get_artist_url`       | `{id, name, mbid?}`        | `{url}`                          | Get artist URL       |
-| `nd_get_artist_biography` | `{id, name, mbid?}`        | `{biography}`                    | Get artist biography |
-| `nd_get_similar_artists`  | `{id, name, mbid?, limit}` | `{artists: [{name, mbid?}]}`     | Get similar artists  |
-| `nd_get_artist_images`    | `{id, name, mbid?}`        | `{images: [{url, size}]}`        | Get artist images    |
-| `nd_get_artist_top_songs` | `{id, name, mbid?, count}` | `{songs: [{name, mbid?}]}`       | Get top songs        |
-| `nd_get_album_info`       | `{name, artist, mbid?}`    | `{name, mbid, description, url}` | Get album info       |
-| `nd_get_album_images`     | `{name, artist, mbid?}`    | `{images: [{url, size}]}`        | Get album images     |
-
-**Example:**
-
-```go
-type ArtistInput struct {
-    ID   string `json:"id"`
-    Name string `json:"name"`
-    MBID string `json:"mbid,omitempty"`
-}
-
-type BiographyOutput struct {
-    Biography string `json:"biography"`
-}
-
-//go:wasmexport nd_get_artist_biography
-func ndGetArtistBiography() int32 {
-    var input ArtistInput
-    if err := pdk.InputJSON(&input); err != nil {
-        pdk.SetError(err)
-        return 1
-    }
-
-    // Fetch biography from your data source...
-    output := BiographyOutput{Biography: "Artist biography..."}
-    pdk.OutputJSON(output)
-    return 0
-}
-```
+| Function                          | Input                      | Output                           | Description              |
+|-----------------------------------|----------------------------|----------------------------------|--------------------------|
+| `nd_get_artist_mbid`              | `{id, name}`               | `{mbid}`                         | Get MusicBrainz ID       |
+| `nd_get_artist_url`               | `{id, name, mbid?}`        | `{url}`                          | Get artist URL           |
+| `nd_get_artist_biography`         | `{id, name, mbid?}`        | `{biography}`                    | Get artist biography     |
+| `nd_get_similar_artists`          | `{id, name, mbid?, limit}` | `{artists: [{name, mbid?}]}`     | Get similar artists      |
+| `nd_get_artist_images`            | `{id, name, mbid?}`        | `{images: [{url, size}]}`        | Get artist images        |
+| `nd_get_artist_top_songs`         | `{id, name, mbid?, count}` | `{songs: [{name, mbid?}]}`       | Get top songs            |
+| `nd_get_album_info`               | `{name, artist, mbid?}`    | `{name, mbid, description, url}` | Get album info           |
+| `nd_get_album_images`             | `{name, artist, mbid?}`    | `{images: [{url, size}]}`        | Get album images         |
+| `nd_get_similar_songs_by_track`   | `{id, name, artist, ...}`  | `{songs: [{name, artist}]}`      | Similar songs by track   |
+| `nd_get_similar_songs_by_album`   | `{id, name, artist, ...}`  | `{songs: [{name, artist}]}`      | Similar songs by album   |
+| `nd_get_similar_songs_by_artist`  | `{id, name, mbid?, count}` | `{songs: [{name, artist}]}`      | Similar songs by artist  |
 
 To use the plugin as a metadata agent, add it to your config:
 
@@ -210,17 +208,49 @@ To use the plugin as a metadata agent, add it to your config:
 Agents = "lastfm,spotify,my-plugin"
 ```
 
+**Example (using Go PDK package):**
+
+```go
+package main
+
+import "github.com/navidrome/navidrome/plugins/pdk/go/metadata"
+
+type myPlugin struct{}
+
+func (p *myPlugin) GetArtistBiography(input metadata.ArtistRequest) (*metadata.ArtistBiographyResponse, error) {
+    return &metadata.ArtistBiographyResponse{Biography: "Biography text..."}, nil
+}
+
+func init() { metadata.Register(&myPlugin{}) }
+func main() {}
+```
+
+**Example (raw wasmexport):**
+
+```go
+//go:wasmexport nd_get_artist_biography
+func ndGetArtistBiography() int32 {
+    var input ArtistInput
+    if err := pdk.InputJSON(&input); err != nil {
+        pdk.SetError(err)
+        return 1
+    }
+    pdk.OutputJSON(BiographyOutput{Biography: "Artist biography..."})
+    return 0
+}
+```
+
 ### Scrobbler
 
-Integrates with external scrobbling services. Export one or more of these functions:
+Integrates with external scrobbling services. All three methods are **required**.
 
-| Function                     | Input                 | Output         | Description                 |
-|------------------------------|-----------------------|----------------|-----------------------------|
-| `nd_scrobbler_is_authorized` | `{username}`          | `bool`         | Check if user is authorized |
-| `nd_scrobbler_now_playing`   | See below             | (none)         | Send now playing            |
-| `nd_scrobbler_scrobble`      | See below             | (none)         | Submit a scrobble           |
+| Function                     | Input                 | Output | Description                 |
+|------------------------------|-----------------------|--------|-----------------------------|
+| `nd_scrobbler_is_authorized` | `{username}`          | `bool` | Check if user is authorized |
+| `nd_scrobbler_now_playing`   | See below             | (none) | Send now playing            |
+| `nd_scrobbler_scrobble`      | See below             | (none) | Submit a scrobble           |
 
-> **Important:** Scrobbler plugins require the `users` permission in their manifest. Scrobble events are only sent for users assigned to the plugin through Navidrome's configuration. The `nd_scrobbler_is_authorized` function is called after the server-side user check passes.
+> **Important:** Scrobbler plugins require the `users` permission in their manifest. Scrobble events are only sent for users assigned to the plugin through Navidrome's configuration.
 
 **Manifest permission:**
 
@@ -267,31 +297,95 @@ On success, return `0`. On failure, use `pdk.SetError()` with one of these error
 ```go
 import "github.com/navidrome/navidrome/plugins/pdk/go/scrobbler"
 
-// Return error using predefined constants
 return scrobbler.ScrobblerErrorNotAuthorized
 return scrobbler.ScrobblerErrorRetryLater
 return scrobbler.ScrobblerErrorUnrecoverable
 ```
 
+### Lyrics
+
+Provides lyrics for tracks. The single method is **required**.
+
+| Function                | Input                         | Output                             | Description     |
+|-------------------------|-------------------------------|------------------------------------|-----------------|
+| `nd_lyrics_get_lyrics`  | `{artistName, title, ...}`    | `{lyrics: [{lang, text}]}`         | Get lyrics      |
+
+Each returned lyric entry has a `lang` (language code) and `text` field. Multiple entries can be returned for different languages.
+
+### SonicSimilarity
+
+Audio-similarity discovery based on acoustic features (e.g., embeddings). Both methods are **required**.
+
+| Function                        | Input                            | Output                                     | Description                           |
+|---------------------------------|----------------------------------|--------------------------------------------|---------------------------------------|
+| `nd_get_sonic_similar_tracks`   | `{song, count}`                  | `{matches: [{song, similarity}]}`          | Find acoustically similar tracks      |
+| `nd_find_sonic_path`            | `{startSong, endSong, count}`    | `{matches: [{song, similarity}]}`          | Find a path between two songs         |
+
+Each match contains a `song` reference and a `similarity` score (float64, 0.0–1.0).
+
+### TaskWorker
+
+Processes tasks from a queue. The method is **optional** — export it if your plugin uses the [Task](#task) host service for background work.
+
+| Function            | Input                                       | Output  | Description          |
+|---------------------|---------------------------------------------|---------|----------------------|
+| `nd_task_execute`   | `{queueName, taskID, payload, attempt}`     | `string`| Execute a queued task|
+
+The `payload` is raw bytes (the same bytes passed to `TaskEnqueue`). The `attempt` counter starts at 1 and increments on retries. Return a string result on success.
+
 ### Lifecycle
 
-Optional initialization callback. Export this function to run code when your plugin loads:
+Optional initialization callback. Called once after the plugin fully loads.
 
 | Function     | Input | Output     | Description                    |
 |--------------|-------|------------|--------------------------------|
 | `nd_on_init` | `{}`  | `{error?}` | Called once after plugin loads |
 
-Useful for initializing connections, scheduling recurring tasks, etc.
+Useful for initializing connections, scheduling recurring tasks, etc. Errors are logged but don't prevent the plugin from loading.
+
+### SchedulerCallback
+
+Receives scheduled task events. **Required** if your plugin uses the [Scheduler](#scheduler) host service.
+
+| Function                  | Input                                        | Output | Description                 |
+|---------------------------|----------------------------------------------|--------|-----------------------------|
+| `nd_scheduler_callback`   | `{scheduleId, payload, isRecurring}`         | (none) | Handle scheduled task event |
+
+### WebSocketCallback
+
+Receives WebSocket events. Export any subset of these to handle events from the [WebSocket](#websocket) host service.
+
+| Function                         | Input                           | Description                      |
+|----------------------------------|---------------------------------|----------------------------------|
+| `nd_websocket_on_text_message`   | `{connectionId, message}`       | Text message received            |
+| `nd_websocket_on_binary_message` | `{connectionId, data}`          | Binary message received (base64) |
+| `nd_websocket_on_error`          | `{connectionId, error}`         | Connection error                 |
+| `nd_websocket_on_close`          | `{connectionId, code, reason}`  | Connection closed                |
 
 ---
 
 ## Host Services
 
-Host services let your plugin call back into Navidrome for advanced functionality. Each service requires declaring the permission in your manifest.
+Host services let your plugin call back into Navidrome for advanced functionality. Each service (except [Config](#config)) requires declaring the corresponding permission in your manifest.
 
-### HTTP Requests
+### Go PDK Setup
 
-Make HTTP requests using the Extism PDK's built-in HTTP support. See your [Extism PDK documentation](https://extism.org/docs/concepts/pdk) for more details on making requests.
+All host service examples below use the generated Go SDK. Add this to your `go.mod`:
+
+```
+require github.com/navidrome/navidrome/plugins/pdk/go v0.0.0
+replace github.com/navidrome/navidrome/plugins/pdk/go => ../../pdk/go
+```
+
+Then import:
+
+```go
+import "github.com/navidrome/navidrome/plugins/pdk/go/host"
+```
+
+### HTTP
+
+Make HTTP requests to external services. This is a dedicated host service (separate from Extism's built-in HTTP support) with additional features like timeouts and redirect control.
 
 **Manifest permission:**
 
@@ -306,22 +400,28 @@ Make HTTP requests using the Extism PDK's built-in HTTP support. See your [Extis
 }
 ```
 
+**Host functions:**
+
+| Function    | Parameters                                               | Returns                          |
+|-------------|----------------------------------------------------------|----------------------------------|
+| `http_send` | `method, url, headers, body, timeoutMs, noFollowRedirects` | `statusCode, headers, body`    |
+
 **Usage:**
 
 ```go
-req := pdk.NewHTTPRequest(pdk.MethodGet, "https://api.example.com/data")
-req.SetHeader("Authorization", "Bearer " + apiKey)
-resp := req.Send()
-
-if resp.Status() == 200 {
-    data := resp.Body()
-    // Process response...
+resp, err := host.HTTPSend(host.HTTPRequest{
+    Method:  "GET",
+    URL:     "https://api.example.com/data",
+    Headers: map[string]string{"Authorization": "Bearer " + apiKey},
+})
+if resp.StatusCode == 200 {
+    // Process resp.Body
 }
 ```
 
 ### Scheduler
 
-Schedule one-time or recurring tasks. Your plugin must export `nd_scheduler_callback` to receive events.
+Schedule one-time or recurring tasks. Your plugin must export the [`nd_scheduler_callback`](#schedulercallback) function to receive events.
 
 **Manifest permission:**
 
@@ -343,40 +443,9 @@ Schedule one-time or recurring tasks. Your plugin must export `nd_scheduler_call
 | `scheduler_schedulerecurring` | `cronExpression, payload, scheduleId?`   | Schedule recurring callback |
 | `scheduler_cancelschedule`    | `scheduleId`                             | Cancel a scheduled task     |
 
-**Callback function:**
+**Usage:**
 
 ```go
-type SchedulerCallbackInput struct {
-    ScheduleID  string `json:"scheduleId"`
-    Payload     string `json:"payload"`
-    IsRecurring bool   `json:"isRecurring"`
-}
-
-//go:wasmexport nd_scheduler_callback
-func ndSchedulerCallback() int32 {
-    var input SchedulerCallbackInput
-    pdk.InputJSON(&input)
-
-    // Handle the scheduled task based on payload
-    pdk.Log(pdk.LogInfo, "Task fired: " + input.ScheduleID)
-    return 0
-}
-```
-
-**Scheduling tasks (using generated SDK):**
-
-Add the generated SDK to your `go.mod`:
-
-```
-require github.com/navidrome/navidrome/plugins/pdk/go v0.0.0
-replace github.com/navidrome/navidrome/plugins/pdk/go => ../../pdk/go
-```
-
-Then import and use:
-
-```go
-import "github.com/navidrome/navidrome/plugins/pdk/go/host"
-
 // Schedule one-time task in 60 seconds
 scheduleID, err := host.SchedulerScheduleOneTime(60, "my-payload", "")
 
@@ -389,7 +458,7 @@ err := host.SchedulerCancelSchedule(scheduleID)
 
 ### Cache
 
-Store and retrieve data in an in-memory TTL-based cache. Each plugin has its own isolated namespace.
+In-memory TTL-based cache. Each plugin has its own isolated namespace. Cleared on server restart.
 
 **Manifest permission:**
 
@@ -420,28 +489,22 @@ Store and retrieve data in an in-memory TTL-based cache. Each plugin has its own
 
 **TTL:** Pass `0` for the default (24 hours), or specify seconds.
 
-**Usage (with generated SDK):**
-
-Import the Go SDK (see [Scheduler](#scheduler) for `go.mod` setup):
+**Usage:**
 
 ```go
-import "github.com/navidrome/navidrome/plugins/pdk/go/host"
-
 // Cache a value for 1 hour
 host.CacheSetString("api-response", responseData, 3600)
 
-// Retrieve (check Exists before using Value)
-result, err := host.CacheGetString("api-response")
-if result.Exists {
-    data := result.Value
+// Retrieve (returns value, exists, error)
+value, exists, err := host.CacheGetString("api-response")
+if exists {
+    // Use value
 }
 ```
 
-> **Note:** Cache is in-memory only and cleared on server restart.
-
 ### KVStore
 
-Persistent key-value storage that survives server restarts. Each plugin has its own isolated SQLite database.
+Persistent key-value storage backed by SQLite. Survives server restarts. Each plugin has its own isolated database at `${DataFolder}/plugins/${pluginID}/kvstore.db`.
 
 **Manifest permission:**
 
@@ -456,61 +519,101 @@ Persistent key-value storage that survives server restarts. Each plugin has its
 }
 ```
 
-**Permission options:**
 - `maxSize`: Maximum storage size (e.g., `"1MB"`, `"500KB"`). Default: 1MB
 
+**Key constraints:** Maximum 256 bytes, must be valid UTF-8.
+
 **Host functions:**
 
-| Function                 | Parameters   | Description                       |
-|--------------------------|--------------|-----------------------------------|
-| `kvstore_set`            | `key, value` | Store a byte value                |
-| `kvstore_get`            | `key`        | Retrieve a byte value             |
-| `kvstore_delete`         | `key`        | Delete a value                    |
-| `kvstore_has`            | `key`        | Check if key exists               |
-| `kvstore_list`           | `prefix`     | List keys matching prefix         |
-| `kvstore_getstorageused` | -            | Get current storage usage (bytes) |
+| Function                    | Parameters               | Description                       |
+|-----------------------------|--------------------------|-----------------------------------|
+| `kvstore_set`               | `key, value`             | Store a byte value                |
+| `kvstore_setwithttl`        | `key, value, ttlSeconds` | Store with auto-expiration        |
+| `kvstore_get`               | `key`                    | Retrieve a byte value             |
+| `kvstore_getmany`           | `keys`                   | Retrieve multiple values at once  |
+| `kvstore_has`               | `key`                    | Check if key exists               |
+| `kvstore_list`              | `prefix`                 | List keys matching prefix         |
+| `kvstore_delete`            | `key`                    | Delete a value                    |
+| `kvstore_deletebyprefix`    | `prefix`                 | Delete all keys matching prefix   |
+| `kvstore_getstorageused`    | –                        | Get current storage usage (bytes) |
 
-**Key constraints:**
-- Maximum key length: 256 bytes
-- Keys must be valid UTF-8 strings
-
-**Usage (with generated SDK):**
-
-Import the Go SDK (see [Scheduler](#scheduler) for `go.mod` setup):
+**Usage:**
 
 ```go
-import "github.com/navidrome/navidrome/plugins/pdk/go/host"
-
 // Store a value (as raw bytes)
 token := []byte(`{"access_token": "xyz", "refresh_token": "abc"}`)
-_, err := host.KVStoreSet("oauth:spotify", token)
+host.KVStoreSet("oauth:spotify", token)
+
+// Store with TTL (auto-expires after 1 hour)
+host.KVStoreSetWithTTL("session:abc", sessionData, 3600)
 
 // Retrieve a value
-result, err := host.KVStoreGet("oauth:spotify")
-if result.Exists {
+value, exists, err := host.KVStoreGet("oauth:spotify")
+if exists {
     var tokenData map[string]string
-    json.Unmarshal(result.Value, &tokenData)
+    json.Unmarshal(value, &tokenData)
 }
 
-// List all keys with prefix
-keysResult, err := host.KVStoreList("user:")
-for _, key := range keysResult.Keys {
-    // Process each key
-}
+// Batch retrieve
+results, err := host.KVStoreGetMany([]string{"key1", "key2", "key3"})
+
+// List and delete by prefix
+keys, err := host.KVStoreList("user:")
+host.KVStoreDeleteByPrefix("user:")
 
 // Check storage usage
-usageResult, err := host.KVStoreGetStorageUsed()
-fmt.Printf("Using %d bytes\n", usageResult.Bytes)
-
-// Delete a value
-host.KVStoreDelete("oauth:spotify")
+usage, err := host.KVStoreGetStorageUsed()
+fmt.Printf("Using %d bytes\n", usage)
 ```
 
-> **Note:** Unlike Cache, KVStore data persists across server restarts. Storage is located at `${DataFolder}/plugins/${pluginID}/kvstore.db`.
+### Task
+
+Background task queue with retry support. Plugins enqueue tasks and process them by exporting the [`nd_task_execute`](#taskworker) capability function.
+
+**Manifest permission:**
+
+```json
+{
+  "permissions": {
+    "taskqueue": {
+      "reason": "Process audio analysis in the background",
+      "maxConcurrency": 2
+    }
+  }
+}
+```
+
+**Host functions:**
+
+| Function            | Parameters                                        | Description                |
+|---------------------|---------------------------------------------------|----------------------------|
+| `task_createqueue`  | `name, concurrency, maxRetries, backoffMs, ...`   | Create a named task queue  |
+| `task_enqueue`      | `queueName, payload`                              | Add a task to the queue    |
+| `task_get`          | `taskID`                                          | Get task status and result |
+| `task_cancel`       | `taskID`                                          | Cancel a pending task      |
+| `task_clearqueue`   | `queueName`                                       | Remove all tasks from queue|
+
+**Usage:**
+
+```go
+// Create a queue with retry configuration
+host.TaskCreateQueue("analysis", host.QueueConfig{
+    Concurrency: 2,
+    MaxRetries:  3,
+    BackoffMs:   1000,
+})
+
+// Enqueue a task
+taskID, err := host.TaskEnqueue("analysis", []byte(`{"trackId": "abc"}`))
+
+// Check task status
+info, err := host.TaskGet(taskID)
+fmt.Printf("Status: %s, Attempt: %d\n", info.Status, info.Attempt)
+```
 
 ### WebSocket
 
-Establish persistent WebSocket connections to external services.
+Establish persistent WebSocket connections to external services. Your plugin must export [WebSocketCallback](#websocketcallback) functions to receive events.
 
 **Manifest permission:**
 
@@ -527,21 +630,20 @@ Establish persistent WebSocket connections to external services.
 
 **Host functions:**
 
-| Function               | Parameters                      | Description       |
-|------------------------|---------------------------------|-------------------|
-| `websocket_connect`    | `url, headers?, connectionId?`  | Open a connection |
-| `websocket_sendtext`   | `connectionId, message`         | Send text message |
-| `websocket_sendbinary` | `connectionId, data`            | Send binary data  |
-| `websocket_close`      | `connectionId, code?, reason?`  | Close connection  |
+| Function                   | Parameters                      | Description       |
+|----------------------------|---------------------------------|-------------------|
+| `websocket_connect`        | `url, headers?, connectionId?`  | Open a connection |
+| `websocket_sendtext`       | `connectionId, message`         | Send text message |
+| `websocket_sendbinary`     | `connectionId, data`            | Send binary data  |
+| `websocket_closeconnection`| `connectionId, code?, reason?`  | Close connection  |
 
-**Callback functions (export these to receive events):**
+**Usage:**
 
-| Function                         | Input                           | Description                      |
-|----------------------------------|---------------------------------|----------------------------------|
-| `nd_websocket_on_text_message`   | `{connectionId, message}`       | Text message received            |
-| `nd_websocket_on_binary_message` | `{connectionId, data}`          | Binary message received (base64) |
-| `nd_websocket_on_error`          | `{connectionId, error}`         | Connection error                 |
-| `nd_websocket_on_close`          | `{connectionId, code, reason}`  | Connection closed                |
+```go
+connID, err := host.WebSocketConnect("wss://gateway.example.com", nil, "")
+host.WebSocketSendText(connID, `{"op": 1, "d": null}`)
+host.WebSocketCloseConnection(connID, 1000, "done")
+```
 
 ### Library
 
@@ -595,33 +697,22 @@ When `filesystem: true`, your plugin can read files from library directories via
 ```go
 import "os"
 
-// Read a file from library 1
 content, err := os.ReadFile("/libraries/1/Artist/Album/track.mp3")
-
-// List directory contents
 entries, err := os.ReadDir("/libraries/1/Artist")
 ```
 
-> **Security:** Filesystem access is read-only and restricted to configured library paths only. Plugins cannot access other parts of the host filesystem.
+> **Security:** Filesystem access is read-only and restricted to configured library paths only.
 
-**Usage (with generated SDK):**
-
-Import the Go SDK (see [Scheduler](#scheduler) for `go.mod` setup). The `Library` struct is provided by the SDK:
+**Usage:**
 
 ```go
-import "github.com/navidrome/navidrome/plugins/pdk/go/host"
-
 // Get a specific library
-resp, err := host.LibraryGetLibrary(1)
-if err != nil {
-    // Handle error
-}
-library := resp.Result
+library, err := host.LibraryGetLibrary(1)
+fmt.Printf("Library: %s (%d songs)\n", library.Name, library.TotalSongs)
 
 // Get all libraries
-resp, err := host.LibraryGetAllLibraries()
-for _, lib := range resp.Result {
-    // lib is of type host.Library
+libraries, err := host.LibraryGetAllLibraries()
+for _, lib := range libraries {
     fmt.Printf("Library: %s (%d songs)\n", lib.Name, lib.TotalSongs)
 }
 ```
@@ -651,6 +742,12 @@ Generate public URLs for Navidrome artwork (albums, artists, tracks, playlists).
 | `artwork_gettrackurl`    | `id, size` | Artwork URL |
 | `artwork_getplaylisturl` | `id, size` | Artwork URL |
 
+**Usage:**
+
+```go
+url, err := host.ArtworkGetAlbumUrl("album-id", 300)
+```
+
 ### SubsonicAPI
 
 Call Navidrome's Subsonic API internally (no network round-trip).
@@ -670,24 +767,28 @@ Call Navidrome's Subsonic API internally (no network round-trip).
 }
 ```
 
-> **Important:** The `subsonicapi` permission requires the `users` permission. User access is controlled through the plugin's database configuration, not the manifest. Configure which users can use the plugin through the Navidrome UI or API.
+> **Important:** The `subsonicapi` permission requires the `users` permission. Which users the plugin can act as is controlled through the Navidrome UI.
 
-**Host function:**
+**Host functions:**
 
-| Function           | Parameters | Returns       |
-|--------------------|------------|---------------|
-| `subsonicapi_call` | `uri`      | JSON response |
+| Function              | Parameters | Returns                        |
+|-----------------------|------------|--------------------------------|
+| `subsonicapi_call`    | `uri`      | JSON response string           |
+| `subsonicapi_callraw` | `uri`      | Content type + binary response |
 
 **Usage:**
 
 ```go
-// The URI must include the 'u' parameter with the username
-response, err := SubsonicAPICall("getAlbumList2?type=random&size=10&u=username")
+// JSON response
+response, err := host.SubsonicAPICall("getAlbumList2?type=random&size=10&u=username")
+
+// Binary response (e.g., cover art, streams)
+contentType, data, err := host.SubsonicAPICallRaw("getCoverArt?id=al-123&u=username")
 ```
 
 ### Config
 
-Access plugin configuration values programmatically. Unlike `pdk.GetConfig()` which only retrieves individual values, this service can list all available configuration keys—useful for discovering dynamic configuration (e.g., user-to-token mappings).
+Access plugin configuration values. Unlike `pdk.GetConfig()` which only retrieves individual values, this service can list all available configuration keys — useful for discovering dynamic configuration.
 
 > **Note:** This service is always available and does not require a manifest permission.
 
@@ -699,25 +800,17 @@ Access plugin configuration values programmatically. Unlike `pdk.GetConfig()` wh
 | `config_getint` | `key`      | `value, exists`             |
 | `config_keys`   | `prefix`   | Array of matching key names |
 
-**Usage (with generated SDK):**
+**Usage:**
 
 ```go
-import "github.com/navidrome/navidrome/plugins/pdk/go/host"
-
-// Get a string configuration value
+// Get a configuration value
 value, exists := host.ConfigGet("api_key")
-if exists {
-    // Use the value
-}
 
 // Get an integer configuration value
 count, exists := host.ConfigGetInt("max_retries")
 
 // List all keys with a prefix (useful for user-specific config)
 keys := host.ConfigKeys("user:")
-for _, key := range keys {
-    // key might be "user:john", "user:jane", etc.
-}
 
 // List all configuration keys
 allKeys := host.ConfigKeys("")
@@ -725,7 +818,7 @@ allKeys := host.ConfigKeys("")
 
 ### Users
 
-Access user information for the users that the plugin has been granted access to. This is useful for plugins that need to associate data with specific users or display user information.
+Access user information for the users that the plugin has been granted access to.
 
 **Manifest permission:**
 
@@ -739,7 +832,7 @@ Access user information for the users that the plugin has been granted access to
 }
 ```
 
-**Important:** Before enabling a plugin that requires the `users` permission, an administrator must configure which users the plugin can access. This can be done in two ways:
+**Important:** Before enabling a plugin that requires the `users` permission, an administrator must configure which users the plugin can access:
 
 1. **Allow all users** – Enable the "Allow all users" toggle in the plugin settings
 2. **Select specific users** – Choose individual users from the user list
@@ -751,6 +844,7 @@ If neither option is configured, the plugin cannot be enabled.
 | Function         | Parameters | Returns               |
 |------------------|------------|-----------------------|
 | `users_getusers` | –          | Array of User objects |
+| `users_getadmins`| –          | Array of admin Users  |
 
 **User object fields:**
 
@@ -762,45 +856,15 @@ If neither option is configured, the plugin cannot be enabled.
 
 > **Security:** Sensitive fields like passwords, email addresses, and internal IDs are never exposed to plugins.
 
-**Usage (with generated SDK):**
+**Usage:**
 
 ```go
-import "github.com/navidrome/navidrome/plugins/pdk/go/host"
-
-// Get all users the plugin has access to
 users, err := host.UsersGetUsers()
-if err != nil {
-    pdk.Log(pdk.LogError, "Failed to get users: " + err.Error())
-    return
-}
-
 for _, user := range users {
     pdk.Log(pdk.LogInfo, "User: " + user.UserName + " (" + user.Name + ")")
-    if user.IsAdmin {
-        pdk.Log(pdk.LogInfo, "  - Administrator")
-    }
 }
-```
 
-**Rust example:**
-
-```rust
-use nd_pdk_host::users::get_users;
-
-let users = get_users()?;
-for user in users {
-    println!("User: {} ({})", user.user_name, user.name);
-}
-```
-
-**Python example:**
-
-```python
-from host.nd_host_users import users_get_users
-
-users = users_get_users()
-for user in users:
-    print(f"User: {user['userName']} ({user['name']})")
+admins, err := host.UsersGetAdmins()
 ```
 
 ---
@@ -834,20 +898,20 @@ if !ok {
 }
 ```
 
+For more advanced access (listing keys, integer values), use the [Config](#config) host service.
+
 ---
 
 ## Building Plugins
 
 ### Supported Languages
 
-Plugins can be written in any language that Extism supports. Each language has its own PDK (Plugin Development Kit) that provides the APIs for I/O, logging, configuration, and HTTP requests. See the [Extism PDK documentation](https://extism.org/docs/concepts/pdk) for details.
+Plugins can be written in any language that Extism supports. We recommend:
 
-We recommend:
-
-- **Go** – Best experience with [TinyGo](https://tinygo.org/) and the [Go PDK](https://github.com/extism/go-pdk)
-- **Rust** – Excellent performance with the [Rust PDK](https://github.com/extism/rust-pdk)
-- **Python** – Experimental support via [extism-py](https://github.com/extism/python-pdk)
-- **TypeScript** – Experimental support via [extism-js](https://github.com/extism/js-pdk)
+- **Go** – Best overall experience with [TinyGo](https://tinygo.org/) and the [Go PDK](https://github.com/extism/go-pdk). Familiar syntax, excellent stdlib support.
+- **Rust** – Best for performance-critical plugins. Smallest binaries, excellent type safety. Uses the [Rust PDK](https://github.com/extism/rust-pdk).
+- **Python** – Best for rapid prototyping. Experimental support via [extism-py](https://github.com/extism/python-pdk). Note some limitations compared to compiled languages.
+- **TypeScript** – Experimental support via [extism-js](https://github.com/extism/js-pdk).
 
 ### Go with TinyGo (Recommended)
 
@@ -863,14 +927,12 @@ zip -j my-plugin.ndp manifest.json plugin.wasm
 
 #### Using Go PDK Packages
 
-Navidrome provides type-safe Go packages for each capability in `plugins/pdk/go/`. Instead of manually exporting functions with `//go:wasmexport`, use the `Register()` pattern:
+Navidrome provides type-safe Go packages for each capability and host service in `plugins/pdk/go/`. Instead of manually exporting functions with `//go:wasmexport`, use the `Register()` pattern:
 
 ```go
 package main
 
-import (
-    "github.com/navidrome/navidrome/plugins/pdk/go/metadata"
-)
+import "github.com/navidrome/navidrome/plugins/pdk/go/metadata"
 
 type myPlugin struct{}
 
@@ -878,10 +940,7 @@ func (p *myPlugin) GetArtistBiography(input metadata.ArtistRequest) (*metadata.A
     return &metadata.ArtistBiographyResponse{Biography: "Biography text..."}, nil
 }
 
-func init() {
-    metadata.Register(&myPlugin{})
-}
-
+func init() { metadata.Register(&myPlugin{}) }
 func main() {}
 ```
 
@@ -892,16 +951,19 @@ require github.com/navidrome/navidrome v0.0.0
 replace github.com/navidrome/navidrome => ../../..
 ```
 
-Available capability packages:
+**Available capability packages:**
 
-| Package     | Import Path                | Description                          |
-|-------------|----------------------------|--------------------------------------|
-| `metadata`  | `plugins/pdk/go/metadata`  | Artist/album metadata providers      |
-| `scrobbler` | `plugins/pdk/go/scrobbler` | Scrobbling services                  |
-| `lifecycle` | `plugins/pdk/go/lifecycle` | Plugin initialization                |
-| `scheduler` | `plugins/pdk/go/scheduler` | Scheduled task callbacks             |
-| `websocket` | `plugins/pdk/go/websocket` | WebSocket event handlers             |
-| `host`      | `plugins/pdk/go/host`      | Host service SDK (HTTP, cache, etc.) |
+| Package           | Import Path                          | Description                          |
+|-------------------|--------------------------------------|--------------------------------------|
+| `metadata`        | `plugins/pdk/go/metadata`            | Artist/album metadata providers      |
+| `scrobbler`       | `plugins/pdk/go/scrobbler`           | Scrobbling services                  |
+| `lyrics`          | `plugins/pdk/go/lyrics`              | Lyrics providers                     |
+| `sonicsimilarity` | `plugins/pdk/go/sonicsimilarity`     | Audio similarity discovery           |
+| `taskworker`      | `plugins/pdk/go/taskworker`          | Background task processing           |
+| `lifecycle`       | `plugins/pdk/go/lifecycle`           | Plugin initialization                |
+| `scheduler`       | `plugins/pdk/go/scheduler`           | Scheduled task callbacks             |
+| `websocket`       | `plugins/pdk/go/websocket`           | WebSocket event handlers             |
+| `host`            | `plugins/pdk/go/host`                | Host service SDK (all services)      |
 
 See the example plugins in [examples/](examples/) for complete usage patterns.
 
@@ -917,8 +979,6 @@ zip -j my-plugin.ndp manifest.json target/wasm32-wasip1/release/plugin.wasm
 
 #### Using Rust PDK
 
-The Rust PDK provides generated type-safe wrappers for both capabilities and host services:
-
 ```toml
 # Cargo.toml
 [dependencies]
@@ -953,17 +1013,12 @@ register_scrobbler!(MyPlugin);  // Generates all WASM exports
 ```rust
 use nd_pdk::host::{cache, scheduler, library};
 
-// Cache a value for 1 hour
 cache::set_string("my_key", "my_value", 3600)?;
-
-// Schedule a recurring task
 scheduler::schedule_recurring("@every 5m", "payload", "task_id")?;
-
-// Access library metadata
 let libs = library::get_all_libraries()?;
 ```
 
-See [pdk/rust/README.md](pdk/rust/README.md) for detailed documentation and examples.
+See [pdk/rust/README.md](pdk/rust/README.md) for detailed documentation.
 
 ### Python (with extism-py)
 
@@ -975,6 +1030,8 @@ extism-py plugin.wasm -o plugin.wasm *.py
 zip -j my-plugin.ndp manifest.json plugin.wasm
 ```
 
+**For Python host services:** Copy functions from the `nd_host_*.py` files in `plugins/pdk/python/host/` into your `__init__.py` (see comments in those files for extism-py limitations).
+
 ### Using XTP CLI (Scaffolding)
 
 Bootstrap a new plugin from a schema:
@@ -996,66 +1053,38 @@ zip -j my-agent.ndp manifest.json dist/plugin.wasm
 
 See [capabilities/README.md](capabilities/README.md) for available schemas and scaffolding examples.
 
-### Using Host Service SDKs
-
-Generated SDKs for calling host services are in `plugins/pdk/go/`, `plugins/pdk/python/` and `plugins/pdk/rust`.
-
-**For Go plugins:** Import the SDK as a Go module:
-
-```go
-import "github.com/navidrome/navidrome/plugins/pdk/go/host"
-```
-
-Add to your `go.mod`:
-
-```
-require github.com/navidrome/navidrome/plugins/pdk/go v0.0.0
-replace github.com/navidrome/navidrome/plugins/pdk/go => ../../pdk/go
-```
-
-See [pdk/go/README.md](pdk/go/README.md) for detailed documentation.
-
-**For Python plugins:** Copy functions from `nd_host_*.py` into your `__init__.py` (see comments in those files for extism-py limitations).
-
-**Recommendations:**
-
-- **Go:** Best overall experience with excellent stdlib support and familiar syntax for most developers. Recommended if you're already in the Go ecosystem.
-- **Rust:** Best for performance-critical plugins or when leveraging Rust's ecosystem. Produces smallest binaries with excellent type safety.
-- **Python:** Best for rapid prototyping or simple plugins. Note that extism-py has limitations compared to compiled languages.
-
 ---
 
 ## Examples
 
 See [examples/](examples/) for complete working plugins:
 
-| Plugin                                                         | Language | Capabilities  | Host Services                              | Description                    |
-|----------------------------------------------------------------|----------|---------------|--------------------------------------------|--------------------------------|
-| [minimal](examples/minimal/)                                   | Go       | MetadataAgent | –                                          | Basic structure example        |
-| [wikimedia](examples/wikimedia/)                               | Go       | MetadataAgent | HTTP                                       | Wikidata/Wikipedia integration |
-| [coverartarchive-py](examples/coverartarchive-py/)             | Python   | MetadataAgent | HTTP                                       | Cover Art Archive              |
-| [webhook-rs](examples/webhook-rs/)                             | Rust     | Scrobbler     | HTTP                                       | HTTP webhooks                  |
-| [nowplaying-py](examples/nowplaying-py/)                       | Python   | Lifecycle     | Scheduler, SubsonicAPI                     | Periodic now-playing logger    |
-| [library-inspector](examples/library-inspector-rs/)            | Rust     | Lifecycle     | Library, Scheduler                         | Periodic library stats logging |
-| [crypto-ticker](examples/crypto-ticker/)                       | Go       | Lifecycle     | WebSocket, Scheduler                       | Real-time crypto prices demo   |
-| [discord-rich-presence-rs](examples/discord-rich-presence-rs/) | Rust     | Scrobbler     | HTTP, WebSocket, Cache, Scheduler, Artwork | Discord integration (Rust)     |
+| Plugin                                                         | Language       | Capabilities  | Host Services                              | Description                    |
+|----------------------------------------------------------------|----------------|---------------|--------------------------------------------|--------------------------------|
+| [minimal](examples/minimal/)                                   | Go             | MetadataAgent | –                                          | Basic structure example        |
+| [wikimedia](examples/wikimedia/)                               | Go             | MetadataAgent | HTTP                                       | Wikidata/Wikipedia integration |
+| [coverartarchive-py](examples/coverartarchive-py/)             | Python         | MetadataAgent | HTTP                                       | Cover Art Archive              |
+| [coverartarchive-as](examples/coverartarchive-as/)             | AssemblyScript | MetadataAgent | HTTP                                       | Cover Art Archive              |
+| [webhook-rs](examples/webhook-rs/)                             | Rust           | Scrobbler     | HTTP                                       | HTTP webhooks                  |
+| [nowplaying-py](examples/nowplaying-py/)                       | Python         | Lifecycle     | Scheduler, SubsonicAPI                     | Periodic now-playing logger    |
+| [library-inspector-rs](examples/library-inspector-rs/)         | Rust           | Lifecycle     | Library, Scheduler                         | Periodic library stats logging |
+| [crypto-ticker](examples/crypto-ticker/)                       | Go             | Lifecycle     | WebSocket, Scheduler                       | Real-time crypto prices demo   |
+| [discord-rich-presence-rs](examples/discord-rich-presence-rs/) | Rust           | Scrobbler     | HTTP, WebSocket, Cache, Scheduler, Artwork | Discord integration            |
 
 ---
 
-
 ## Security
 
 Plugins run in a secure WebAssembly sandbox provided by [Extism](https://extism.org/) and the [Wazero](https://wazero.io/) runtime:
 
 1. **Host Allowlisting** – Only explicitly allowed hosts are accessible via HTTP/WebSocket
-2. **Limited File System** – Plugins can only access library directories when explicitly granted the `library.filesystem` permission, and access is read-only
+2. **Limited File System** – Read-only access to library directories, only when explicitly granted the `library.filesystem` permission
 3. **No Network Listeners** – Plugins cannot bind ports
 4. **Config Isolation** – Plugins only receive their own config section
 5. **Memory Limits** – Controlled by the WebAssembly runtime
-6. **User-Scoped Authorization** – Plugins with `subsonicapi` or `scrobbler` capabilities can only access/receive events for users assigned to them through Navidrome's configuration. The `users` permission is required for these features.
+6. **User-Scoped Authorization** – Plugins with `subsonicapi` or `scrobbler` capabilities can only access/receive events for users assigned to them through Navidrome's configuration
 7. **Users Permission** – Plugins requesting user access must be explicitly configured with allowed users; sensitive data (passwords, emails) is never exposed
 
-
 ---
 
 ## Runtime Management
@@ -1064,7 +1093,7 @@ Plugins run in a secure WebAssembly sandbox provided by [Extism](https://extism.
 
 With `AutoReload = true`, Navidrome watches the plugins folder and automatically detects when `.ndp` files are added, modified, or removed. When a plugin file changes, the plugin is disabled and its metadata is re-read from the archive.
 
-If the `AutoReload` setting is disabled, Navidrome needs to be restarted to pick up plugin changes.
+If `AutoReload` is disabled, Navidrome needs to be restarted to pick up plugin changes.
 
 ### Enabling/Disabling Plugins
 
@@ -1074,4 +1103,4 @@ Plugins can be enabled/disabled via the Navidrome UI. The plugin state is persis
 
 - **In-flight requests** – When reloading, existing requests complete before the new version takes over
 - **Config changes** – Changes to the plugin configuration in the UI are applied immediately
-- **Cache persistence** – The in-memory cache is cleared when a plugin is unloaded
+- **Cache persistence** – The in-memory cache is cleared when a plugin is unloaded

plugins/capabilities/lyrics.yaml

@@ -102,6 +102,12 @@ components:
                 mbzReleaseTrackId:
                     type: string
                     description: MBZReleaseTrackID is the MusicBrainz release track ID.
+                libraryId:
+                    type: integer
+                    format: int32
+                    description: |-
+                        LibraryID is the ID of the library the track belongs to.
+                        Only included if the plugin has library permission with filesystem access for the track's library.
                 path:
                     type: string
                     description: |-

plugins/capabilities/scrobbler.go

@@ -68,6 +68,9 @@ type TrackInfo struct {
 	MBZReleaseGroupID string `json:"mbzReleaseGroupId,omitempty"`
 	// MBZReleaseTrackID is the MusicBrainz release track ID.
 	MBZReleaseTrackID string `json:"mbzReleaseTrackId,omitempty"`
+	// LibraryID is the ID of the library the track belongs to.
+	// Only included if the plugin has library permission with filesystem access for the track's library.
+	LibraryID int32 `json:"libraryId,omitempty"`
 	// Path is the full path to the track file, relative to the library root.
 	// Only included if the plugin has library permission with filesystem access for the track's library.
 	Path string `json:"path,omitempty"`

plugins/capabilities/scrobbler.yaml

@@ -128,6 +128,12 @@ components:
                 mbzReleaseTrackId:
                     type: string
                     description: MBZReleaseTrackID is the MusicBrainz release track ID.
+                libraryId:
+                    type: integer
+                    format: int32
+                    description: |-
+                        LibraryID is the ID of the library the track belongs to.
+                        Only included if the plugin has library permission with filesystem access for the track's library.
                 path:
                     type: string
                     description: |-

plugins/capabilities/sonic_similarity.go

@@ -0,0 +1,32 @@
+package capabilities
+
+// SonicSimilarity provides audio-similarity based track discovery.
+//
+//nd:capability name=sonicsimilarity required=true
+type SonicSimilarity interface {
+	//nd:export name=nd_get_sonic_similar_tracks
+	GetSonicSimilarTracks(GetSonicSimilarTracksRequest) (SonicSimilarityResponse, error)
+
+	//nd:export name=nd_find_sonic_path
+	FindSonicPath(FindSonicPathRequest) (SonicSimilarityResponse, error)
+}
+
+type GetSonicSimilarTracksRequest struct {
+	Song  SongRef `json:"song"`
+	Count int32   `json:"count"`
+}
+
+type FindSonicPathRequest struct {
+	StartSong SongRef `json:"startSong"`
+	EndSong   SongRef `json:"endSong"`
+	Count     int32   `json:"count"`
+}
+
+type SonicSimilarityResponse struct {
+	Matches []SonicMatch `json:"matches"`
+}
+
+type SonicMatch struct {
+	Song       SongRef `json:"song"`
+	Similarity float64 `json:"similarity"`
+}

plugins/capabilities/sonic_similarity.yaml

@@ -0,0 +1,92 @@
+version: v1-draft
+exports:
+    nd_get_sonic_similar_tracks:
+        input:
+            $ref: '#/components/schemas/GetSonicSimilarTracksRequest'
+            contentType: application/json
+        output:
+            $ref: '#/components/schemas/SonicSimilarityResponse'
+            contentType: application/json
+    nd_find_sonic_path:
+        input:
+            $ref: '#/components/schemas/FindSonicPathRequest'
+            contentType: application/json
+        output:
+            $ref: '#/components/schemas/SonicSimilarityResponse'
+            contentType: application/json
+components:
+    schemas:
+        FindSonicPathRequest:
+            properties:
+                startSong:
+                    $ref: '#/components/schemas/SongRef'
+                endSong:
+                    $ref: '#/components/schemas/SongRef'
+                count:
+                    type: integer
+                    format: int32
+            required:
+                - startSong
+                - endSong
+                - count
+        GetSonicSimilarTracksRequest:
+            properties:
+                song:
+                    $ref: '#/components/schemas/SongRef'
+                count:
+                    type: integer
+                    format: int32
+            required:
+                - song
+                - count
+        SongRef:
+            description: SongRef is a reference to a song with metadata for matching.
+            properties:
+                id:
+                    type: string
+                    description: ID is the internal Navidrome mediafile ID (if known).
+                name:
+                    type: string
+                    description: Name is the song name.
+                mbid:
+                    type: string
+                    description: MBID is the MusicBrainz ID for the song.
+                isrc:
+                    type: string
+                    description: ISRC is the International Standard Recording Code for the song.
+                artist:
+                    type: string
+                    description: Artist is the artist name.
+                artistMbid:
+                    type: string
+                    description: ArtistMBID is the MusicBrainz artist ID.
+                album:
+                    type: string
+                    description: Album is the album name.
+                albumMbid:
+                    type: string
+                    description: AlbumMBID is the MusicBrainz release ID.
+                duration:
+                    type: number
+                    format: float
+                    description: Duration is the song duration in seconds.
+            required:
+                - name
+        SonicMatch:
+            properties:
+                song:
+                    $ref: '#/components/schemas/SongRef'
+                similarity:
+                    type: number
+                    format: float
+            required:
+                - song
+                - similarity
+        SonicSimilarityResponse:
+            properties:
+                matches:
+                    type: array
+                    items:
+                        $ref: '#/components/schemas/SonicMatch'
+            required:
+                - matches

plugins/config_validation_test.go

@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (

plugins/lyrics_adapter.go

@@ -21,6 +21,10 @@ func init() {
 	)
 }
 
+func newLyricsPlugin(p *plugin) *LyricsPlugin {
+	return &LyricsPlugin{name: p.name, plugin: p}
+}
+
 // LyricsPlugin adapts a WASM plugin with the Lyrics capability.
 type LyricsPlugin struct {
 	name   string

plugins/manager.go

@@ -18,6 +18,7 @@ import (
 	"github.com/navidrome/navidrome/core/agents"
 	"github.com/navidrome/navidrome/core/lyrics"
 	"github.com/navidrome/navidrome/core/scrobbler"
+	"github.com/navidrome/navidrome/core/sonic"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/server/events"
@@ -238,65 +239,32 @@ func (m *Manager) PluginNames(capability string) []string {
 	return names
 }
 
-// LoadMediaAgent loads and returns a media agent plugin by name.
-// Returns false if the plugin is not found or doesn't have the MetadataAgent capability.
 func (m *Manager) LoadMediaAgent(name string) (agents.Interface, bool) {
-	m.mu.RLock()
-	plugin, ok := m.plugins[name]
-	m.mu.RUnlock()
-
-	if !ok || !hasCapability(plugin.capabilities, CapabilityMetadataAgent) {
-		return nil, false
-	}
-
-	// Create a new metadata agent adapter for this plugin
-	return &MetadataAgent{
-		name:   plugin.name,
-		plugin: plugin,
-	}, true
+	return loadPlugin(m, name, CapabilityMetadataAgent, newMetadataAgent)
 }
 
-// LoadScrobbler loads and returns a scrobbler plugin by name.
-// Returns false if the plugin is not found or doesn't have the Scrobbler capability.
 func (m *Manager) LoadScrobbler(name string) (scrobbler.Scrobbler, bool) {
-	m.mu.RLock()
-	plugin, ok := m.plugins[name]
-	m.mu.RUnlock()
-
-	if !ok || !hasCapability(plugin.capabilities, CapabilityScrobbler) {
-		return nil, false
-	}
-
-	// Build user ID map for fast lookups
-	userIDMap := make(map[string]struct{})
-	for _, id := range plugin.allowedUserIDs {
-		userIDMap[id] = struct{}{}
-	}
-
-	// Create a new scrobbler adapter for this plugin with user authorization config
-	return &ScrobblerPlugin{
-		name:           plugin.name,
-		plugin:         plugin,
-		allowedUserIDs: plugin.allowedUserIDs,
-		allUsers:       plugin.allUsers,
-		userIDMap:      userIDMap,
-	}, true
+	return loadPlugin(m, name, CapabilityScrobbler, newScrobblerPlugin)
 }
 
-// LoadLyricsProvider loads and returns a lyrics provider plugin by name.
 func (m *Manager) LoadLyricsProvider(name string) (lyrics.Lyrics, bool) {
+	return loadPlugin(m, name, CapabilityLyrics, newLyricsPlugin)
+}
+
+func (m *Manager) LoadSonicSimilarity(name string) (sonic.Provider, bool) {
+	return loadPlugin(m, name, CapabilitySonicSimilarity, newSonicSimilarityPlugin)
+}
+
+func loadPlugin[T any](m *Manager, name string, cap Capability, newAdapter func(*plugin) T) (T, bool) {
 	m.mu.RLock()
-	plugin, ok := m.plugins[name]
+	p, ok := m.plugins[name]
 	m.mu.RUnlock()
 
-	if !ok || !hasCapability(plugin.capabilities, CapabilityLyrics) {
-		return nil, false
+	var zero T
+	if !ok || !hasCapability(p.capabilities, cap) {
+		return zero, false
 	}
-
-	return &LyricsPlugin{
-		name:   plugin.name,
-		plugin: plugin,
-	}, true
+	return newAdapter(p), true
 }
 
 // PluginInfo contains basic information about a plugin for metrics/insights.

plugins/manager_loader_test.go

@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (

plugins/manager_test.go

@@ -1,3 +1,5 @@
+//go:build !windows
+
 package plugins
 
 import (

plugins/manager_watcher_test.go

@@ -1,3 +1,5 @@
+//go:build !windows
+
 package plugins
 
 import (

plugins/metadata_agent.go

@@ -6,6 +6,7 @@ import (
 
 	"github.com/navidrome/navidrome/core/agents"
 	"github.com/navidrome/navidrome/plugins/capabilities"
+	"github.com/navidrome/navidrome/utils/slice"
 )
 
 // CapabilityMetadataAgent indicates the plugin can provide artist/album metadata.
@@ -44,6 +45,10 @@ func init() {
 	)
 }
 
+func newMetadataAgent(p *plugin) *MetadataAgent {
+	return &MetadataAgent{name: p.name, plugin: p}
+}
+
 // MetadataAgent is an adapter that wraps an Extism plugin and implements
 // the agents interfaces for metadata retrieval.
 type MetadataAgent struct {
@@ -222,23 +227,24 @@ func (a *MetadataAgent) GetSimilarSongsByArtist(ctx context.Context, id, name, m
 	return callSimilarSongsPluginFunction[capabilities.SimilarSongsByArtistRequest](ctx, a.plugin, FuncGetSimilarSongsByArtist, capabilities.SimilarSongsByArtistRequest{ID: id, Name: name, MBID: mbid, Count: int32(count)})
 }
 
+// songRefToAgentSong converts a single SongRef to agents.Song
+func songRefToAgentSong(s capabilities.SongRef) agents.Song {
+	return agents.Song{
+		ID:         s.ID,
+		Name:       s.Name,
+		MBID:       s.MBID,
+		ISRC:       s.ISRC,
+		Artist:     s.Artist,
+		ArtistMBID: s.ArtistMBID,
+		Album:      s.Album,
+		AlbumMBID:  s.AlbumMBID,
+		Duration:   uint32(s.Duration * 1000),
+	}
+}
+
 // songRefsToAgentSongs converts a slice of SongRef to agents.Song
 func songRefsToAgentSongs(refs []capabilities.SongRef) []agents.Song {
-	songs := make([]agents.Song, len(refs))
-	for i, s := range refs {
-		songs[i] = agents.Song{
-			ID:         s.ID,
-			Name:       s.Name,
-			MBID:       s.MBID,
-			ISRC:       s.ISRC,
-			Artist:     s.Artist,
-			ArtistMBID: s.ArtistMBID,
-			Album:      s.Album,
-			AlbumMBID:  s.AlbumMBID,
-			Duration:   uint32(s.Duration * 1000),
-		}
-	}
-	return songs
+	return slice.Map(refs, songRefToAgentSong)
 }
 
 // Verify interface implementations at compile time