refactor: remove outdated comments in GetSimilarSongs methods

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

.devcontainer/Dockerfile

@@ -23,5 +23,7 @@ RUN DOWNLOAD_ARCH="linux-${TARGETARCH}" \
     && rmdir /usr/include/taglib \
     && rm /tmp/cross-taglib.tar.gz /usr/provenance.json
 
+ENV CGO_CFLAGS_ALLOW="--define-prefix"
+
 # [Optional] Uncomment this line to install global node packages.
 # RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g <your-package-here>" 2>&1

.github/workflows/pipeline.yml

@@ -15,6 +15,7 @@ concurrency:
 
 env:
   CROSS_TAGLIB_VERSION: "2.1.1-1"
+  CGO_CFLAGS_ALLOW: "--define-prefix"
   IS_RELEASE: ${{ startsWith(github.ref, 'refs/tags/') && 'true' || 'false' }}
 
 jobs:

.gitignore

@@ -35,4 +35,5 @@ AGENTS.md
 *.test
 *.wasm
 *.ndp
-openspec/
+openspec/
+go.work*

Dockerfile

@@ -94,6 +94,7 @@ RUN --mount=type=bind,source=. \
     # Setup CGO cross-compilation environment
     xx-go --wrap
     export CGO_ENABLED=1
+    export CGO_CFLAGS_ALLOW="--define-prefix"
     export PKG_CONFIG_PATH=/taglib/lib/pkgconfig
     cat $(go env GOENV)
 

Makefile

@@ -2,6 +2,7 @@ GO_VERSION=$(shell grep "^go " go.mod | cut -f 2 -d ' ')
 NODE_VERSION=$(shell cat .nvmrc)
 
 # Set global environment variables, required for most targets
+export CGO_CFLAGS_ALLOW=--define-prefix
 export ND_ENABLEINSIGHTSCOLLECTOR=false
 
 ifneq ("$(wildcard .git/HEAD)","")

adapters/gotaglib/end_to_end_test.go

@@ -0,0 +1,274 @@
+package gotaglib
+
+import (
+	"io/fs"
+	"os"
+	"time"
+
+	"github.com/djherbis/times"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/metadata"
+	"github.com/navidrome/navidrome/utils/gg"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+type testFileInfo struct {
+	fs.FileInfo
+}
+
+func (t testFileInfo) BirthTime() time.Time {
+	if ts := times.Get(t.FileInfo); ts.HasBirthTime() {
+		return ts.BirthTime()
+	}
+	return t.FileInfo.ModTime()
+}
+
+var _ = Describe("Extractor", func() {
+	toP := func(name, sortName, mbid string) model.Participant {
+		return model.Participant{
+			Artist: model.Artist{Name: name, SortArtistName: sortName, MbzArtistID: mbid},
+		}
+	}
+
+	roles := []struct {
+		model.Role
+		model.ParticipantList
+	}{
+		{model.RoleComposer, model.ParticipantList{
+			toP("coma a", "a, coma", "bf13b584-f27c-43db-8f42-32898d33d4e2"),
+			toP("comb", "comb", "924039a2-09c6-4d29-9b4f-50cc54447d36"),
+		}},
+		{model.RoleLyricist, model.ParticipantList{
+			toP("la a", "a, la", "c84f648f-68a6-40a2-a0cb-d135b25da3c2"),
+			toP("lb", "lb", "0a7c582d-143a-4540-b4e9-77200835af65"),
+		}},
+		{model.RoleArranger, model.ParticipantList{
+			toP("aa", "", "4605a1d4-8d15-42a3-bd00-9c20e42f71e6"),
+			toP("ab", "", "002f0ff8-77bf-42cc-8216-61a9c43dc145"),
+		}},
+		{model.RoleConductor, model.ParticipantList{
+			toP("cona", "", "af86879b-2141-42af-bad2-389a4dc91489"),
+			toP("conb", "", "3dfa3c70-d7d3-4b97-b953-c298dd305e12"),
+		}},
+		{model.RoleDirector, model.ParticipantList{
+			toP("dia", "", "f943187f-73de-4794-be47-88c66f0fd0f4"),
+			toP("dib", "", "bceb75da-1853-4b3d-b399-b27f0cafc389"),
+		}},
+		{model.RoleEngineer, model.ParticipantList{
+			toP("ea", "", "f634bf6d-d66a-425d-888a-28ad39392759"),
+			toP("eb", "", "243d64ae-d514-44e1-901a-b918d692baee"),
+		}},
+		{model.RoleProducer, model.ParticipantList{
+			toP("pra", "", "d971c8d7-999c-4a5f-ac31-719721ab35d6"),
+			toP("prb", "", "f0a09070-9324-434f-a599-6d25ded87b69"),
+		}},
+		{model.RoleRemixer, model.ParticipantList{
+			toP("ra", "", "c7dc6095-9534-4c72-87cc-aea0103462cf"),
+			toP("rb", "", "8ebeef51-c08c-4736-992f-c37870becedd"),
+		}},
+		{model.RoleDJMixer, model.ParticipantList{
+			toP("dja", "", "d063f13b-7589-4efc-ab7f-c60e6db17247"),
+			toP("djb", "", "3636670c-385f-4212-89c8-0ff51d6bc456"),
+		}},
+		{model.RoleMixer, model.ParticipantList{
+			toP("ma", "", "53fb5a2d-7016-427e-a563-d91819a5f35a"),
+			toP("mb", "", "64c13e65-f0da-4ab9-a300-71ee53b0376a"),
+		}},
+	}
+
+	var e *extractor
+
+	parseTestFile := func(path string) *model.MediaFile {
+		mds, err := e.Parse(path)
+		Expect(err).ToNot(HaveOccurred())
+
+		info, ok := mds[path]
+		Expect(ok).To(BeTrue())
+
+		fileInfo, err := os.Stat(path)
+		Expect(err).ToNot(HaveOccurred())
+		info.FileInfo = testFileInfo{FileInfo: fileInfo}
+
+		metadata := metadata.New(path, info)
+		mf := metadata.ToMediaFile(1, "folderID")
+		return &mf
+	}
+
+	BeforeEach(func() {
+		e = &extractor{fs: os.DirFS(".")}
+	})
+
+	Describe("ReplayGain", func() {
+		DescribeTable("test replaygain end-to-end", func(file string, trackGain, trackPeak, albumGain, albumPeak *float64) {
+			mf := parseTestFile("tests/fixtures/" + file)
+
+			Expect(mf.RGTrackGain).To(Equal(trackGain))
+			Expect(mf.RGTrackPeak).To(Equal(trackPeak))
+			Expect(mf.RGAlbumGain).To(Equal(albumGain))
+			Expect(mf.RGAlbumPeak).To(Equal(albumPeak))
+		},
+			Entry("mp3 with no replaygain", "no_replaygain.mp3", nil, nil, nil, nil),
+			Entry("mp3 with no zero replaygain", "zero_replaygain.mp3", gg.P(0.0), gg.P(1.0), gg.P(0.0), gg.P(1.0)),
+		)
+	})
+
+	Describe("lyrics", func() {
+		makeLyrics := func(code, secondLine string) model.Lyrics {
+			return model.Lyrics{
+				DisplayArtist: "",
+				DisplayTitle:  "",
+				Lang:          code,
+				Line: []model.Line{
+					{Start: gg.P(int64(0)), Value: "This is"},
+					{Start: gg.P(int64(2500)), Value: secondLine},
+				},
+				Offset: nil,
+				Synced: true,
+			}
+		}
+
+		It("should fetch both synced and unsynced lyrics in mixed flac", func() {
+			mf := parseTestFile("tests/fixtures/mixed-lyrics.flac")
+
+			lyrics, err := mf.StructuredLyrics()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(lyrics).To(HaveLen(2))
+
+			Expect(lyrics[0].Synced).To(BeTrue())
+			Expect(lyrics[1].Synced).To(BeFalse())
+		})
+
+		It("should handle mp3 with uslt and sylt", func() {
+			mf := parseTestFile("tests/fixtures/test.mp3")
+
+			lyrics, err := mf.StructuredLyrics()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(lyrics).To(HaveLen(4))
+
+			engSylt := makeLyrics("eng", "English SYLT")
+			engUslt := makeLyrics("eng", "English")
+			unsSylt := makeLyrics("xxx", "unspecified SYLT")
+			unsUslt := makeLyrics("xxx", "unspecified")
+
+			Expect(lyrics).To(ConsistOf(engSylt, engUslt, unsSylt, unsUslt))
+		})
+
+		DescribeTable("format-specific lyrics", func(file string, isId3 bool) {
+			mf := parseTestFile("tests/fixtures/" + file)
+
+			lyrics, err := mf.StructuredLyrics()
+			Expect(err).To(Not(HaveOccurred()))
+			Expect(lyrics).To(HaveLen(2))
+
+			unspec := makeLyrics("xxx", "unspecified")
+			eng := makeLyrics("xxx", "English")
+
+			if isId3 {
+				eng.Lang = "eng"
+			}
+
+			Expect(lyrics).To(Or(
+				Equal(model.LyricList{unspec, eng}),
+				Equal(model.LyricList{eng, unspec})))
+		},
+			Entry("flac", "test.flac", false),
+			Entry("m4a", "test.m4a", false),
+			Entry("ogg", "test.ogg", false),
+			Entry("wma", "test.wma", false),
+			Entry("wv", "test.wv", false),
+			Entry("wav", "test.wav", true),
+			Entry("aiff", "test.aiff", true),
+		)
+	})
+
+	Describe("Participants", func() {
+		DescribeTable("test tags consistent across formats", func(format string) {
+			mf := parseTestFile("tests/fixtures/test." + format)
+
+			for _, data := range roles {
+				role := data.Role
+				artists := data.ParticipantList
+
+				actual := mf.Participants[role]
+				Expect(actual).To(HaveLen(len(artists)))
+
+				for i := range artists {
+					actualArtist := actual[i]
+					expectedArtist := artists[i]
+
+					Expect(actualArtist.Name).To(Equal(expectedArtist.Name))
+					Expect(actualArtist.SortArtistName).To(Equal(expectedArtist.SortArtistName))
+					Expect(actualArtist.MbzArtistID).To(Equal(expectedArtist.MbzArtistID))
+				}
+			}
+
+			if format != "m4a" {
+				performers := mf.Participants[model.RolePerformer]
+				Expect(performers).To(HaveLen(8))
+
+				rules := map[string][]string{
+					"pgaa": {"2fd0b311-9fa8-4ff9-be5d-f6f3d16b835e", "Guitar"},
+					"pgbb": {"223d030b-bf97-4c2a-ad26-b7f7bbe25c93", "Guitar", ""},
+					"pvaa": {"cb195f72-448f-41c8-b962-3f3c13d09d38", "Vocals"},
+					"pvbb": {"60a1f832-8ca2-49f6-8660-84d57f07b520", "Vocals", "Flute"},
+					"pfaa": {"51fb40c-0305-4bf9-a11b-2ee615277725", "", "Flute"},
+				}
+
+				for name, rule := range rules {
+					mbid := rule[0]
+					for i := 1; i < len(rule); i++ {
+						found := false
+
+						for _, mapped := range performers {
+							if mapped.Name == name && mapped.MbzArtistID == mbid && mapped.SubRole == rule[i] {
+								found = true
+								break
+							}
+						}
+
+						Expect(found).To(BeTrue(), "Could not find matching artist")
+					}
+				}
+			}
+		},
+			Entry("FLAC format", "flac"),
+			Entry("M4a format", "m4a"),
+			Entry("OGG format", "ogg"),
+			Entry("WV format", "wv"),
+
+			Entry("MP3 format", "mp3"),
+			Entry("WAV format", "wav"),
+			Entry("AIFF format", "aiff"),
+		)
+
+		It("should parse wma", func() {
+			mf := parseTestFile("tests/fixtures/test.wma")
+
+			for _, data := range roles {
+				role := data.Role
+				artists := data.ParticipantList
+				actual := mf.Participants[role]
+
+				// WMA has no Arranger role
+				if role == model.RoleArranger {
+					Expect(actual).To(HaveLen(0))
+					continue
+				}
+
+				Expect(actual).To(HaveLen(len(artists)), role.String())
+
+				// For some bizarre reason, the order is inverted. We also don't get
+				// sort names or MBIDs
+				for i := range artists {
+					idx := len(artists) - 1 - i
+
+					actualArtist := actual[i]
+					expectedArtist := artists[idx]
+
+					Expect(actualArtist.Name).To(Equal(expectedArtist.Name))
+				}
+			}
+		})
+	})
+})

adapters/gotaglib/gotaglib.go

@@ -0,0 +1,263 @@
+// Package gotaglib provides an alternative metadata extractor using go-taglib,
+// a pure Go (WASM-based) implementation of TagLib.
+//
+// This extractor aims for parity with the CGO-based taglib extractor. It uses
+// TagLib's PropertyMap interface for standard tags. The File handle API provides
+// efficient access to format-specific tags (ID3v2 frames, MP4 atoms, ASF attributes)
+// through a single file open operation.
+//
+// This extractor is registered under the name "gotaglib". It only works with a filesystem
+// (fs.FS) and does not support direct local file paths. Files returned by the filesystem
+// must implement io.ReadSeeker for go-taglib to read them.
+package gotaglib
+
+import (
+	"errors"
+	"io"
+	"io/fs"
+	"strings"
+	"time"
+
+	"github.com/navidrome/navidrome/core/storage/local"
+	"github.com/navidrome/navidrome/model/metadata"
+	"go.senan.xyz/taglib"
+)
+
+type extractor struct {
+	fs fs.FS
+}
+
+func (e extractor) Parse(files ...string) (map[string]metadata.Info, error) {
+	results := make(map[string]metadata.Info)
+	for _, path := range files {
+		props, err := e.extractMetadata(path)
+		if err != nil {
+			continue
+		}
+		results[path] = *props
+	}
+	return results, nil
+}
+
+func (e extractor) Version() string {
+	return "go-taglib (TagLib 2.1.1 WASM)"
+}
+
+func (e extractor) extractMetadata(filePath string) (*metadata.Info, error) {
+	f, close, err := e.openFile(filePath)
+	if err != nil {
+		return nil, err
+	}
+	defer close()
+
+	// Get all tags and properties in one go
+	allTags := f.AllTags()
+	props := f.Properties()
+
+	// Map properties to AudioProperties
+	ap := metadata.AudioProperties{
+		Duration:   props.Length.Round(time.Millisecond * 10),
+		BitRate:    int(props.Bitrate),
+		Channels:   int(props.Channels),
+		SampleRate: int(props.SampleRate),
+		BitDepth:   int(props.BitsPerSample),
+	}
+
+	// Convert normalized tags to lowercase keys (go-taglib returns UPPERCASE keys)
+	normalizedTags := make(map[string][]string, len(allTags.Tags))
+	for key, values := range allTags.Tags {
+		lowerKey := strings.ToLower(key)
+		normalizedTags[lowerKey] = values
+	}
+
+	// Process format-specific raw tags
+	processRawTags(allTags, normalizedTags)
+
+	// Parse track/disc totals from "N/Total" format
+	parseTuple(normalizedTags, "track")
+	parseTuple(normalizedTags, "disc")
+
+	// Adjust some ID3 tags
+	parseLyrics(normalizedTags)
+	parseTIPL(normalizedTags)
+	delete(normalizedTags, "tmcl") // TMCL is already parsed by TagLib
+
+	// Determine if file has embedded picture
+	hasPicture := len(props.Images) > 0
+
+	return &metadata.Info{
+		Tags:            normalizedTags,
+		AudioProperties: ap,
+		HasPicture:      hasPicture,
+	}, nil
+}
+
+// openFile opens the file at filePath using the extractor's filesystem.
+// It returns a TagLib File handle and a cleanup function to close resources.
+func (e extractor) openFile(filePath string) (*taglib.File, func(), error) {
+	// Open the file from the filesystem
+	file, err := e.fs.Open(filePath)
+	if err != nil {
+		return nil, nil, err
+	}
+	rs, isSeekable := file.(io.ReadSeeker)
+	if !isSeekable {
+		file.Close()
+		return nil, nil, errors.New("file is not seekable")
+	}
+	f, err := taglib.OpenStream(rs, taglib.WithReadStyle(taglib.ReadStyleFast))
+	if err != nil {
+		file.Close()
+		return nil, nil, err
+	}
+	closeFunc := func() {
+		f.Close()
+		file.Close()
+	}
+	return f, closeFunc, nil
+}
+
+// parseTuple parses track/disc numbers in "N/Total" format and separates them.
+// For example, tracknumber="2/10" becomes tracknumber="2" and tracktotal="10".
+func parseTuple(tags map[string][]string, prop string) {
+	tagName := prop + "number"
+	tagTotal := prop + "total"
+	if value, ok := tags[tagName]; ok && len(value) > 0 {
+		parts := strings.Split(value[0], "/")
+		tags[tagName] = []string{parts[0]}
+		if len(parts) == 2 {
+			tags[tagTotal] = []string{parts[1]}
+		}
+	}
+}
+
+// parseLyrics ensures lyrics tags have a language code.
+// If lyrics exist without a language code, they are moved to "lyrics:xxx".
+func parseLyrics(tags map[string][]string) {
+	lyrics := tags["lyrics"]
+	if len(lyrics) > 0 {
+		tags["lyrics:xxx"] = lyrics
+		delete(tags, "lyrics")
+	}
+}
+
+// processRawTags processes format-specific raw tags based on the detected file format.
+// This handles ID3v2 frames (MP3/WAV/AIFF), MP4 atoms, and ASF attributes.
+func processRawTags(allTags taglib.AllTags, normalizedTags map[string][]string) {
+	switch allTags.Format {
+	case taglib.FormatMPEG, taglib.FormatWAV, taglib.FormatAIFF:
+		parseID3v2Frames(allTags.Raw, normalizedTags)
+	case taglib.FormatMP4:
+		parseMP4Atoms(allTags.Raw, normalizedTags)
+	case taglib.FormatASF:
+		parseASFAttributes(allTags.Raw, normalizedTags)
+	}
+}
+
+// parseID3v2Frames processes ID3v2 raw frames to extract USLT/SYLT with language codes.
+// This extracts language-specific lyrics that the standard Tags() doesn't provide.
+func parseID3v2Frames(rawFrames map[string][]string, tags map[string][]string) {
+	// Process frames that have language-specific data
+	for key, values := range rawFrames {
+		lowerKey := strings.ToLower(key)
+
+		// Handle USLT:xxx and SYLT:xxx (lyrics with language codes)
+		if strings.HasPrefix(lowerKey, "uslt:") || strings.HasPrefix(lowerKey, "sylt:") {
+			parts := strings.SplitN(lowerKey, ":", 2)
+			if len(parts) == 2 && parts[1] != "" {
+				lang := parts[1]
+				lyricsKey := "lyrics:" + lang
+				tags[lyricsKey] = append(tags[lyricsKey], values...)
+			}
+		}
+	}
+
+	// If we found any language-specific lyrics from ID3v2 frames, remove the generic lyrics
+	for key := range tags {
+		if strings.HasPrefix(key, "lyrics:") && key != "lyrics" {
+			delete(tags, "lyrics")
+			break
+		}
+	}
+}
+
+const iTunesKeyPrefix = "----:com.apple.iTunes:"
+
+// parseMP4Atoms processes MP4 raw atoms to get iTunes-specific tags.
+func parseMP4Atoms(rawAtoms map[string][]string, tags map[string][]string) {
+	// Process all atoms and add them to tags
+	for key, values := range rawAtoms {
+		// Strip iTunes prefix and convert to lowercase
+		normalizedKey := strings.TrimPrefix(key, iTunesKeyPrefix)
+		normalizedKey = strings.ToLower(normalizedKey)
+
+		// Only add if the tag doesn't already exist (avoid duplication with PropertyMap)
+		if _, exists := tags[normalizedKey]; !exists {
+			tags[normalizedKey] = values
+		}
+	}
+}
+
+// parseASFAttributes processes ASF raw attributes to get WMA-specific tags.
+func parseASFAttributes(rawAttrs map[string][]string, tags map[string][]string) {
+	// Process all attributes and add them to tags
+	for key, values := range rawAttrs {
+		normalizedKey := strings.ToLower(key)
+
+		// Only add if the tag doesn't already exist (avoid duplication with PropertyMap)
+		if _, exists := tags[normalizedKey]; !exists {
+			tags[normalizedKey] = values
+		}
+	}
+}
+
+// These are the only roles we support, based on Picard's tag map:
+// https://picard-docs.musicbrainz.org/downloads/MusicBrainz_Picard_Tag_Map.html
+var tiplMapping = map[string]string{
+	"arranger": "arranger",
+	"engineer": "engineer",
+	"producer": "producer",
+	"mix":      "mixer",
+	"DJ-mix":   "djmixer",
+}
+
+// parseTIPL parses the ID3v2.4 TIPL frame string, which is received from TagLib in the format:
+//
+//	"arranger Andrew Powell engineer Chris Blair engineer Pat Stapley producer Eric Woolfson".
+//
+// and breaks it down into a map of roles and names, e.g.:
+//
+//	{"arranger": ["Andrew Powell"], "engineer": ["Chris Blair", "Pat Stapley"], "producer": ["Eric Woolfson"]}.
+func parseTIPL(tags map[string][]string) {
+	tipl := tags["tipl"]
+	if len(tipl) == 0 {
+		return
+	}
+	addRole := func(currentRole string, currentValue []string) {
+		if currentRole != "" && len(currentValue) > 0 {
+			role := tiplMapping[currentRole]
+			tags[role] = append(tags[role], strings.Join(currentValue, " "))
+		}
+	}
+	var currentRole string
+	var currentValue []string
+	for _, part := range strings.Split(tipl[0], " ") {
+		if _, ok := tiplMapping[part]; ok {
+			addRole(currentRole, currentValue)
+			currentRole = part
+			currentValue = nil
+			continue
+		}
+		currentValue = append(currentValue, part)
+	}
+	addRole(currentRole, currentValue)
+	delete(tags, "tipl")
+}
+
+var _ local.Extractor = (*extractor)(nil)
+
+func init() {
+	local.RegisterExtractor("taglib", func(fsys fs.FS, baseDir string) local.Extractor {
+		return &extractor{fsys}
+	})
+}

adapters/gotaglib/gotaglib_suite_test.go

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

adapters/gotaglib/gotaglib_test.go

@@ -0,0 +1,302 @@
+package gotaglib
+
+import (
+	"io/fs"
+	"os"
+	"strings"
+
+	"github.com/navidrome/navidrome/utils"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Extractor", func() {
+	var e *extractor
+
+	BeforeEach(func() {
+		e = &extractor{fs: os.DirFS(".")}
+	})
+
+	Describe("Parse", func() {
+		It("correctly parses metadata from all files in folder", func() {
+			mds, err := e.Parse(
+				"tests/fixtures/test.mp3",
+				"tests/fixtures/test.ogg",
+			)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(mds).To(HaveLen(2))
+
+			// Test MP3
+			m := mds["tests/fixtures/test.mp3"]
+			Expect(m.Tags).To(HaveKeyWithValue("title", []string{"Song"}))
+			Expect(m.Tags).To(HaveKeyWithValue("album", []string{"Album"}))
+			Expect(m.Tags).To(HaveKeyWithValue("artist", []string{"Artist"}))
+			Expect(m.Tags).To(HaveKeyWithValue("albumartist", []string{"Album Artist"}))
+
+			Expect(m.HasPicture).To(BeTrue())
+			Expect(m.AudioProperties.Duration.String()).To(Equal("1.02s"))
+			Expect(m.AudioProperties.BitRate).To(Equal(192))
+			Expect(m.AudioProperties.Channels).To(Equal(2))
+			Expect(m.AudioProperties.SampleRate).To(Equal(44100))
+
+			Expect(m.Tags).To(Or(
+				HaveKeyWithValue("compilation", []string{"1"}),
+				HaveKeyWithValue("tcmp", []string{"1"})),
+			)
+			Expect(m.Tags).To(HaveKeyWithValue("genre", []string{"Rock"}))
+			Expect(m.Tags).To(HaveKeyWithValue("date", []string{"2014-05-21"}))
+			Expect(m.Tags).To(HaveKeyWithValue("originaldate", []string{"1996-11-21"}))
+			Expect(m.Tags).To(HaveKeyWithValue("releasedate", []string{"2020-12-31"}))
+			Expect(m.Tags).To(HaveKeyWithValue("discnumber", []string{"1"}))
+			Expect(m.Tags).To(HaveKeyWithValue("disctotal", []string{"2"}))
+			Expect(m.Tags).To(HaveKeyWithValue("comment", []string{"Comment1\nComment2"}))
+			Expect(m.Tags).To(HaveKeyWithValue("bpm", []string{"123"}))
+			Expect(m.Tags).To(HaveKeyWithValue("replaygain_album_gain", []string{"+3.21518 dB"}))
+			Expect(m.Tags).To(HaveKeyWithValue("replaygain_album_peak", []string{"0.9125"}))
+			Expect(m.Tags).To(HaveKeyWithValue("replaygain_track_gain", []string{"-1.48 dB"}))
+			Expect(m.Tags).To(HaveKeyWithValue("replaygain_track_peak", []string{"0.4512"}))
+
+			Expect(m.Tags).To(HaveKeyWithValue("tracknumber", []string{"2"}))
+			Expect(m.Tags).To(HaveKeyWithValue("tracktotal", []string{"10"}))
+
+			Expect(m.Tags).ToNot(HaveKey("lyrics"))
+			Expect(m.Tags).To(Or(HaveKeyWithValue("lyrics:eng", []string{
+				"[00:00.00]This is\n[00:02.50]English SYLT\n",
+				"[00:00.00]This is\n[00:02.50]English",
+			}), HaveKeyWithValue("lyrics:eng", []string{
+				"[00:00.00]This is\n[00:02.50]English",
+				"[00:00.00]This is\n[00:02.50]English SYLT\n",
+			})))
+			Expect(m.Tags).To(Or(HaveKeyWithValue("lyrics:xxx", []string{
+				"[00:00.00]This is\n[00:02.50]unspecified SYLT\n",
+				"[00:00.00]This is\n[00:02.50]unspecified",
+			}), HaveKeyWithValue("lyrics:xxx", []string{
+				"[00:00.00]This is\n[00:02.50]unspecified",
+				"[00:00.00]This is\n[00:02.50]unspecified SYLT\n",
+			})))
+
+			// Test OGG
+			m = mds["tests/fixtures/test.ogg"]
+			Expect(err).To(BeNil())
+			Expect(m.Tags).To(HaveKeyWithValue("fbpm", []string{"141.7"}))
+
+			// TagLib 1.12 returns 18, previous versions return 39.
+			// See https://github.com/taglib/taglib/commit/2f238921824741b2cfe6fbfbfc9701d9827ab06b
+			Expect(m.AudioProperties.BitRate).To(BeElementOf(18, 19, 39, 40, 43, 49))
+			Expect(m.AudioProperties.Channels).To(BeElementOf(2))
+			Expect(m.AudioProperties.SampleRate).To(BeElementOf(8000))
+			Expect(m.HasPicture).To(BeTrue())
+		})
+
+		DescribeTable("Format-Specific tests",
+			func(file, duration string, channels, samplerate, bitdepth int, albumGain, albumPeak, trackGain, trackPeak string, id3Lyrics bool, image bool) {
+				file = "tests/fixtures/" + file
+				mds, err := e.Parse(file)
+				Expect(err).NotTo(HaveOccurred())
+				Expect(mds).To(HaveLen(1))
+
+				m := mds[file]
+
+				Expect(m.HasPicture).To(Equal(image))
+				Expect(m.AudioProperties.Duration.String()).To(Equal(duration))
+				Expect(m.AudioProperties.Channels).To(Equal(channels))
+				Expect(m.AudioProperties.SampleRate).To(Equal(samplerate))
+				Expect(m.AudioProperties.BitDepth).To(Equal(bitdepth))
+
+				Expect(m.Tags).To(Or(
+					HaveKeyWithValue("replaygain_album_gain", []string{albumGain}),
+					HaveKeyWithValue("----:com.apple.itunes:replaygain_album_gain", []string{albumGain}),
+				))
+
+				Expect(m.Tags).To(Or(
+					HaveKeyWithValue("replaygain_album_peak", []string{albumPeak}),
+					HaveKeyWithValue("----:com.apple.itunes:replaygain_album_peak", []string{albumPeak}),
+				))
+				Expect(m.Tags).To(Or(
+					HaveKeyWithValue("replaygain_track_gain", []string{trackGain}),
+					HaveKeyWithValue("----:com.apple.itunes:replaygain_track_gain", []string{trackGain}),
+				))
+				Expect(m.Tags).To(Or(
+					HaveKeyWithValue("replaygain_track_peak", []string{trackPeak}),
+					HaveKeyWithValue("----:com.apple.itunes:replaygain_track_peak", []string{trackPeak}),
+				))
+
+				Expect(m.Tags).To(HaveKeyWithValue("title", []string{"Title"}))
+				Expect(m.Tags).To(HaveKeyWithValue("album", []string{"Album"}))
+				Expect(m.Tags).To(HaveKeyWithValue("artist", []string{"Artist"}))
+				Expect(m.Tags).To(HaveKeyWithValue("albumartist", []string{"Album Artist"}))
+				Expect(m.Tags).To(HaveKeyWithValue("genre", []string{"Rock"}))
+				Expect(m.Tags).To(HaveKeyWithValue("date", []string{"2014"}))
+
+				Expect(m.Tags).To(HaveKeyWithValue("bpm", []string{"123"}))
+				Expect(m.Tags).To(Or(
+					HaveKeyWithValue("tracknumber", []string{"3"}),
+					HaveKeyWithValue("tracknumber", []string{"3/10"}),
+				))
+				if !strings.HasSuffix(file, "test.wma") {
+					// TODO Not sure why this is not working for WMA
+					Expect(m.Tags).To(HaveKeyWithValue("tracktotal", []string{"10"}))
+				}
+				Expect(m.Tags).To(Or(
+					HaveKeyWithValue("discnumber", []string{"1"}),
+					HaveKeyWithValue("discnumber", []string{"1/2"}),
+				))
+				Expect(m.Tags).To(HaveKeyWithValue("disctotal", []string{"2"}))
+
+				// WMA does not have a "compilation" tag, but "wm/iscompilation"
+				Expect(m.Tags).To(Or(
+					HaveKeyWithValue("compilation", []string{"1"}),
+					HaveKeyWithValue("wm/iscompilation", []string{"1"})),
+				)
+
+				if id3Lyrics {
+					Expect(m.Tags).To(HaveKeyWithValue("lyrics:eng", []string{
+						"[00:00.00]This is\n[00:02.50]English",
+					}))
+					Expect(m.Tags).To(HaveKeyWithValue("lyrics:xxx", []string{
+						"[00:00.00]This is\n[00:02.50]unspecified",
+					}))
+				} else {
+					Expect(m.Tags).To(HaveKeyWithValue("lyrics:xxx", []string{
+						"[00:00.00]This is\n[00:02.50]unspecified",
+						"[00:00.00]This is\n[00:02.50]English",
+					}))
+				}
+
+				Expect(m.Tags).To(HaveKeyWithValue("comment", []string{"Comment1\nComment2"}))
+			},
+
+			// ffmpeg -f lavfi -i "sine=frequency=1200:duration=1" test.flac
+			Entry("correctly parses flac tags", "test.flac", "1s", 1, 44100, 16, "+4.06 dB", "0.12496948", "+4.06 dB", "0.12496948", false, true),
+
+			Entry("correctly parses m4a (aac) gain tags", "01 Invisible (RED) Edit Version.m4a", "1.04s", 2, 44100, 16, "0.37", "0.48", "0.37", "0.48", false, true),
+			Entry("correctly parses m4a (aac) gain tags (uppercase)", "test.m4a", "1.04s", 2, 44100, 16, "0.37", "0.48", "0.37", "0.48", false, true),
+			Entry("correctly parses ogg (vorbis) tags", "test.ogg", "1.04s", 2, 8000, 0, "+7.64 dB", "0.11772506", "+7.64 dB", "0.11772506", false, true),
+
+			// ffmpeg -f lavfi -i "sine=frequency=900:duration=1" test.wma
+			// Weird note: for the tag parsing to work, the lyrics are actually stored in the reverse order
+			Entry("correctly parses wma/asf tags", "test.wma", "1.02s", 1, 44100, 16, "3.27 dB", "0.132914", "3.27 dB", "0.132914", false, true),
+
+			// ffmpeg -f lavfi -i "sine=frequency=800:duration=1" test.wv
+			Entry("correctly parses wv (wavpak) tags", "test.wv", "1s", 1, 44100, 16, "3.43 dB", "0.125061", "3.43 dB", "0.125061", false, true),
+
+			// ffmpeg -f lavfi -i "sine=frequency=1000:duration=1" test.wav
+			Entry("correctly parses wav tags", "test.wav", "1s", 1, 44100, 16, "3.06 dB", "0.125056", "3.06 dB", "0.125056", true, true),
+
+			// ffmpeg -f lavfi -i "sine=frequency=1400:duration=1" test.aiff
+			Entry("correctly parses aiff tags", "test.aiff", "1s", 1, 44100, 16, "2.00 dB", "0.124972", "2.00 dB", "0.124972", true, true),
+		)
+
+		// Skip these tests when running as root
+		Context("Access Forbidden", func() {
+			var accessForbiddenFile string
+			var RegularUserContext = XContext
+			var isRegularUser = os.Getuid() != 0
+			if isRegularUser {
+				RegularUserContext = Context
+			}
+
+			// Only run permission tests if we are not root
+			RegularUserContext("when run without root privileges", func() {
+				BeforeEach(func() {
+					// Use root fs for absolute paths in temp directory
+					e = &extractor{fs: os.DirFS("/")}
+					accessForbiddenFile = utils.TempFileName("access_forbidden-", ".mp3")
+
+					f, err := os.OpenFile(accessForbiddenFile, os.O_WRONLY|os.O_CREATE, 0222)
+					Expect(err).ToNot(HaveOccurred())
+
+					DeferCleanup(func() {
+						Expect(f.Close()).To(Succeed())
+						Expect(os.Remove(accessForbiddenFile)).To(Succeed())
+					})
+				})
+
+				It("correctly handle unreadable file due to insufficient read permission", func() {
+					// Strip leading slash for DirFS rooted at "/"
+					_, err := e.extractMetadata(accessForbiddenFile[1:])
+					Expect(err).To(MatchError(os.ErrPermission))
+				})
+
+				It("skips the file if it cannot be read", func() {
+					// Get current working directory to construct paths relative to root
+					cwd, err := os.Getwd()
+					Expect(err).ToNot(HaveOccurred())
+					// Strip leading slash for DirFS rooted at "/"
+					files := []string{
+						cwd[1:] + "/tests/fixtures/test.mp3",
+						cwd[1:] + "/tests/fixtures/test.ogg",
+						accessForbiddenFile[1:],
+					}
+					mds, err := e.Parse(files...)
+					Expect(err).NotTo(HaveOccurred())
+					Expect(mds).To(HaveLen(2))
+					Expect(mds).ToNot(HaveKey(accessForbiddenFile[1:]))
+				})
+			})
+		})
+
+	})
+
+	Describe("Error Checking", func() {
+		It("returns a generic ErrPath if file does not exist", func() {
+			testFilePath := "tests/fixtures/NON_EXISTENT.ogg"
+			_, err := e.extractMetadata(testFilePath)
+			Expect(err).To(MatchError(fs.ErrNotExist))
+		})
+		It("does not throw a SIGSEGV error when reading a file with an invalid frame", func() {
+			// File has an empty TDAT frame
+			md, err := e.extractMetadata("tests/fixtures/invalid-files/test-invalid-frame.mp3")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(md.Tags).To(HaveKeyWithValue("albumartist", []string{"Elvis Presley"}))
+		})
+	})
+
+	Describe("parseTIPL", func() {
+		var tags map[string][]string
+
+		BeforeEach(func() {
+			tags = make(map[string][]string)
+		})
+
+		Context("when the TIPL string is populated", func() {
+			It("correctly parses roles and names", func() {
+				tags["tipl"] = []string{"arranger Andrew Powell DJ-mix François Kevorkian DJ-mix Jane Doe engineer Chris Blair"}
+				parseTIPL(tags)
+				Expect(tags["arranger"]).To(ConsistOf("Andrew Powell"))
+				Expect(tags["engineer"]).To(ConsistOf("Chris Blair"))
+				Expect(tags["djmixer"]).To(ConsistOf("François Kevorkian", "Jane Doe"))
+			})
+
+			It("handles multiple names for a single role", func() {
+				tags["tipl"] = []string{"engineer Pat Stapley producer Eric Woolfson engineer Chris Blair"}
+				parseTIPL(tags)
+				Expect(tags["producer"]).To(ConsistOf("Eric Woolfson"))
+				Expect(tags["engineer"]).To(ConsistOf("Pat Stapley", "Chris Blair"))
+			})
+
+			It("discards roles without names", func() {
+				tags["tipl"] = []string{"engineer Pat Stapley producer engineer Chris Blair"}
+				parseTIPL(tags)
+				Expect(tags).ToNot(HaveKey("producer"))
+				Expect(tags["engineer"]).To(ConsistOf("Pat Stapley", "Chris Blair"))
+			})
+		})
+
+		Context("when the TIPL string is empty", func() {
+			It("does nothing", func() {
+				tags["tipl"] = []string{""}
+				parseTIPL(tags)
+				Expect(tags).To(BeEmpty())
+			})
+		})
+
+		Context("when the TIPL is not present", func() {
+			It("does nothing", func() {
+				parseTIPL(tags)
+				Expect(tags).To(BeEmpty())
+			})
+		})
+	})
+
+})

adapters/lastfm/agent.go

@@ -192,6 +192,26 @@ func (l *lastfmAgent) GetArtistTopSongs(ctx context.Context, id, artistName, mbi
 	return res, nil
 }
 
+func (l *lastfmAgent) GetSimilarSongsByTrack(ctx context.Context, id, name, artist, mbid string, count int) ([]agents.Song, error) {
+	resp, err := l.callTrackGetSimilar(ctx, name, artist, count)
+	if err != nil {
+		return nil, err
+	}
+	if len(resp) == 0 {
+		return nil, agents.ErrNotFound
+	}
+	res := make([]agents.Song, 0, len(resp))
+	for _, t := range resp {
+		res = append(res, agents.Song{
+			Name:       t.Name,
+			MBID:       t.MBID,
+			Artist:     t.Artist.Name,
+			ArtistMBID: t.Artist.MBID,
+		})
+	}
+	return res, nil
+}
+
 var (
 	artistOpenGraphQuery = cascadia.MustCompile(`html > head > meta[property="og:image"]`)
 	artistIgnoredImage   = "2a96cbd8b46e442fc41c2b86b821562f" // Last.fm artist placeholder image name
@@ -290,6 +310,15 @@ func (l *lastfmAgent) callArtistGetTopTracks(ctx context.Context, artistName str
 	return t.Track, nil
 }
 
+func (l *lastfmAgent) callTrackGetSimilar(ctx context.Context, name, artist string, count int) ([]SimilarTrack, error) {
+	s, err := l.client.trackGetSimilar(ctx, name, artist, count)
+	if err != nil {
+		log.Error(ctx, "Error calling LastFM/track.getSimilar", "track", name, "artist", artist, err)
+		return nil, err
+	}
+	return s.Track, nil
+}
+
 func (l *lastfmAgent) getArtistForScrobble(track *model.MediaFile, role model.Role, displayName string) string {
 	if conf.Server.LastFM.ScrobbleFirstArtistOnly && len(track.Participants[role]) > 0 {
 		return track.Participants[role][0].Name

adapters/lastfm/agent_test.go

@@ -177,6 +177,54 @@ var _ = Describe("lastfmAgent", func() {
 		})
 	})
 
+	Describe("GetSimilarSongsByTrack", func() {
+		var agent *lastfmAgent
+		var httpClient *tests.FakeHttpClient
+		BeforeEach(func() {
+			httpClient = &tests.FakeHttpClient{}
+			client := newClient("API_KEY", "SECRET", "pt", httpClient)
+			agent = lastFMConstructor(ds)
+			agent.client = client
+		})
+
+		It("returns similar songs", func() {
+			f, _ := os.Open("tests/fixtures/lastfm.track.getsimilar.json")
+			httpClient.Res = http.Response{Body: f, StatusCode: 200}
+			Expect(agent.GetSimilarSongsByTrack(ctx, "123", "Just Can't Get Enough", "Depeche Mode", "", 5)).To(Equal([]agents.Song{
+				{Name: "Dreaming of Me", MBID: "027b553e-7c74-3ed4-a95e-1d4fea51f174", Artist: "Depeche Mode", ArtistMBID: "8538e728-ca0b-4321-b7e5-cff6565dd4c0"},
+				{Name: "Everything Counts", MBID: "5a5a3ca4-bdb8-4641-a674-9b54b9b319a6", Artist: "Depeche Mode", ArtistMBID: "8538e728-ca0b-4321-b7e5-cff6565dd4c0"},
+				{Name: "Don't You Want Me", MBID: "", Artist: "The Human League", ArtistMBID: "7adaabfb-acfb-47bc-8c7c-59471c2f0db8"},
+				{Name: "Tainted Love", MBID: "", Artist: "Soft Cell", ArtistMBID: "7fb50287-029d-47cc-825a-235ca28024b2"},
+				{Name: "Blue Monday", MBID: "727e84c6-1b56-31dd-a958-a5f46305cec0", Artist: "New Order", ArtistMBID: "f1106b17-dcbb-45f6-b938-199ccfab50cc"},
+			}))
+			Expect(httpClient.RequestCount).To(Equal(1))
+			Expect(httpClient.SavedRequest.URL.Query().Get("track")).To(Equal("Just Can't Get Enough"))
+			Expect(httpClient.SavedRequest.URL.Query().Get("artist")).To(Equal("Depeche Mode"))
+		})
+
+		It("returns ErrNotFound when no similar songs found", func() {
+			f, _ := os.Open("tests/fixtures/lastfm.track.getsimilar.unknown.json")
+			httpClient.Res = http.Response{Body: f, StatusCode: 200}
+			_, err := agent.GetSimilarSongsByTrack(ctx, "123", "UnknownTrack", "UnknownArtist", "", 3)
+			Expect(err).To(MatchError(agents.ErrNotFound))
+			Expect(httpClient.RequestCount).To(Equal(1))
+		})
+
+		It("returns an error if Last.fm call fails", func() {
+			httpClient.Err = errors.New("error")
+			_, err := agent.GetSimilarSongsByTrack(ctx, "123", "Believe", "Cher", "", 3)
+			Expect(err).To(HaveOccurred())
+			Expect(httpClient.RequestCount).To(Equal(1))
+		})
+
+		It("returns an error if Last.fm call returns an error", func() {
+			httpClient.Res = http.Response{Body: io.NopCloser(bytes.NewBufferString(lastfmError3)), StatusCode: 200}
+			_, err := agent.GetSimilarSongsByTrack(ctx, "123", "Believe", "Cher", "", 3)
+			Expect(err).To(HaveOccurred())
+			Expect(httpClient.RequestCount).To(Equal(1))
+		})
+	})
+
 	Describe("Scrobbling", func() {
 		var agent *lastfmAgent
 		var httpClient *tests.FakeHttpClient

adapters/lastfm/client.go

@@ -95,6 +95,19 @@ func (c *client) artistGetTopTracks(ctx context.Context, name string, limit int)
 	return &response.TopTracks, nil
 }
 
+func (c *client) trackGetSimilar(ctx context.Context, name, artist string, limit int) (*SimilarTracks, error) {
+	params := url.Values{}
+	params.Add("method", "track.getSimilar")
+	params.Add("track", name)
+	params.Add("artist", artist)
+	params.Add("limit", strconv.Itoa(limit))
+	response, err := c.makeRequest(ctx, http.MethodGet, params, false)
+	if err != nil {
+		return nil, err
+	}
+	return &response.SimilarTracks, nil
+}
+
 func (c *client) GetToken(ctx context.Context) (string, error) {
 	params := url.Values{}
 	params.Add("method", "auth.getToken")

adapters/lastfm/client_test.go

@@ -121,6 +121,30 @@ var _ = Describe("client", func() {
 		})
 	})
 
+	Describe("trackGetSimilar", func() {
+		It("returns similar tracks for a successful response", func() {
+			f, _ := os.Open("tests/fixtures/lastfm.track.getsimilar.json")
+			httpClient.Res = http.Response{Body: f, StatusCode: 200}
+
+			similar, err := client.trackGetSimilar(context.Background(), "Just Can't Get Enough", "Depeche Mode", 5)
+			Expect(err).To(BeNil())
+			Expect(len(similar.Track)).To(Equal(5))
+			Expect(similar.Track[0].Name).To(Equal("Dreaming of Me"))
+			Expect(similar.Track[0].Artist.Name).To(Equal("Depeche Mode"))
+			Expect(similar.Track[0].Match).To(Equal(1.0))
+			Expect(httpClient.SavedRequest.URL.String()).To(Equal(apiBaseUrl + "?api_key=API_KEY&artist=Depeche+Mode&format=json&limit=5&method=track.getSimilar&track=Just+Can%27t+Get+Enough"))
+		})
+
+		It("returns empty list when no similar tracks found", func() {
+			f, _ := os.Open("tests/fixtures/lastfm.track.getsimilar.unknown.json")
+			httpClient.Res = http.Response{Body: f, StatusCode: 200}
+
+			similar, err := client.trackGetSimilar(context.Background(), "UnknownTrack", "UnknownArtist", 3)
+			Expect(err).To(BeNil())
+			Expect(similar.Track).To(BeEmpty())
+		})
+	})
+
 	Describe("GetToken", func() {
 		It("returns a token when the request is successful", func() {
 			httpClient.Res = http.Response{

adapters/lastfm/responses.go

@@ -5,6 +5,7 @@ type Response struct {
 	SimilarArtists SimilarArtists `json:"similarartists"`
 	TopTracks      TopTracks      `json:"toptracks"`
 	Album          Album          `json:"album"`
+	SimilarTracks  SimilarTracks  `json:"similartracks"`
 	Error          int            `json:"error"`
 	Message        string         `json:"message"`
 	Token          string         `json:"token"`
@@ -59,6 +60,28 @@ type TopTracks struct {
 	Attr  Attr    `json:"@attr"`
 }
 
+type SimilarTracks struct {
+	Track []SimilarTrack `json:"track"`
+	Attr  SimilarAttr    `json:"@attr"`
+}
+
+type SimilarTrack struct {
+	Name   string             `json:"name"`
+	MBID   string             `json:"mbid"`
+	Match  float64            `json:"match"`
+	Artist SimilarTrackArtist `json:"artist"`
+}
+
+type SimilarTrackArtist struct {
+	Name string `json:"name"`
+	MBID string `json:"mbid"`
+}
+
+type SimilarAttr struct {
+	Artist string `json:"artist"`
+	Track  string `json:"track"`
+}
+
 type Session struct {
 	Name       string `json:"name"`
 	Key        string `json:"key"`

adapters/taglib/end_to_end_test.go

@@ -151,11 +151,7 @@ var _ = Describe("Extractor", func() {
 			unsSylt := makeLyrics("xxx", "unspecified SYLT")
 			unsUslt := makeLyrics("xxx", "unspecified")
 
-			// Why is the order inconsistent between runs? Nobody knows
-			Expect(lyrics).To(Or(
-				Equal(model.LyricList{engSylt, engUslt, unsSylt, unsUslt}),
-				Equal(model.LyricList{unsSylt, unsUslt, engSylt, engUslt}),
-			))
+			Expect(lyrics).To(ConsistOf(engSylt, engUslt, unsSylt, unsUslt))
 		})
 
 		DescribeTable("format-specific lyrics", func(file string, isId3 bool) {

adapters/taglib/taglib.go

@@ -168,7 +168,7 @@ func parseTIPL(tags map[string][]string) {
 var _ local.Extractor = (*extractor)(nil)
 
 func init() {
-	local.RegisterExtractor("taglib", func(_ fs.FS, baseDir string) local.Extractor {
+	local.RegisterExtractor("legacy-taglib", func(_ fs.FS, baseDir string) local.Extractor {
 		// ignores fs, as taglib extractor only works with local files
 		return &extractor{baseDir}
 	})

adapters/taglib/taglib_test.go

@@ -80,12 +80,11 @@ var _ = Describe("Extractor", func() {
 			Expect(err).To(BeNil())
 			Expect(m.Tags).To(HaveKeyWithValue("fbpm", []string{"141.7"}))
 
-			// TabLib 1.12 returns 18, previous versions return 39.
+			// TagLib 1.12 returns 18, previous versions return 39.
 			// See https://github.com/taglib/taglib/commit/2f238921824741b2cfe6fbfbfc9701d9827ab06b
 			Expect(m.AudioProperties.BitRate).To(BeElementOf(18, 19, 39, 40, 43, 49))
 			Expect(m.AudioProperties.Channels).To(BeElementOf(2))
 			Expect(m.AudioProperties.SampleRate).To(BeElementOf(8000))
-			Expect(m.AudioProperties.SampleRate).To(BeElementOf(8000))
 			Expect(m.HasPicture).To(BeTrue())
 		})
 
@@ -106,7 +105,7 @@ var _ = Describe("Extractor", func() {
 
 				Expect(m.Tags).To(Or(
 					HaveKeyWithValue("replaygain_album_gain", []string{albumGain}),
-					HaveKeyWithValue("----:com.apple.itunes:replaygain_track_gain", []string{albumGain}),
+					HaveKeyWithValue("----:com.apple.itunes:replaygain_album_gain", []string{albumGain}),
 				))
 
 				Expect(m.Tags).To(Or(

adapters/taglib/taglib_wrapper.go

@@ -1,7 +1,8 @@
 package taglib
 
 /*
-#cgo pkg-config: taglib
+#cgo !windows pkg-config: --define-prefix taglib
+#cgo windows pkg-config: taglib
 #cgo illumos LDFLAGS: -lstdc++ -lsendfile
 #cgo linux darwin CXXFLAGS: -std=c++11
 #cgo darwin LDFLAGS: -L/opt/homebrew/opt/taglib/lib

cmd/root.go

@@ -24,6 +24,7 @@ import (
 
 	// Import adapters to register them
 	_ "github.com/navidrome/navidrome/adapters/deezer"
+	_ "github.com/navidrome/navidrome/adapters/gotaglib"
 	_ "github.com/navidrome/navidrome/adapters/lastfm"
 	_ "github.com/navidrome/navidrome/adapters/listenbrainz"
 	_ "github.com/navidrome/navidrome/adapters/spotify"

cmd/wire_gen.go

@@ -33,6 +33,7 @@ import (
 
 import (
 	_ "github.com/navidrome/navidrome/adapters/deezer"
+	_ "github.com/navidrome/navidrome/adapters/gotaglib"
 	_ "github.com/navidrome/navidrome/adapters/lastfm"
 	_ "github.com/navidrome/navidrome/adapters/listenbrainz"
 	_ "github.com/navidrome/navidrome/adapters/spotify"

conf/configuration.go

@@ -126,6 +126,7 @@ type configOptions struct {
 	DevExternalScanner                bool
 	DevScannerThreads                 uint
 	DevSelectiveWatcher               bool
+	DevLegacyEmbedImage               bool
 	DevInsightsInitialDelay           time.Duration
 	DevEnablePlayerInsights           bool
 	DevEnablePluginsInsights          bool
@@ -152,6 +153,7 @@ type subsonicOptions struct {
 	AppendSubtitle        bool
 	ArtistParticipations  bool
 	DefaultReportRealPath bool
+	EnableAverageRating   bool
 	LegacyClients         string
 	MinimalClients        string
 }
@@ -366,10 +368,6 @@ func Load(noConfigDump bool) {
 		disableExternalServices()
 	}
 
-	if Server.Scanner.Extractor != consts.DefaultScannerExtractor {
-		log.Warn(fmt.Sprintf("Extractor '%s' is not implemented, using 'taglib'", Server.Scanner.Extractor))
-		Server.Scanner.Extractor = consts.DefaultScannerExtractor
-	}
 	logDeprecatedOptions("Scanner.GenreSeparators", "")
 	logDeprecatedOptions("Scanner.GroupAlbumReleases", "")
 	logDeprecatedOptions("DevEnableBufferedScrobble", "") // Deprecated: Buffered scrobbling is now always enabled and this option is ignored
@@ -609,6 +607,7 @@ func setViperDefaults() {
 	viper.SetDefault("subsonic.appendsubtitle", true)
 	viper.SetDefault("subsonic.artistparticipations", false)
 	viper.SetDefault("subsonic.defaultreportrealpath", false)
+	viper.SetDefault("subsonic.enableaveragerating", true)
 	viper.SetDefault("subsonic.legacyclients", "DSub,SubMusic")
 	viper.SetDefault("agents", "lastfm,spotify,deezer")
 	viper.SetDefault("lastfm.enabled", true)

core/agents/agents.go

@@ -22,6 +22,8 @@ type PluginLoader interface {
 	LoadMediaAgent(name string) (Interface, bool)
 }
 
+// Agents is a meta-agent that aggregates multiple built-in and plugin agents. It tries each enabled agent in order
+// until one returns valid data.
 type Agents struct {
 	ds           model.DataStore
 	pluginLoader PluginLoader
@@ -129,26 +131,14 @@ func (a *Agents) GetArtistMBID(ctx context.Context, id string, name string) (str
 	case consts.VariousArtistsID:
 		return "", nil
 	}
-	start := time.Now()
-	for _, enabledAgent := range a.getEnabledAgentNames() {
-		ag := a.getAgent(enabledAgent)
-		if ag == nil {
-			continue
-		}
-		if utils.IsCtxDone(ctx) {
-			break
-		}
+
+	return callAgentMethod(ctx, a, "GetArtistMBID", func(ag Interface) (string, error) {
 		retriever, ok := ag.(ArtistMBIDRetriever)
 		if !ok {
-			continue
+			return "", ErrNotFound
 		}
-		mbid, err := retriever.GetArtistMBID(ctx, id, name)
-		if mbid != "" && err == nil {
-			log.Debug(ctx, "Got MBID", "agent", ag.AgentName(), "artist", name, "mbid", mbid, "elapsed", time.Since(start))
-			return mbid, nil
-		}
-	}
-	return "", ErrNotFound
+		return retriever.GetArtistMBID(ctx, id, name)
+	})
 }
 
 func (a *Agents) GetArtistURL(ctx context.Context, id, name, mbid string) (string, error) {
@@ -158,26 +148,14 @@ func (a *Agents) GetArtistURL(ctx context.Context, id, name, mbid string) (strin
 	case consts.VariousArtistsID:
 		return "", nil
 	}
-	start := time.Now()
-	for _, enabledAgent := range a.getEnabledAgentNames() {
-		ag := a.getAgent(enabledAgent)
-		if ag == nil {
-			continue
-		}
-		if utils.IsCtxDone(ctx) {
-			break
-		}
+
+	return callAgentMethod(ctx, a, "GetArtistURL", func(ag Interface) (string, error) {
 		retriever, ok := ag.(ArtistURLRetriever)
 		if !ok {
-			continue
+			return "", ErrNotFound
 		}
-		url, err := retriever.GetArtistURL(ctx, id, name, mbid)
-		if url != "" && err == nil {
-			log.Debug(ctx, "Got External Url", "agent", ag.AgentName(), "artist", name, "url", url, "elapsed", time.Since(start))
-			return url, nil
-		}
-	}
-	return "", ErrNotFound
+		return retriever.GetArtistURL(ctx, id, name, mbid)
+	})
 }
 
 func (a *Agents) GetArtistBiography(ctx context.Context, id, name, mbid string) (string, error) {
@@ -187,26 +165,14 @@ func (a *Agents) GetArtistBiography(ctx context.Context, id, name, mbid string)
 	case consts.VariousArtistsID:
 		return "", nil
 	}
-	start := time.Now()
-	for _, enabledAgent := range a.getEnabledAgentNames() {
-		ag := a.getAgent(enabledAgent)
-		if ag == nil {
-			continue
-		}
-		if utils.IsCtxDone(ctx) {
-			break
-		}
+
+	return callAgentMethod(ctx, a, "GetArtistBiography", func(ag Interface) (string, error) {
 		retriever, ok := ag.(ArtistBiographyRetriever)
 		if !ok {
-			continue
+			return "", ErrNotFound
 		}
-		bio, err := retriever.GetArtistBiography(ctx, id, name, mbid)
-		if err == nil {
-			log.Debug(ctx, "Got Biography", "agent", ag.AgentName(), "artist", name, "len", len(bio), "elapsed", time.Since(start))
-			return bio, nil
-		}
-	}
-	return "", ErrNotFound
+		return retriever.GetArtistBiography(ctx, id, name, mbid)
+	})
 }
 
 // GetSimilarArtists returns similar artists by id, name, and/or mbid. Because some artists returned from an enabled
@@ -254,26 +220,14 @@ func (a *Agents) GetArtistImages(ctx context.Context, id, name, mbid string) ([]
 	case consts.VariousArtistsID:
 		return nil, nil
 	}
-	start := time.Now()
-	for _, enabledAgent := range a.getEnabledAgentNames() {
-		ag := a.getAgent(enabledAgent)
-		if ag == nil {
-			continue
-		}
-		if utils.IsCtxDone(ctx) {
-			break
-		}
+
+	return callAgentSliceMethod(ctx, a, "GetArtistImages", func(ag Interface) ([]ExternalImage, error) {
 		retriever, ok := ag.(ArtistImageRetriever)
 		if !ok {
-			continue
+			return nil, ErrNotFound
 		}
-		images, err := retriever.GetArtistImages(ctx, id, name, mbid)
-		if len(images) > 0 && err == nil {
-			log.Debug(ctx, "Got Images", "agent", ag.AgentName(), "artist", name, "images", images, "elapsed", time.Since(start))
-			return images, nil
-		}
-	}
-	return nil, ErrNotFound
+		return retriever.GetArtistImages(ctx, id, name, mbid)
+	})
 }
 
 // GetArtistTopSongs returns top songs by id, name, and/or mbid. Because some songs returned from an enabled
@@ -288,80 +242,127 @@ func (a *Agents) GetArtistTopSongs(ctx context.Context, id, artistName, mbid str
 
 	overLimit := int(float64(count) * conf.Server.DevExternalArtistFetchMultiplier)
 
-	start := time.Now()
-	for _, enabledAgent := range a.getEnabledAgentNames() {
-		ag := a.getAgent(enabledAgent)
-		if ag == nil {
-			continue
-		}
-		if utils.IsCtxDone(ctx) {
-			break
-		}
+	return callAgentSliceMethod(ctx, a, "GetArtistTopSongs", func(ag Interface) ([]Song, error) {
 		retriever, ok := ag.(ArtistTopSongsRetriever)
 		if !ok {
-			continue
+			return nil, ErrNotFound
 		}
-		songs, err := retriever.GetArtistTopSongs(ctx, id, artistName, mbid, overLimit)
-		if len(songs) > 0 && err == nil {
-			log.Debug(ctx, "Got Top Songs", "agent", ag.AgentName(), "artist", artistName, "songs", songs, "elapsed", time.Since(start))
-			return songs, nil
-		}
-	}
-	return nil, ErrNotFound
+		return retriever.GetArtistTopSongs(ctx, id, artistName, mbid, overLimit)
+	})
 }
 
 func (a *Agents) GetAlbumInfo(ctx context.Context, name, artist, mbid string) (*AlbumInfo, error) {
 	if name == consts.UnknownAlbum {
 		return nil, ErrNotFound
 	}
-	start := time.Now()
-	for _, enabledAgent := range a.getEnabledAgentNames() {
-		ag := a.getAgent(enabledAgent)
-		if ag == nil {
-			continue
-		}
-		if utils.IsCtxDone(ctx) {
-			break
-		}
+
+	return callAgentMethod(ctx, a, "GetAlbumInfo", func(ag Interface) (*AlbumInfo, error) {
 		retriever, ok := ag.(AlbumInfoRetriever)
 		if !ok {
-			continue
+			return nil, ErrNotFound
 		}
-		album, err := retriever.GetAlbumInfo(ctx, name, artist, mbid)
-		if err == nil {
-			log.Debug(ctx, "Got Album Info", "agent", ag.AgentName(), "album", name, "artist", artist,
-				"mbid", mbid, "elapsed", time.Since(start))
-			return album, nil
-		}
-	}
-	return nil, ErrNotFound
+		return retriever.GetAlbumInfo(ctx, name, artist, mbid)
+	})
 }
 
 func (a *Agents) GetAlbumImages(ctx context.Context, name, artist, mbid string) ([]ExternalImage, error) {
 	if name == consts.UnknownAlbum {
 		return nil, ErrNotFound
 	}
+
+	return callAgentSliceMethod(ctx, a, "GetAlbumImages", func(ag Interface) ([]ExternalImage, error) {
+		retriever, ok := ag.(AlbumImageRetriever)
+		if !ok {
+			return nil, ErrNotFound
+		}
+		return retriever.GetAlbumImages(ctx, name, artist, mbid)
+	})
+}
+
+// GetSimilarSongsByTrack returns similar songs for a given track.
+func (a *Agents) GetSimilarSongsByTrack(ctx context.Context, id, name, artist, mbid string, count int) ([]Song, error) {
+	return callAgentSliceMethod(ctx, a, "GetSimilarSongsByTrack", func(ag Interface) ([]Song, error) {
+		retriever, ok := ag.(SimilarSongsByTrackRetriever)
+		if !ok {
+			return nil, ErrNotFound
+		}
+		return retriever.GetSimilarSongsByTrack(ctx, id, name, artist, mbid, count)
+	})
+}
+
+// GetSimilarSongsByAlbum returns similar songs for a given album.
+func (a *Agents) GetSimilarSongsByAlbum(ctx context.Context, id, name, artist, mbid string, count int) ([]Song, error) {
+	return callAgentSliceMethod(ctx, a, "GetSimilarSongsByAlbum", func(ag Interface) ([]Song, error) {
+		retriever, ok := ag.(SimilarSongsByAlbumRetriever)
+		if !ok {
+			return nil, ErrNotFound
+		}
+		return retriever.GetSimilarSongsByAlbum(ctx, id, name, artist, mbid, count)
+	})
+}
+
+// GetSimilarSongsByArtist returns similar songs for a given artist.
+func (a *Agents) GetSimilarSongsByArtist(ctx context.Context, id, name, mbid string, count int) ([]Song, error) {
+	switch id {
+	case consts.UnknownArtistID:
+		return nil, ErrNotFound
+	case consts.VariousArtistsID:
+		return nil, nil
+	}
+
+	return callAgentSliceMethod(ctx, a, "GetSimilarSongsByArtist", func(ag Interface) ([]Song, error) {
+		retriever, ok := ag.(SimilarSongsByArtistRetriever)
+		if !ok {
+			return nil, ErrNotFound
+		}
+		return retriever.GetSimilarSongsByArtist(ctx, id, name, mbid, count)
+	})
+}
+
+func callAgentMethod[T comparable](ctx context.Context, agents *Agents, methodName string, fn func(Interface) (T, error)) (T, error) {
+	var zero T
 	start := time.Now()
-	for _, enabledAgent := range a.getEnabledAgentNames() {
-		ag := a.getAgent(enabledAgent)
+	for _, enabledAgent := range agents.getEnabledAgentNames() {
+		ag := agents.getAgent(enabledAgent)
 		if ag == nil {
 			continue
 		}
 		if utils.IsCtxDone(ctx) {
 			break
 		}
-		retriever, ok := ag.(AlbumImageRetriever)
-		if !ok {
+		result, err := fn(ag)
+		if err != nil {
+			log.Trace(ctx, "Agent method call error", "method", methodName, "agent", ag.AgentName(), "error", err)
 			continue
 		}
-		images, err := retriever.GetAlbumImages(ctx, name, artist, mbid)
-		if err != nil {
-			log.Trace(ctx, "Agent GetAlbumImages failed", "agent", ag.AgentName(), "album", name, "artist", artist, "mbid", mbid, err)
+
+		if result != zero {
+			log.Debug(ctx, "Got result", "method", methodName, "agent", ag.AgentName(), "elapsed", time.Since(start))
+			return result, nil
 		}
-		if len(images) > 0 && err == nil {
-			log.Debug(ctx, "Got Album Images", "agent", ag.AgentName(), "album", name, "artist", artist,
-				"mbid", mbid, "elapsed", time.Since(start))
-			return images, nil
+	}
+	return zero, ErrNotFound
+}
+
+func callAgentSliceMethod[T any](ctx context.Context, agents *Agents, methodName string, fn func(Interface) ([]T, error)) ([]T, error) {
+	start := time.Now()
+	for _, enabledAgent := range agents.getEnabledAgentNames() {
+		ag := agents.getAgent(enabledAgent)
+		if ag == nil {
+			continue
+		}
+		if utils.IsCtxDone(ctx) {
+			break
+		}
+		results, err := fn(ag)
+		if err != nil {
+			log.Trace(ctx, "Agent method call error", "method", methodName, "agent", ag.AgentName(), "error", err)
+			continue
+		}
+
+		if len(results) > 0 {
+			log.Debug(ctx, "Got results", "method", methodName, "agent", ag.AgentName(), "count", len(results), "elapsed", time.Since(start))
+			return results, nil
 		}
 	}
 	return nil, ErrNotFound
@@ -376,3 +377,6 @@ var _ ArtistImageRetriever = (*Agents)(nil)
 var _ ArtistTopSongsRetriever = (*Agents)(nil)
 var _ AlbumInfoRetriever = (*Agents)(nil)
 var _ AlbumImageRetriever = (*Agents)(nil)
+var _ SimilarSongsByTrackRetriever = (*Agents)(nil)
+var _ SimilarSongsByAlbumRetriever = (*Agents)(nil)
+var _ SimilarSongsByArtistRetriever = (*Agents)(nil)

core/agents/agents_test.go

@@ -295,6 +295,72 @@ var _ = Describe("Agents", func() {
 				Expect(mock.Args).To(BeEmpty())
 			})
 		})
+
+		Describe("GetSimilarSongsByTrack", func() {
+			It("returns on first match", func() {
+				Expect(ag.GetSimilarSongsByTrack(ctx, "123", "test song", "test artist", "mb123", 2)).To(Equal([]Song{{
+					Name: "Similar Song",
+					MBID: "mbid555",
+				}}))
+				Expect(mock.Args).To(HaveExactElements("123", "test song", "test artist", "mb123", 2))
+			})
+			It("skips the agent if it returns an error", func() {
+				mock.Err = errors.New("error")
+				_, err := ag.GetSimilarSongsByTrack(ctx, "123", "test song", "test artist", "mb123", 2)
+				Expect(err).To(MatchError(ErrNotFound))
+				Expect(mock.Args).To(HaveExactElements("123", "test song", "test artist", "mb123", 2))
+			})
+			It("interrupts if the context is canceled", func() {
+				cancel()
+				_, err := ag.GetSimilarSongsByTrack(ctx, "123", "test song", "test artist", "mb123", 2)
+				Expect(err).To(MatchError(ErrNotFound))
+				Expect(mock.Args).To(BeEmpty())
+			})
+		})
+
+		Describe("GetSimilarSongsByAlbum", func() {
+			It("returns on first match", func() {
+				Expect(ag.GetSimilarSongsByAlbum(ctx, "123", "test album", "test artist", "mb123", 2)).To(Equal([]Song{{
+					Name: "Album Similar Song",
+					MBID: "mbid666",
+				}}))
+				Expect(mock.Args).To(HaveExactElements("123", "test album", "test artist", "mb123", 2))
+			})
+			It("skips the agent if it returns an error", func() {
+				mock.Err = errors.New("error")
+				_, err := ag.GetSimilarSongsByAlbum(ctx, "123", "test album", "test artist", "mb123", 2)
+				Expect(err).To(MatchError(ErrNotFound))
+				Expect(mock.Args).To(HaveExactElements("123", "test album", "test artist", "mb123", 2))
+			})
+			It("interrupts if the context is canceled", func() {
+				cancel()
+				_, err := ag.GetSimilarSongsByAlbum(ctx, "123", "test album", "test artist", "mb123", 2)
+				Expect(err).To(MatchError(ErrNotFound))
+				Expect(mock.Args).To(BeEmpty())
+			})
+		})
+
+		Describe("GetSimilarSongsByArtist", func() {
+			It("returns on first match", func() {
+				Expect(ag.GetSimilarSongsByArtist(ctx, "123", "test artist", "mb123", 2)).To(Equal([]Song{{
+					Name: "Artist Similar Song",
+					MBID: "mbid777",
+				}}))
+				Expect(mock.Args).To(HaveExactElements("123", "test artist", "mb123", 2))
+			})
+			It("skips the agent if it returns an error", func() {
+				mock.Err = errors.New("error")
+				_, err := ag.GetSimilarSongsByArtist(ctx, "123", "test artist", "mb123", 2)
+				Expect(err).To(MatchError(ErrNotFound))
+				Expect(mock.Args).To(HaveExactElements("123", "test artist", "mb123", 2))
+			})
+			It("interrupts if the context is canceled", func() {
+				cancel()
+				_, err := ag.GetSimilarSongsByArtist(ctx, "123", "test artist", "mb123", 2)
+				Expect(err).To(MatchError(ErrNotFound))
+				Expect(mock.Args).To(BeEmpty())
+			})
+		})
 	})
 })
 
@@ -377,6 +443,39 @@ func (a *mockAgent) GetAlbumInfo(ctx context.Context, name, artist, mbid string)
 	}, nil
 }
 
+func (a *mockAgent) GetSimilarSongsByTrack(_ context.Context, id, name, artist, mbid string, count int) ([]Song, error) {
+	a.Args = []interface{}{id, name, artist, mbid, count}
+	if a.Err != nil {
+		return nil, a.Err
+	}
+	return []Song{{
+		Name: "Similar Song",
+		MBID: "mbid555",
+	}}, nil
+}
+
+func (a *mockAgent) GetSimilarSongsByAlbum(_ context.Context, id, name, artist, mbid string, count int) ([]Song, error) {
+	a.Args = []interface{}{id, name, artist, mbid, count}
+	if a.Err != nil {
+		return nil, a.Err
+	}
+	return []Song{{
+		Name: "Album Similar Song",
+		MBID: "mbid666",
+	}}, nil
+}
+
+func (a *mockAgent) GetSimilarSongsByArtist(_ context.Context, id, name, mbid string, count int) ([]Song, error) {
+	a.Args = []interface{}{id, name, mbid, count}
+	if a.Err != nil {
+		return nil, a.Err
+	}
+	return []Song{{
+		Name: "Artist Similar Song",
+		MBID: "mbid777",
+	}}, nil
+}
+
 type emptyAgent struct {
 	Interface
 }

core/agents/interfaces.go

@@ -33,9 +33,13 @@ type ExternalImage struct {
 }
 
 type Song struct {
-	ID   string
-	Name string
-	MBID string
+	ID         string
+	Name       string
+	MBID       string
+	Artist     string
+	ArtistMBID string
+	Album      string
+	AlbumMBID  string
 }
 
 var (
@@ -76,6 +80,41 @@ type ArtistTopSongsRetriever interface {
 	GetArtistTopSongs(ctx context.Context, id, artistName, mbid string, count int) ([]Song, error)
 }
 
+// SimilarSongsByTrackRetriever provides similar songs based on a specific track
+type SimilarSongsByTrackRetriever interface {
+	// GetSimilarSongsByTrack returns songs similar to the given track.
+	// Parameters:
+	//   - id: local mediafile ID
+	//   - name: track title
+	//   - artist: artist name
+	//   - mbid: MusicBrainz recording ID (may be empty)
+	//   - count: maximum number of results
+	GetSimilarSongsByTrack(ctx context.Context, id, name, artist, mbid string, count int) ([]Song, error)
+}
+
+// SimilarSongsByAlbumRetriever provides similar songs based on an album
+type SimilarSongsByAlbumRetriever interface {
+	// GetSimilarSongsByAlbum returns songs similar to tracks on the given album.
+	// Parameters:
+	//   - id: local album ID
+	//   - name: album name
+	//   - artist: album artist name
+	//   - mbid: MusicBrainz release ID (may be empty)
+	//   - count: maximum number of results
+	GetSimilarSongsByAlbum(ctx context.Context, id, name, artist, mbid string, count int) ([]Song, error)
+}
+
+// SimilarSongsByArtistRetriever provides similar songs based on an artist
+type SimilarSongsByArtistRetriever interface {
+	// GetSimilarSongsByArtist returns songs similar to the artist's catalog.
+	// Parameters:
+	//   - id: local artist ID
+	//   - name: artist name
+	//   - mbid: MusicBrainz artist ID (may be empty)
+	//   - count: maximum number of results
+	GetSimilarSongsByArtist(ctx context.Context, id, name, mbid string, count int) ([]Song, error)
+}
+
 var Map map[string]Constructor
 
 func Register(name string, init Constructor) {

core/artwork/sources.go

@@ -16,12 +16,14 @@ import (
 	"time"
 
 	"github.com/dhowden/tag"
+	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/core/external"
 	"github.com/navidrome/navidrome/core/ffmpeg"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/resources"
+	"go.senan.xyz/taglib"
 )
 
 func selectImageReader(ctx context.Context, artID model.ArtworkID, extractFuncs ...sourceFunc) (io.ReadCloser, string, error) {
@@ -84,6 +86,13 @@ var picTypeRegexes = []*regexp.Regexp{
 }
 
 func fromTag(ctx context.Context, path string) sourceFunc {
+	if conf.Server.DevLegacyEmbedImage {
+		return fromTagLegacy(ctx, path)
+	}
+	return fromTagGoTaglib(ctx, path)
+}
+
+func fromTagLegacy(ctx context.Context, path string) sourceFunc {
 	return func() (io.ReadCloser, string, error) {
 		if path == "" {
 			return nil, "", nil
@@ -128,6 +137,44 @@ func fromTag(ctx context.Context, path string) sourceFunc {
 	}
 }
 
+func fromTagGoTaglib(ctx context.Context, path string) sourceFunc {
+	return func() (io.ReadCloser, string, error) {
+		if path == "" {
+			return nil, "", nil
+		}
+		f, err := taglib.OpenReadOnly(path, taglib.WithReadStyle(taglib.ReadStyleFast))
+		if err != nil {
+			return nil, "", err
+		}
+		defer f.Close()
+
+		images := f.Properties().Images
+		if len(images) == 0 {
+			return nil, "", fmt.Errorf("no embedded image found in %s", path)
+		}
+
+		imageIndex := findBestImageIndex(ctx, images, path)
+		data, err := f.Image(imageIndex)
+		if err != nil || len(data) == 0 {
+			return nil, "", fmt.Errorf("could not load embedded image from %s", path)
+		}
+		return io.NopCloser(bytes.NewReader(data)), path, nil
+	}
+}
+
+func findBestImageIndex(ctx context.Context, images []taglib.ImageDesc, path string) int {
+	for _, regex := range picTypeRegexes {
+		for i, img := range images {
+			if regex.MatchString(img.Type) {
+				log.Trace(ctx, "Found embedded image", "type", img.Type, "path", path)
+				return i
+			}
+		}
+	}
+	log.Trace(ctx, "Could not find a front image. Getting the first one", "type", images[0].Type, "path", path)
+	return 0
+}
+
 func fromFFmpegTag(ctx context.Context, ffmpeg ffmpeg.FFmpeg, path string) sourceFunc {
 	return func() (io.ReadCloser, string, error) {
 		if path == "" {

core/external/extdata_helper_test.go

@@ -282,3 +282,27 @@ func (m *mockAgents) GetAlbumImages(ctx context.Context, name, artist, mbid stri
 	}
 	return nil, args.Error(1)
 }
+
+func (m *mockAgents) GetSimilarSongsByTrack(ctx context.Context, id, name, artist, mbid string, count int) ([]agents.Song, error) {
+	args := m.Called(ctx, id, name, artist, mbid, count)
+	if args.Get(0) != nil {
+		return args.Get(0).([]agents.Song), args.Error(1)
+	}
+	return nil, args.Error(1)
+}
+
+func (m *mockAgents) GetSimilarSongsByAlbum(ctx context.Context, id, name, artist, mbid string, count int) ([]agents.Song, error) {
+	args := m.Called(ctx, id, name, artist, mbid, count)
+	if args.Get(0) != nil {
+		return args.Get(0).([]agents.Song), args.Error(1)
+	}
+	return nil, args.Error(1)
+}
+
+func (m *mockAgents) GetSimilarSongsByArtist(ctx context.Context, id, name, mbid string, count int) ([]agents.Song, error) {
+	args := m.Called(ctx, id, name, mbid, count)
+	if args.Get(0) != nil {
+		return args.Get(0).([]agents.Song), args.Error(1)
+	}
+	return nil, args.Error(1)
+}

core/external/provider.go

@@ -32,7 +32,7 @@ const (
 type Provider interface {
 	UpdateAlbumInfo(ctx context.Context, id string) (*model.Album, error)
 	UpdateArtistInfo(ctx context.Context, id string, count int, includeNotPresent bool) (*model.Artist, error)
-	ArtistRadio(ctx context.Context, id string, count int) (model.MediaFiles, error)
+	SimilarSongs(ctx context.Context, id string, count int) (model.MediaFiles, error)
 	TopSongs(ctx context.Context, artist string, count int) (model.MediaFiles, error)
 	ArtistImage(ctx context.Context, id string) (*url.URL, error)
 	AlbumImage(ctx context.Context, id string) (*url.URL, error)
@@ -80,6 +80,9 @@ type Agents interface {
 	agents.ArtistSimilarRetriever
 	agents.ArtistTopSongsRetriever
 	agents.ArtistURLRetriever
+	agents.SimilarSongsByTrackRetriever
+	agents.SimilarSongsByAlbumRetriever
+	agents.SimilarSongsByArtistRetriever
 }
 
 func NewProvider(ds model.DataStore, agents Agents) Provider {
@@ -256,7 +259,7 @@ func (e *provider) populateArtistInfo(ctx context.Context, artist auxArtist) (au
 	g.Go(func() error { e.callGetImage(ctx, e.ag, &artist); return nil })
 	g.Go(func() error { e.callGetBiography(ctx, e.ag, &artist); return nil })
 	g.Go(func() error { e.callGetURL(ctx, e.ag, &artist); return nil })
-	g.Go(func() error { e.callGetSimilar(ctx, e.ag, &artist, maxSimilarArtists, true); return nil })
+	g.Go(func() error { e.callGetSimilarArtists(ctx, e.ag, &artist, maxSimilarArtists, true); return nil })
 	_ = g.Wait()
 
 	if utils.IsCtxDone(ctx) {
@@ -275,22 +278,51 @@ func (e *provider) populateArtistInfo(ctx context.Context, artist auxArtist) (au
 	return artist, nil
 }
 
-func (e *provider) ArtistRadio(ctx context.Context, id string, count int) (model.MediaFiles, error) {
+func (e *provider) SimilarSongs(ctx context.Context, id string, count int) (model.MediaFiles, error) {
+	entity, err := model.GetEntityByID(ctx, e.ds, id)
+	if err != nil {
+		return nil, err
+	}
+
+	var songs []agents.Song
+
+	// Try entity-specific similarity first
+	switch v := entity.(type) {
+	case *model.MediaFile:
+		songs, err = e.ag.GetSimilarSongsByTrack(ctx, v.ID, v.Title, v.Artist, v.MbzRecordingID, count)
+	case *model.Album:
+		songs, err = e.ag.GetSimilarSongsByAlbum(ctx, v.ID, v.Name, v.AlbumArtist, v.MbzAlbumID, count)
+	case *model.Artist:
+		songs, err = e.ag.GetSimilarSongsByArtist(ctx, v.ID, v.Name, v.MbzArtistID, count)
+	}
+
+	if err == nil && len(songs) > 0 {
+		return e.matchSongsToLibrary(ctx, songs, count)
+	}
+
+	// Fallback to existing similar artists + top songs algorithm
+	return e.similarSongsFallback(ctx, id, count)
+}
+
+// similarSongsFallback uses the original similar artists + top songs algorithm. The idea is to
+// get the artist of the given entity, retrieve similar artists, get their top songs, and pick
+// a weighted random selection of songs to return as similar songs.
+func (e *provider) similarSongsFallback(ctx context.Context, id string, count int) (model.MediaFiles, error) {
 	artist, err := e.getArtist(ctx, id)
 	if err != nil {
 		return nil, err
 	}
 
-	e.callGetSimilar(ctx, e.ag, &artist, 15, false)
+	e.callGetSimilarArtists(ctx, e.ag, &artist, 15, false)
 	if utils.IsCtxDone(ctx) {
-		log.Warn(ctx, "ArtistRadio call canceled", ctx.Err())
+		log.Warn(ctx, "SimilarSongs call canceled", ctx.Err())
 		return nil, ctx.Err()
 	}
 
 	weightedSongs := random.NewWeightedChooser[model.MediaFile]()
 	addArtist := func(a model.Artist, weightedSongs *random.WeightedChooser[model.MediaFile], count, artistWeight int) error {
 		if utils.IsCtxDone(ctx) {
-			log.Warn(ctx, "ArtistRadio call canceled", ctx.Err())
+			log.Warn(ctx, "SimilarSongs call canceled", ctx.Err())
 			return ctx.Err()
 		}
 
@@ -422,21 +454,20 @@ func (e *provider) getMatchingTopSongs(ctx context.Context, agent agents.ArtistT
 		return nil, fmt.Errorf("failed to get top songs for artist %s: %w", artistName, err)
 	}
 
-	idMatches, err := e.loadTracksByID(ctx, songs)
-	if err != nil {
-		return nil, fmt.Errorf("failed to load tracks by ID: %w", err)
-	}
-	mbidMatches, err := e.loadTracksByMBID(ctx, songs)
-	if err != nil {
-		return nil, fmt.Errorf("failed to load tracks by MBID: %w", err)
-	}
-	titleMatches, err := e.loadTracksByTitle(ctx, songs, artist, idMatches, mbidMatches)
-	if err != nil {
-		return nil, fmt.Errorf("failed to load tracks by title: %w", err)
+	// Enrich songs with artist info if not already present (for top songs, we know the artist)
+	for i := range songs {
+		if songs[i].Artist == "" {
+			songs[i].Artist = artistName
+		}
+		if songs[i].ArtistMBID == "" {
+			songs[i].ArtistMBID = artist.MbzArtistID
+		}
 	}
 
-	log.Trace(ctx, "Top Songs loaded", "name", artistName, "numSongs", len(songs), "numIDMatches", len(idMatches), "numMBIDMatches", len(mbidMatches), "numTitleMatches", len(titleMatches))
-	mfs := e.selectTopSongs(songs, idMatches, mbidMatches, titleMatches, count)
+	mfs, err := e.matchSongsToLibrary(ctx, songs, count)
+	if err != nil {
+		return nil, err
+	}
 
 	if len(mfs) == 0 {
 		log.Debug(ctx, "No matching top songs found", "name", artistName)
@@ -447,137 +478,6 @@ func (e *provider) getMatchingTopSongs(ctx context.Context, agent agents.ArtistT
 	return mfs, nil
 }
 
-func (e *provider) loadTracksByMBID(ctx context.Context, songs []agents.Song) (map[string]model.MediaFile, error) {
-	var mbids []string
-	for _, s := range songs {
-		if s.MBID != "" {
-			mbids = append(mbids, s.MBID)
-		}
-	}
-	matches := map[string]model.MediaFile{}
-	if len(mbids) == 0 {
-		return matches, nil
-	}
-	res, err := e.ds.MediaFile(ctx).GetAll(model.QueryOptions{
-		Filters: squirrel.And{
-			squirrel.Eq{"mbz_recording_id": mbids},
-			squirrel.Eq{"missing": false},
-		},
-	})
-	if err != nil {
-		return matches, err
-	}
-	for _, mf := range res {
-		if id := mf.MbzRecordingID; id != "" {
-			if _, ok := matches[id]; !ok {
-				matches[id] = mf
-			}
-		}
-	}
-	return matches, nil
-}
-
-func (e *provider) loadTracksByID(ctx context.Context, songs []agents.Song) (map[string]model.MediaFile, error) {
-	var ids []string
-	for _, s := range songs {
-		if s.ID != "" {
-			ids = append(ids, s.ID)
-		}
-	}
-	matches := map[string]model.MediaFile{}
-	if len(ids) == 0 {
-		return matches, nil
-	}
-	res, err := e.ds.MediaFile(ctx).GetAll(model.QueryOptions{
-		Filters: squirrel.And{
-			squirrel.Eq{"media_file.id": ids},
-			squirrel.Eq{"missing": false},
-		},
-	})
-	if err != nil {
-		return matches, err
-	}
-	for _, mf := range res {
-		if _, ok := matches[mf.ID]; !ok {
-			matches[mf.ID] = mf
-		}
-	}
-	return matches, nil
-}
-
-func (e *provider) loadTracksByTitle(ctx context.Context, songs []agents.Song, artist *auxArtist, idMatches, mbidMatches map[string]model.MediaFile) (map[string]model.MediaFile, error) {
-	titleMap := map[string]string{}
-	for _, s := range songs {
-		// Skip if already matched by ID or MBID
-		if s.ID != "" && idMatches[s.ID].ID != "" {
-			continue
-		}
-		if s.MBID != "" && mbidMatches[s.MBID].ID != "" {
-			continue
-		}
-		sanitized := str.SanitizeFieldForSorting(s.Name)
-		titleMap[sanitized] = s.Name
-	}
-	matches := map[string]model.MediaFile{}
-	if len(titleMap) == 0 {
-		return matches, nil
-	}
-	titleFilters := squirrel.Or{}
-	for sanitized := range titleMap {
-		titleFilters = append(titleFilters, squirrel.Like{"order_title": sanitized})
-	}
-
-	res, err := e.ds.MediaFile(ctx).GetAll(model.QueryOptions{
-		Filters: squirrel.And{
-			squirrel.Or{
-				squirrel.Eq{"artist_id": artist.ID},
-				squirrel.Eq{"album_artist_id": artist.ID},
-			},
-			titleFilters,
-			squirrel.Eq{"missing": false},
-		},
-		Sort: "starred desc, rating desc, year asc, compilation asc ",
-	})
-	if err != nil {
-		return matches, err
-	}
-	for _, mf := range res {
-		sanitized := str.SanitizeFieldForSorting(mf.Title)
-		if _, ok := matches[sanitized]; !ok {
-			matches[sanitized] = mf
-		}
-	}
-	return matches, nil
-}
-
-func (e *provider) selectTopSongs(songs []agents.Song, byID, byMBID, byTitle map[string]model.MediaFile, count int) model.MediaFiles {
-	var mfs model.MediaFiles
-	for _, t := range songs {
-		if len(mfs) == count {
-			break
-		}
-		// Try ID match first
-		if t.ID != "" {
-			if mf, ok := byID[t.ID]; ok {
-				mfs = append(mfs, mf)
-				continue
-			}
-		}
-		// Try MBID match second
-		if t.MBID != "" {
-			if mf, ok := byMBID[t.MBID]; ok {
-				mfs = append(mfs, mf)
-				continue
-			}
-		}
-		// Fall back to title match
-		if mf, ok := byTitle[str.SanitizeFieldForSorting(t.Name)]; ok {
-			mfs = append(mfs, mf)
-		}
-	}
-	return mfs
-}
-
 func (e *provider) callGetURL(ctx context.Context, agent agents.ArtistURLRetriever, artist *auxArtist) {
 	artisURL, err := agent.GetArtistURL(ctx, artist.ID, artist.Name(), artist.MbzArtistID)
 	if err != nil {
@@ -614,7 +514,7 @@ func (e *provider) callGetImage(ctx context.Context, agent agents.ArtistImageRet
 	}
 }
 
-func (e *provider) callGetSimilar(ctx context.Context, agent agents.ArtistSimilarRetriever, artist *auxArtist,
+func (e *provider) callGetSimilarArtists(ctx context.Context, agent agents.ArtistSimilarRetriever, artist *auxArtist,
 	limit int, includeNotPresent bool) {
 	artistName := artist.Name()
 	similar, err := agent.GetSimilarArtists(ctx, artist.ID, artistName, artist.MbzArtistID, limit)

core/external/provider_artistradio_test.go

@@ -1,205 +0,0 @@
-package external_test
-
-import (
-	"context"
-	"errors"
-
-	"github.com/Masterminds/squirrel"
-	"github.com/navidrome/navidrome/core/agents"
-	. "github.com/navidrome/navidrome/core/external"
-	"github.com/navidrome/navidrome/model"
-	"github.com/navidrome/navidrome/tests"
-	. "github.com/onsi/ginkgo/v2"
-	. "github.com/onsi/gomega"
-	"github.com/stretchr/testify/mock"
-)
-
-var _ = Describe("Provider - ArtistRadio", func() {
-	var ds model.DataStore
-	var provider Provider
-	var mockAgent *mockSimilarArtistAgent
-	var mockTopAgent agents.ArtistTopSongsRetriever
-	var mockSimilarAgent agents.ArtistSimilarRetriever
-	var agentsCombined Agents
-	var artistRepo *mockArtistRepo
-	var mediaFileRepo *mockMediaFileRepo
-	var ctx context.Context
-
-	BeforeEach(func() {
-		ctx = GinkgoT().Context()
-
-		artistRepo = newMockArtistRepo()
-		mediaFileRepo = newMockMediaFileRepo()
-
-		ds = &tests.MockDataStore{
-			MockedArtist:    artistRepo,
-			MockedMediaFile: mediaFileRepo,
-		}
-
-		mockAgent = &mockSimilarArtistAgent{}
-		mockTopAgent = mockAgent
-		mockSimilarAgent = mockAgent
-
-		agentsCombined = &mockAgents{
-			topSongsAgent: mockTopAgent,
-			similarAgent:  mockSimilarAgent,
-		}
-
-		provider = NewProvider(ds, agentsCombined)
-	})
-
-	It("returns similar songs from main artist and similar artists", func() {
-		artist1 := model.Artist{ID: "artist-1", Name: "Artist One"}
-		similarArtist := model.Artist{ID: "artist-3", Name: "Similar Artist"}
-		song1 := model.MediaFile{ID: "song-1", Title: "Song One", ArtistID: "artist-1", MbzRecordingID: "mbid-1"}
-		song2 := model.MediaFile{ID: "song-2", Title: "Song Two", ArtistID: "artist-1", MbzRecordingID: "mbid-2"}
-		song3 := model.MediaFile{ID: "song-3", Title: "Song Three", ArtistID: "artist-3", MbzRecordingID: "mbid-3"}
-
-		artistRepo.On("Get", "artist-1").Return(&artist1, nil).Maybe()
-		artistRepo.On("Get", "artist-3").Return(&similarArtist, nil).Maybe()
-
-		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-			return opt.Max == 1 && opt.Filters != nil
-		})).Return(model.Artists{artist1}, nil).Once()
-
-		similarAgentsResp := []agents.Artist{
-			{Name: "Similar Artist", MBID: "similar-mbid"},
-		}
-		mockAgent.On("GetSimilarArtists", mock.Anything, "artist-1", "Artist One", "", 15).
-			Return(similarAgentsResp, nil).Once()
-
-		// Mock the three-phase artist lookup: ID (skipped - no IDs), MBID, then Name
-		// MBID lookup returns empty (no match)
-		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-			_, ok := opt.Filters.(squirrel.Eq)
-			return opt.Max == 0 && ok
-		})).Return(model.Artists{}, nil).Once()
-		// Name lookup returns the similar artist
-		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-			_, ok := opt.Filters.(squirrel.Or)
-			return opt.Max == 0 && ok
-		})).Return(model.Artists{similarArtist}, nil).Once()
-
-		mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
-			Return([]agents.Song{
-				{Name: "Song One", MBID: "mbid-1"},
-				{Name: "Song Two", MBID: "mbid-2"},
-			}, nil).Once()
-
-		mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-3", "Similar Artist", "", mock.Anything).
-			Return([]agents.Song{
-				{Name: "Song Three", MBID: "mbid-3"},
-			}, nil).Once()
-
-		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song1, song2}, nil).Once()
-		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song3}, nil).Once()
-
-		songs, err := provider.ArtistRadio(ctx, "artist-1", 3)
-
-		Expect(err).ToNot(HaveOccurred())
-		Expect(songs).To(HaveLen(3))
-		for _, song := range songs {
-			Expect(song.ID).To(BeElementOf("song-1", "song-2", "song-3"))
-		}
-	})
-
-	It("returns ErrNotFound when artist is not found", func() {
-		artistRepo.On("Get", "artist-unknown-artist").Return(nil, model.ErrNotFound)
-		mediaFileRepo.On("Get", "artist-unknown-artist").Return(nil, model.ErrNotFound)
-
-		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-			return opt.Max == 1 && opt.Filters != nil
-		})).Return(model.Artists{}, nil).Maybe()
-
-		songs, err := provider.ArtistRadio(ctx, "artist-unknown-artist", 5)
-
-		Expect(err).To(Equal(model.ErrNotFound))
-		Expect(songs).To(BeNil())
-	})
-
-	It("returns songs from main artist when GetSimilarArtists returns error", func() {
-		artist1 := model.Artist{ID: "artist-1", Name: "Artist One"}
-		song1 := model.MediaFile{ID: "song-1", Title: "Song One", ArtistID: "artist-1", MbzRecordingID: "mbid-1"}
-
-		artistRepo.On("Get", "artist-1").Return(&artist1, nil).Maybe()
-		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-			return opt.Max == 1 && opt.Filters != nil
-		})).Return(model.Artists{artist1}, nil).Maybe()
-
-		mockAgent.On("GetSimilarArtists", mock.Anything, "artist-1", "Artist One", "", 15).
-			Return(nil, errors.New("error getting similar artists")).Once()
-
-		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-			return opt.Max == 0 && opt.Filters != nil
-		})).Return(model.Artists{}, nil).Once()
-
-		mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
-			Return([]agents.Song{
-				{Name: "Song One", MBID: "mbid-1"},
-			}, nil).Once()
-
-		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song1}, nil).Once()
-
-		songs, err := provider.ArtistRadio(ctx, "artist-1", 5)
-
-		Expect(err).ToNot(HaveOccurred())
-		Expect(songs).To(HaveLen(1))
-		Expect(songs[0].ID).To(Equal("song-1"))
-	})
-
-	It("returns empty list when GetArtistTopSongs returns error", func() {
-		artist1 := model.Artist{ID: "artist-1", Name: "Artist One"}
-
-		artistRepo.On("Get", "artist-1").Return(&artist1, nil).Maybe()
-		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-			return opt.Max == 1 && opt.Filters != nil
-		})).Return(model.Artists{artist1}, nil).Maybe()
-
-		mockAgent.On("GetSimilarArtists", mock.Anything, "artist-1", "Artist One", "", 15).
-			Return([]agents.Artist{}, nil).Once()
-
-		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-			return opt.Max == 0 && opt.Filters != nil
-		})).Return(model.Artists{}, nil).Once()
-
-		mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
-			Return(nil, errors.New("error getting top songs")).Once()
-
-		songs, err := provider.ArtistRadio(ctx, "artist-1", 5)
-
-		Expect(err).ToNot(HaveOccurred())
-		Expect(songs).To(BeEmpty())
-	})
-
-	It("respects count parameter", func() {
-		artist1 := model.Artist{ID: "artist-1", Name: "Artist One"}
-		song1 := model.MediaFile{ID: "song-1", Title: "Song One", ArtistID: "artist-1", MbzRecordingID: "mbid-1"}
-		song2 := model.MediaFile{ID: "song-2", Title: "Song Two", ArtistID: "artist-1", MbzRecordingID: "mbid-2"}
-
-		artistRepo.On("Get", "artist-1").Return(&artist1, nil).Maybe()
-		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-			return opt.Max == 1 && opt.Filters != nil
-		})).Return(model.Artists{artist1}, nil).Maybe()
-
-		mockAgent.On("GetSimilarArtists", mock.Anything, "artist-1", "Artist One", "", 15).
-			Return([]agents.Artist{}, nil).Once()
-
-		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-			return opt.Max == 0 && opt.Filters != nil
-		})).Return(model.Artists{}, nil).Once()
-
-		mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
-			Return([]agents.Song{
-				{Name: "Song One", MBID: "mbid-1"},
-				{Name: "Song Two", MBID: "mbid-2"},
-			}, nil).Once()
-
-		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song1, song2}, nil).Once()
-
-		songs, err := provider.ArtistRadio(ctx, "artist-1", 1)
-
-		Expect(err).ToNot(HaveOccurred())
-		Expect(songs).To(HaveLen(1))
-		Expect(songs[0].ID).To(BeElementOf("song-1", "song-2"))
-	})
-})

core/external/provider_matching.go

@@ -0,0 +1,304 @@
+package external
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/core/agents"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/utils/str"
+)
+
+// matchSongsToLibrary matches agent song results to local library tracks
+func (e *provider) matchSongsToLibrary(ctx context.Context, songs []agents.Song, count int) (model.MediaFiles, error) {
+	idMatches, err := e.loadTracksByID(ctx, songs)
+	if err != nil {
+		return nil, fmt.Errorf("failed to load tracks by ID: %w", err)
+	}
+	mbidMatches, err := e.loadTracksByMBID(ctx, songs)
+	if err != nil {
+		return nil, fmt.Errorf("failed to load tracks by MBID: %w", err)
+	}
+	titleMatches, err := e.loadTracksByTitleAndArtist(ctx, songs, idMatches, mbidMatches)
+	if err != nil {
+		return nil, fmt.Errorf("failed to load tracks by title: %w", err)
+	}
+
+	return e.selectBestMatchingSongs(songs, idMatches, mbidMatches, titleMatches, count), nil
+}
+
+func (e *provider) loadTracksByID(ctx context.Context, songs []agents.Song) (map[string]model.MediaFile, error) {
+	var ids []string
+	for _, s := range songs {
+		if s.ID != "" {
+			ids = append(ids, s.ID)
+		}
+	}
+	matches := map[string]model.MediaFile{}
+	if len(ids) == 0 {
+		return matches, nil
+	}
+	res, err := e.ds.MediaFile(ctx).GetAll(model.QueryOptions{
+		Filters: squirrel.And{
+			squirrel.Eq{"media_file.id": ids},
+			squirrel.Eq{"missing": false},
+		},
+	})
+	if err != nil {
+		return matches, err
+	}
+	for _, mf := range res {
+		if _, ok := matches[mf.ID]; !ok {
+			matches[mf.ID] = mf
+		}
+	}
+	return matches, nil
+}
+
+func (e *provider) loadTracksByMBID(ctx context.Context, songs []agents.Song) (map[string]model.MediaFile, error) {
+	var mbids []string
+	for _, s := range songs {
+		if s.MBID != "" {
+			mbids = append(mbids, s.MBID)
+		}
+	}
+	matches := map[string]model.MediaFile{}
+	if len(mbids) == 0 {
+		return matches, nil
+	}
+	res, err := e.ds.MediaFile(ctx).GetAll(model.QueryOptions{
+		Filters: squirrel.And{
+			squirrel.Eq{"mbz_recording_id": mbids},
+			squirrel.Eq{"missing": false},
+		},
+	})
+	if err != nil {
+		return matches, err
+	}
+	for _, mf := range res {
+		if id := mf.MbzRecordingID; id != "" {
+			if _, ok := matches[id]; !ok {
+				matches[id] = mf
+			}
+		}
+	}
+	return matches, nil
+}
+
+type songQuery struct {
+	title      string
+	artist     string
+	artistMBID string
+	album      string
+	albumMBID  string
+}
+
+// loadTracksByTitleAndArtist loads tracks matching by title with optional artist/album filtering.
+// Uses per-song artist/album info when available for more precise matching.
+// Returns a map keyed by sanitized title for compatibility with selectBestMatchingSongs.
+func (e *provider) loadTracksByTitleAndArtist(ctx context.Context, songs []agents.Song, idMatches, mbidMatches map[string]model.MediaFile) (map[string]model.MediaFile, error) {
+	queries := e.buildTitleQueries(songs, idMatches, mbidMatches)
+	matches := map[string]model.MediaFile{}
+	if len(queries) == 0 {
+		return matches, nil
+	}
+
+	res, err := e.queryTracksByTitles(ctx, queries)
+	if err != nil {
+		return matches, err
+	}
+
+	indices := e.indexTracksByKeys(res)
+	return e.matchQueriesAgainstIndices(queries, indices), nil
+}
+
+func (e *provider) buildTitleQueries(songs []agents.Song, idMatches, mbidMatches map[string]model.MediaFile) []songQuery {
+	var queries []songQuery
+	for _, s := range songs {
+		// Skip if already matched by ID or MBID
+		if s.ID != "" && idMatches[s.ID].ID != "" {
+			continue
+		}
+		if s.MBID != "" && mbidMatches[s.MBID].ID != "" {
+			continue
+		}
+		queries = append(queries, songQuery{
+			title:      str.SanitizeFieldForSorting(s.Name),
+			artist:     str.SanitizeFieldForSorting(s.Artist),
+			artistMBID: s.ArtistMBID,
+			album:      str.SanitizeFieldForSorting(s.Album),
+			albumMBID:  s.AlbumMBID,
+		})
+	}
+	return queries
+}
+
+func (e *provider) queryTracksByTitles(ctx context.Context, queries []songQuery) (model.MediaFiles, error) {
+	titleSet := map[string]struct{}{}
+	for _, q := range queries {
+		titleSet[q.title] = struct{}{}
+	}
+
+	titleFilters := squirrel.Or{}
+	for title := range titleSet {
+		titleFilters = append(titleFilters, squirrel.Like{"order_title": title})
+	}
+
+	return e.ds.MediaFile(ctx).GetAll(model.QueryOptions{
+		Filters: squirrel.And{
+			titleFilters,
+			squirrel.Eq{"missing": false},
+		},
+		Sort: "starred desc, rating desc, year asc, compilation asc",
+	})
+}
+
+type trackIndices struct {
+	byTitleArtistMBIDAlbumMBID map[string]model.MediaFile
+	byTitleArtistMBIDAlbum     map[string]model.MediaFile
+	byTitleArtistAlbum         map[string]model.MediaFile
+	byTitleArtistMBID          map[string]model.MediaFile
+	byTitleArtist              map[string]model.MediaFile
+	byTitle                    map[string]model.MediaFile
+}
+
+func (e *provider) indexTracksByKeys(tracks model.MediaFiles) *trackIndices {
+	indices := &trackIndices{
+		byTitleArtistMBIDAlbumMBID: map[string]model.MediaFile{},
+		byTitleArtistMBIDAlbum:     map[string]model.MediaFile{},
+		byTitleArtistAlbum:         map[string]model.MediaFile{},
+		byTitleArtistMBID:          map[string]model.MediaFile{},
+		byTitleArtist:              map[string]model.MediaFile{},
+		byTitle:                    map[string]model.MediaFile{},
+	}
+
+	for _, mf := range tracks {
+		title := str.SanitizeFieldForSorting(mf.Title)
+		artist := str.SanitizeFieldForSorting(mf.Artist)
+		album := str.SanitizeFieldForSorting(mf.Album)
+		artistMBID := mf.MbzArtistID
+		albumMBID := mf.MbzAlbumID
+
+		e.indexTrackBySpecificity(indices, title, artist, album, artistMBID, albumMBID, mf)
+	}
+	return indices
+}
+
+func (e *provider) indexTrackBySpecificity(indices *trackIndices, title, artist, album, artistMBID, albumMBID string, mf model.MediaFile) {
+	addIfNotExists := func(m map[string]model.MediaFile, key string) {
+		if _, ok := m[key]; !ok {
+			m[key] = mf
+		}
+	}
+
+	if artistMBID != "" && albumMBID != "" {
+		addIfNotExists(indices.byTitleArtistMBIDAlbumMBID, title+"|"+artistMBID+"|"+albumMBID)
+	}
+	if artistMBID != "" && album != "" {
+		addIfNotExists(indices.byTitleArtistMBIDAlbum, title+"|"+artistMBID+"|"+album)
+	}
+	if artist != "" && album != "" {
+		addIfNotExists(indices.byTitleArtistAlbum, title+"|"+artist+"|"+album)
+	}
+	if artistMBID != "" {
+		addIfNotExists(indices.byTitleArtistMBID, title+"|"+artistMBID)
+	}
+	if artist != "" {
+		addIfNotExists(indices.byTitleArtist, title+"|"+artist)
+	}
+	addIfNotExists(indices.byTitle, title)
+}
+
+func (e *provider) matchQueriesAgainstIndices(queries []songQuery, indices *trackIndices) map[string]model.MediaFile {
+	matches := map[string]model.MediaFile{}
+
+	for _, q := range queries {
+		if mf, found := e.findBestMatch(q, indices); found {
+			if _, ok := matches[q.title]; !ok {
+				matches[q.title] = mf
+			}
+		}
+	}
+	return matches
+}
+
+func (e *provider) findBestMatch(q songQuery, indices *trackIndices) (model.MediaFile, bool) {
+	// Try most specific matches first
+	lookupFuncs := []func() (model.MediaFile, bool){
+		func() (model.MediaFile, bool) {
+			if q.artistMBID != "" && q.albumMBID != "" {
+				mf, ok := indices.byTitleArtistMBIDAlbumMBID[q.title+"|"+q.artistMBID+"|"+q.albumMBID]
+				return mf, ok
+			}
+			return model.MediaFile{}, false
+		},
+		func() (model.MediaFile, bool) {
+			if q.artistMBID != "" && q.album != "" {
+				mf, ok := indices.byTitleArtistMBIDAlbum[q.title+"|"+q.artistMBID+"|"+q.album]
+				return mf, ok
+			}
+			return model.MediaFile{}, false
+		},
+		func() (model.MediaFile, bool) {
+			if q.artist != "" && q.album != "" {
+				mf, ok := indices.byTitleArtistAlbum[q.title+"|"+q.artist+"|"+q.album]
+				return mf, ok
+			}
+			return model.MediaFile{}, false
+		},
+		func() (model.MediaFile, bool) {
+			if q.artistMBID != "" {
+				mf, ok := indices.byTitleArtistMBID[q.title+"|"+q.artistMBID]
+				return mf, ok
+			}
+			return model.MediaFile{}, false
+		},
+		func() (model.MediaFile, bool) {
+			if q.artist != "" {
+				mf, ok := indices.byTitleArtist[q.title+"|"+q.artist]
+				return mf, ok
+			}
+			return model.MediaFile{}, false
+		},
+		func() (model.MediaFile, bool) {
+			mf, ok := indices.byTitle[q.title]
+			return mf, ok
+		},
+	}
+
+	for _, lookup := range lookupFuncs {
+		if mf, found := lookup(); found {
+			return mf, true
+		}
+	}
+	return model.MediaFile{}, false
+}
+
+func (e *provider) selectBestMatchingSongs(songs []agents.Song, byID, byMBID, byTitle map[string]model.MediaFile, count int) model.MediaFiles {
+	var mfs model.MediaFiles
+	for _, t := range songs {
+		if len(mfs) == count {
+			break
+		}
+		// Try ID match first
+		if t.ID != "" {
+			if mf, ok := byID[t.ID]; ok {
+				mfs = append(mfs, mf)
+				continue
+			}
+		}
+		// Try MBID match second
+		if t.MBID != "" {
+			if mf, ok := byMBID[t.MBID]; ok {
+				mfs = append(mfs, mf)
+				continue
+			}
+		}
+		// Fall back to title match
+		if mf, ok := byTitle[str.SanitizeFieldForSorting(t.Name)]; ok {
+			mfs = append(mfs, mf)
+		}
+	}
+	return mfs
+}

core/external/provider_matching_test.go

@@ -0,0 +1,324 @@
+package external_test
+
+import (
+	"context"
+
+	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/core/agents"
+	. "github.com/navidrome/navidrome/core/external"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"github.com/stretchr/testify/mock"
+)
+
+var _ = Describe("Provider - Song Matching", func() {
+	var ds model.DataStore
+	var provider Provider
+	var agentsCombined *mockAgents
+	var artistRepo *mockArtistRepo
+	var mediaFileRepo *mockMediaFileRepo
+	var albumRepo *mockAlbumRepo
+	var ctx context.Context
+
+	BeforeEach(func() {
+		ctx = GinkgoT().Context()
+
+		artistRepo = newMockArtistRepo()
+		mediaFileRepo = newMockMediaFileRepo()
+		albumRepo = newMockAlbumRepo()
+
+		ds = &tests.MockDataStore{
+			MockedArtist:    artistRepo,
+			MockedMediaFile: mediaFileRepo,
+			MockedAlbum:     albumRepo,
+		}
+
+		agentsCombined = &mockAgents{}
+		provider = NewProvider(ds, agentsCombined)
+	})
+
+	Describe("matchSongsToLibrary priority matching", func() {
+		var track model.MediaFile
+
+		BeforeEach(func() {
+			track = model.MediaFile{ID: "track-1", Title: "Test Track", Artist: "Test Artist", MbzRecordingID: ""}
+
+			// Setup for GetEntityByID to return the track
+			artistRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
+			albumRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
+			mediaFileRepo.On("Get", "track-1").Return(&track, nil).Once()
+		})
+
+		Context("when agent returns artist and album metadata", func() {
+			It("matches by title + artist MBID + album MBID (highest priority)", func() {
+				// Song in library with all MBIDs
+				correctMatch := model.MediaFile{
+					ID: "correct-match", Title: "Similar Song", Artist: "Depeche Mode", Album: "Violator",
+					MbzArtistID: "artist-mbid-123", MbzAlbumID: "album-mbid-456",
+				}
+				// Another song with same title but different MBIDs (should NOT match)
+				wrongMatch := model.MediaFile{
+					ID: "wrong-match", Title: "Similar Song", Artist: "Depeche Mode", Album: "Some Other Album",
+					MbzArtistID: "artist-mbid-123", MbzAlbumID: "different-album-mbid",
+				}
+
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything).
+					Return([]agents.Song{
+						{Name: "Similar Song", Artist: "Depeche Mode", ArtistMBID: "artist-mbid-123", Album: "Violator", AlbumMBID: "album-mbid-456"},
+					}, nil).Once()
+
+				// loadTracksByID returns empty
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					_, ok := opt.Filters.(squirrel.Eq)
+					return ok
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// loadTracksByMBID returns empty (no song MBID)
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 1 {
+						return false
+					}
+					eq, hasEq := and[0].(squirrel.Eq)
+					if !hasEq {
+						return false
+					}
+					_, hasMBID := eq["mbz_recording_id"]
+					return hasMBID
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// loadTracksByTitleAndArtist returns both songs
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 2 {
+						return false
+					}
+					_, hasOr := and[0].(squirrel.Or)
+					return hasOr
+				})).Return(model.MediaFiles{wrongMatch, correctMatch}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(1))
+				Expect(songs[0].ID).To(Equal("correct-match"))
+			})
+
+			It("matches by title + artist name + album name when MBIDs unavailable", func() {
+				// Song in library without MBIDs but with matching artist/album names
+				correctMatch := model.MediaFile{
+					ID: "correct-match", Title: "Similar Song", Artist: "depeche mode", Album: "violator",
+				}
+				// Another song with same title but different artist (should NOT match)
+				wrongMatch := model.MediaFile{
+					ID: "wrong-match", Title: "Similar Song", Artist: "Other Artist", Album: "Other Album",
+				}
+
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything).
+					Return([]agents.Song{
+						{Name: "Similar Song", Artist: "Depeche Mode", Album: "Violator"}, // No MBIDs
+					}, nil).Once()
+
+				// loadTracksByID returns empty
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					_, ok := opt.Filters.(squirrel.Eq)
+					return ok
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// loadTracksByMBID returns empty
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 1 {
+						return false
+					}
+					eq, hasEq := and[0].(squirrel.Eq)
+					if !hasEq {
+						return false
+					}
+					_, hasMBID := eq["mbz_recording_id"]
+					return hasMBID
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// loadTracksByTitleAndArtist returns both songs
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 2 {
+						return false
+					}
+					_, hasOr := and[0].(squirrel.Or)
+					return hasOr
+				})).Return(model.MediaFiles{wrongMatch, correctMatch}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(1))
+				Expect(songs[0].ID).To(Equal("correct-match"))
+			})
+
+			It("matches by title + artist only when album info unavailable", func() {
+				// Song in library with matching artist
+				correctMatch := model.MediaFile{
+					ID: "correct-match", Title: "Similar Song", Artist: "depeche mode", Album: "Some Album",
+				}
+				// Another song with same title but different artist
+				wrongMatch := model.MediaFile{
+					ID: "wrong-match", Title: "Similar Song", Artist: "Other Artist", Album: "Other Album",
+				}
+
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything).
+					Return([]agents.Song{
+						{Name: "Similar Song", Artist: "Depeche Mode"}, // No album info
+					}, nil).Once()
+
+				// loadTracksByID returns empty
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					_, ok := opt.Filters.(squirrel.Eq)
+					return ok
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// loadTracksByMBID returns empty
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 1 {
+						return false
+					}
+					eq, hasEq := and[0].(squirrel.Eq)
+					if !hasEq {
+						return false
+					}
+					_, hasMBID := eq["mbz_recording_id"]
+					return hasMBID
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// loadTracksByTitleAndArtist returns both songs
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 2 {
+						return false
+					}
+					_, hasOr := and[0].(squirrel.Or)
+					return hasOr
+				})).Return(model.MediaFiles{wrongMatch, correctMatch}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(1))
+				Expect(songs[0].ID).To(Equal("correct-match"))
+			})
+
+			It("falls back to title-only match when no artist info available", func() {
+				// Song in library
+				titleMatch := model.MediaFile{
+					ID: "title-match", Title: "Similar Song", Artist: "Random Artist",
+				}
+
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything).
+					Return([]agents.Song{
+						{Name: "Similar Song"}, // No artist/album info at all
+					}, nil).Once()
+
+				// loadTracksByID returns empty
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					_, ok := opt.Filters.(squirrel.Eq)
+					return ok
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// loadTracksByMBID returns empty
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 1 {
+						return false
+					}
+					eq, hasEq := and[0].(squirrel.Eq)
+					if !hasEq {
+						return false
+					}
+					_, hasMBID := eq["mbz_recording_id"]
+					return hasMBID
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// loadTracksByTitleAndArtist returns the song
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 2 {
+						return false
+					}
+					_, hasOr := and[0].(squirrel.Or)
+					return hasOr
+				})).Return(model.MediaFiles{titleMatch}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(1))
+				Expect(songs[0].ID).To(Equal("title-match"))
+			})
+		})
+
+		Context("when matching multiple songs with different precision levels", func() {
+			It("prefers more precise matches for each song", func() {
+				// Library has multiple versions of same song
+				preciseMatch := model.MediaFile{
+					ID: "precise", Title: "Song A", Artist: "Artist One", Album: "Album One",
+					MbzArtistID: "mbid-1", MbzAlbumID: "album-mbid-1",
+				}
+				lessAccurateMatch := model.MediaFile{
+					ID: "less-accurate", Title: "Song A", Artist: "Artist One", Album: "Compilation",
+					MbzArtistID: "mbid-1",
+				}
+				titleOnlyMatch := model.MediaFile{
+					ID: "title-only", Title: "Song B", Artist: "Different Artist",
+				}
+
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything).
+					Return([]agents.Song{
+						{Name: "Song A", Artist: "Artist One", ArtistMBID: "mbid-1", Album: "Album One", AlbumMBID: "album-mbid-1"},
+						{Name: "Song B"}, // Title only
+					}, nil).Once()
+
+				// loadTracksByID returns empty
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					_, ok := opt.Filters.(squirrel.Eq)
+					return ok
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// loadTracksByMBID returns empty
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 1 {
+						return false
+					}
+					eq, hasEq := and[0].(squirrel.Eq)
+					if !hasEq {
+						return false
+					}
+					_, hasMBID := eq["mbz_recording_id"]
+					return hasMBID
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// loadTracksByTitleAndArtist returns all candidates
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 2 {
+						return false
+					}
+					_, hasOr := and[0].(squirrel.Or)
+					return hasOr
+				})).Return(model.MediaFiles{lessAccurateMatch, preciseMatch, titleOnlyMatch}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(2))
+				// First song should be the precise match (has all MBIDs)
+				Expect(songs[0].ID).To(Equal("precise"))
+				// Second song should be title-only match
+				Expect(songs[1].ID).To(Equal("title-only"))
+			})
+		})
+	})
+})

core/external/provider_similarsongs_test.go

@@ -0,0 +1,435 @@
+package external_test
+
+import (
+	"context"
+	"errors"
+
+	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/core/agents"
+	. "github.com/navidrome/navidrome/core/external"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"github.com/stretchr/testify/mock"
+)
+
+var _ = Describe("Provider - SimilarSongs", func() {
+	var ds model.DataStore
+	var provider Provider
+	var mockAgent *mockSimilarArtistAgent
+	var mockTopAgent agents.ArtistTopSongsRetriever
+	var mockSimilarAgent agents.ArtistSimilarRetriever
+	var agentsCombined *mockAgents
+	var artistRepo *mockArtistRepo
+	var mediaFileRepo *mockMediaFileRepo
+	var albumRepo *mockAlbumRepo
+	var ctx context.Context
+
+	BeforeEach(func() {
+		ctx = GinkgoT().Context()
+
+		artistRepo = newMockArtistRepo()
+		mediaFileRepo = newMockMediaFileRepo()
+		albumRepo = newMockAlbumRepo()
+
+		ds = &tests.MockDataStore{
+			MockedArtist:    artistRepo,
+			MockedMediaFile: mediaFileRepo,
+			MockedAlbum:     albumRepo,
+		}
+
+		mockAgent = &mockSimilarArtistAgent{}
+		mockTopAgent = mockAgent
+		mockSimilarAgent = mockAgent
+
+		agentsCombined = &mockAgents{
+			topSongsAgent: mockTopAgent,
+			similarAgent:  mockSimilarAgent,
+		}
+
+		provider = NewProvider(ds, agentsCombined)
+	})
+
+	Describe("dispatch by entity type", func() {
+		Context("when ID is a MediaFile (track)", func() {
+			It("calls GetSimilarSongsByTrack and returns matched songs", func() {
+				track := model.MediaFile{ID: "track-1", Title: "Just Can't Get Enough", Artist: "Depeche Mode", MbzRecordingID: "track-mbid"}
+				matchedSong := model.MediaFile{ID: "matched-1", Title: "Dreaming of Me", Artist: "Depeche Mode"}
+
+				// GetEntityByID tries Artist, Album, Playlist, then MediaFile
+				artistRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
+				mediaFileRepo.On("Get", "track-1").Return(&track, nil).Once()
+
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "track-1", "Just Can't Get Enough", "Depeche Mode", "track-mbid", 5).
+					Return([]agents.Song{
+						{Name: "Dreaming of Me", MBID: "", Artist: "Depeche Mode", ArtistMBID: "artist-mbid"},
+					}, nil).Once()
+
+				// Mock loadTracksByID - no ID matches
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					_, ok := opt.Filters.(squirrel.Eq)
+					return ok
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// Mock loadTracksByMBID - no MBID matches (empty MBID)
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					eq, ok := opt.Filters.(squirrel.And)
+					if !ok || len(eq) < 1 {
+						return false
+					}
+					_, hasEq := eq[0].(squirrel.Eq)
+					return hasEq
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// Mock loadTracksByTitleOnly - title matches
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 2 {
+						return false
+					}
+					_, hasOr := and[0].(squirrel.Or)
+					return hasOr
+				})).Return(model.MediaFiles{matchedSong}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(1))
+				Expect(songs[0].ID).To(Equal("matched-1"))
+			})
+
+			It("falls back to artist-based algorithm when GetSimilarSongsByTrack returns empty", func() {
+				track := model.MediaFile{ID: "track-1", Title: "Track", Artist: "Artist", ArtistID: "artist-1"}
+				artist := model.Artist{ID: "artist-1", Name: "Artist"}
+				song := model.MediaFile{ID: "song-1", Title: "Song One", ArtistID: "artist-1", MbzRecordingID: "mbid-1"}
+
+				// GetEntityByID for the initial call tries Artist, Album, Playlist, then MediaFile
+				artistRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
+				mediaFileRepo.On("Get", "track-1").Return(&track, nil).Once()
+
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "track-1", "Track", "Artist", "", mock.Anything).
+					Return([]agents.Song{}, nil).Once()
+
+				// Fallback calls getArtist(id) which calls GetEntityByID again - this time it finds the mediafile
+				// and recursively calls getArtist(v.ArtistID)
+				artistRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
+				mediaFileRepo.On("Get", "track-1").Return(&track, nil).Once()
+
+				// Then it recurses with the artist-1 ID
+				artistRepo.On("Get", "artist-1").Return(&artist, nil).Maybe()
+				artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					return opt.Max == 1 && opt.Filters != nil
+				})).Return(model.Artists{artist}, nil).Maybe()
+
+				mockAgent.On("GetSimilarArtists", mock.Anything, "artist-1", "Artist", "", 15).
+					Return([]agents.Artist{}, nil).Once()
+
+				artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					return opt.Max == 0 && opt.Filters != nil
+				})).Return(model.Artists{}, nil).Once()
+
+				mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist", "", mock.Anything).
+					Return([]agents.Song{{Name: "Song One", MBID: "mbid-1"}}, nil).Once()
+
+				mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(1))
+				Expect(songs[0].ID).To(Equal("song-1"))
+			})
+		})
+
+		Context("when ID is an Album", func() {
+			It("calls GetSimilarSongsByAlbum and returns matched songs", func() {
+				album := model.Album{ID: "album-1", Name: "Speak & Spell", AlbumArtist: "Depeche Mode", MbzAlbumID: "album-mbid"}
+				matchedSong := model.MediaFile{ID: "matched-1", Title: "New Life", Artist: "Depeche Mode", MbzRecordingID: "song-mbid"}
+
+				// GetEntityByID tries Artist, Album, Playlist, then MediaFile
+				artistRepo.On("Get", "album-1").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "album-1").Return(&album, nil).Once()
+
+				agentsCombined.On("GetSimilarSongsByAlbum", mock.Anything, "album-1", "Speak & Spell", "Depeche Mode", "album-mbid", 5).
+					Return([]agents.Song{
+						{Name: "New Life", MBID: "song-mbid", Artist: "Depeche Mode"},
+					}, nil).Once()
+
+				// Mock loadTracksByID - no ID matches
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					_, ok := opt.Filters.(squirrel.Eq)
+					return ok
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// Mock loadTracksByMBID - MBID match
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 1 {
+						return false
+					}
+					_, hasEq := and[0].(squirrel.Eq)
+					return hasEq
+				})).Return(model.MediaFiles{matchedSong}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "album-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(1))
+				Expect(songs[0].ID).To(Equal("matched-1"))
+			})
+
+			It("falls back when GetSimilarSongsByAlbum returns ErrNotFound", func() {
+				album := model.Album{ID: "album-1", Name: "Album", AlbumArtist: "Artist", AlbumArtistID: "artist-1"}
+				artist := model.Artist{ID: "artist-1", Name: "Artist"}
+				song := model.MediaFile{ID: "song-1", Title: "Song One", ArtistID: "artist-1", MbzRecordingID: "mbid-1"}
+
+				// GetEntityByID for the initial call tries Artist, Album, Playlist, then MediaFile
+				artistRepo.On("Get", "album-1").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "album-1").Return(&album, nil).Once()
+
+				agentsCombined.On("GetSimilarSongsByAlbum", mock.Anything, "album-1", "Album", "Artist", "", mock.Anything).
+					Return(nil, agents.ErrNotFound).Once()
+
+				// Fallback calls getArtist(id) which calls GetEntityByID again - this time it finds the album
+				// and recursively calls getArtist(v.AlbumArtistID)
+				artistRepo.On("Get", "album-1").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "album-1").Return(&album, nil).Once()
+
+				// Then it recurses with the artist-1 ID
+				artistRepo.On("Get", "artist-1").Return(&artist, nil).Maybe()
+				artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					return opt.Max == 1 && opt.Filters != nil
+				})).Return(model.Artists{artist}, nil).Maybe()
+
+				mockAgent.On("GetSimilarArtists", mock.Anything, "artist-1", "Artist", "", 15).
+					Return([]agents.Artist{}, nil).Once()
+
+				artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					return opt.Max == 0 && opt.Filters != nil
+				})).Return(model.Artists{}, nil).Once()
+
+				mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist", "", mock.Anything).
+					Return([]agents.Song{{Name: "Song One", MBID: "mbid-1"}}, nil).Once()
+
+				mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "album-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(1))
+				Expect(songs[0].ID).To(Equal("song-1"))
+			})
+		})
+
+		Context("when ID is an Artist", func() {
+			It("calls GetSimilarSongsByArtist and returns matched songs", func() {
+				artist := model.Artist{ID: "artist-1", Name: "Depeche Mode", MbzArtistID: "artist-mbid"}
+				matchedSong := model.MediaFile{ID: "matched-1", Title: "Enjoy the Silence", Artist: "Depeche Mode", MbzRecordingID: "song-mbid"}
+
+				artistRepo.On("Get", "artist-1").Return(&artist, nil).Once()
+				agentsCombined.On("GetSimilarSongsByArtist", mock.Anything, "artist-1", "Depeche Mode", "artist-mbid", 5).
+					Return([]agents.Song{
+						{Name: "Enjoy the Silence", MBID: "song-mbid", Artist: "Depeche Mode"},
+					}, nil).Once()
+
+				// Mock loadTracksByID - no ID matches
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					_, ok := opt.Filters.(squirrel.Eq)
+					return ok
+				})).Return(model.MediaFiles{}, nil).Once()
+
+				// Mock loadTracksByMBID - MBID match
+				mediaFileRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					and, ok := opt.Filters.(squirrel.And)
+					if !ok || len(and) < 1 {
+						return false
+					}
+					_, hasEq := and[0].(squirrel.Eq)
+					return hasEq
+				})).Return(model.MediaFiles{matchedSong}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "artist-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(1))
+				Expect(songs[0].ID).To(Equal("matched-1"))
+			})
+		})
+	})
+
+	It("returns similar songs from main artist and similar artists", func() {
+		artist1 := model.Artist{ID: "artist-1", Name: "Artist One"}
+		similarArtist := model.Artist{ID: "artist-3", Name: "Similar Artist"}
+		song1 := model.MediaFile{ID: "song-1", Title: "Song One", ArtistID: "artist-1", MbzRecordingID: "mbid-1"}
+		song2 := model.MediaFile{ID: "song-2", Title: "Song Two", ArtistID: "artist-1", MbzRecordingID: "mbid-2"}
+		song3 := model.MediaFile{ID: "song-3", Title: "Song Three", ArtistID: "artist-3", MbzRecordingID: "mbid-3"}
+
+		artistRepo.On("Get", "artist-1").Return(&artist1, nil).Maybe()
+		artistRepo.On("Get", "artist-3").Return(&similarArtist, nil).Maybe()
+
+		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+			return opt.Max == 1 && opt.Filters != nil
+		})).Return(model.Artists{artist1}, nil).Once()
+
+		// New similar songs by artist returns ErrNotFound to trigger fallback
+		agentsCombined.On("GetSimilarSongsByArtist", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
+			Return(nil, agents.ErrNotFound).Once()
+
+		similarAgentsResp := []agents.Artist{
+			{Name: "Similar Artist", MBID: "similar-mbid"},
+		}
+		mockAgent.On("GetSimilarArtists", mock.Anything, "artist-1", "Artist One", "", 15).
+			Return(similarAgentsResp, nil).Once()
+
+		// Mock the three-phase artist lookup: ID (skipped - no IDs), MBID, then Name
+		// MBID lookup returns empty (no match)
+		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+			_, ok := opt.Filters.(squirrel.Eq)
+			return opt.Max == 0 && ok
+		})).Return(model.Artists{}, nil).Once()
+		// Name lookup returns the similar artist
+		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+			_, ok := opt.Filters.(squirrel.Or)
+			return opt.Max == 0 && ok
+		})).Return(model.Artists{similarArtist}, nil).Once()
+
+		mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
+			Return([]agents.Song{
+				{Name: "Song One", MBID: "mbid-1"},
+				{Name: "Song Two", MBID: "mbid-2"},
+			}, nil).Once()
+
+		mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-3", "Similar Artist", "", mock.Anything).
+			Return([]agents.Song{
+				{Name: "Song Three", MBID: "mbid-3"},
+			}, nil).Once()
+
+		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song1, song2}, nil).Once()
+		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song3}, nil).Once()
+
+		songs, err := provider.SimilarSongs(ctx, "artist-1", 3)
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(songs).To(HaveLen(3))
+		for _, song := range songs {
+			Expect(song.ID).To(BeElementOf("song-1", "song-2", "song-3"))
+		}
+	})
+
+	It("returns ErrNotFound when artist is not found", func() {
+		artistRepo.On("Get", "artist-unknown-artist").Return(nil, model.ErrNotFound)
+		mediaFileRepo.On("Get", "artist-unknown-artist").Return(nil, model.ErrNotFound)
+		albumRepo.On("Get", "artist-unknown-artist").Return(nil, model.ErrNotFound)
+
+		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+			return opt.Max == 1 && opt.Filters != nil
+		})).Return(model.Artists{}, nil).Maybe()
+
+		songs, err := provider.SimilarSongs(ctx, "artist-unknown-artist", 5)
+
+		Expect(err).To(Equal(model.ErrNotFound))
+		Expect(songs).To(BeNil())
+	})
+
+	It("returns songs from main artist when GetSimilarArtists returns error", func() {
+		artist1 := model.Artist{ID: "artist-1", Name: "Artist One"}
+		song1 := model.MediaFile{ID: "song-1", Title: "Song One", ArtistID: "artist-1", MbzRecordingID: "mbid-1"}
+
+		artistRepo.On("Get", "artist-1").Return(&artist1, nil).Maybe()
+		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+			return opt.Max == 1 && opt.Filters != nil
+		})).Return(model.Artists{artist1}, nil).Maybe()
+
+		// New similar songs by artist returns ErrNotFound to trigger fallback
+		agentsCombined.On("GetSimilarSongsByArtist", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
+			Return(nil, agents.ErrNotFound).Once()
+
+		mockAgent.On("GetSimilarArtists", mock.Anything, "artist-1", "Artist One", "", 15).
+			Return(nil, errors.New("error getting similar artists")).Once()
+
+		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+			return opt.Max == 0 && opt.Filters != nil
+		})).Return(model.Artists{}, nil).Once()
+
+		mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
+			Return([]agents.Song{
+				{Name: "Song One", MBID: "mbid-1"},
+			}, nil).Once()
+
+		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song1}, nil).Once()
+
+		songs, err := provider.SimilarSongs(ctx, "artist-1", 5)
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(songs).To(HaveLen(1))
+		Expect(songs[0].ID).To(Equal("song-1"))
+	})
+
+	It("returns empty list when GetArtistTopSongs returns error", func() {
+		artist1 := model.Artist{ID: "artist-1", Name: "Artist One"}
+
+		artistRepo.On("Get", "artist-1").Return(&artist1, nil).Maybe()
+		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+			return opt.Max == 1 && opt.Filters != nil
+		})).Return(model.Artists{artist1}, nil).Maybe()
+
+		// New similar songs by artist returns ErrNotFound to trigger fallback
+		agentsCombined.On("GetSimilarSongsByArtist", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
+			Return(nil, agents.ErrNotFound).Once()
+
+		mockAgent.On("GetSimilarArtists", mock.Anything, "artist-1", "Artist One", "", 15).
+			Return([]agents.Artist{}, nil).Once()
+
+		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+			return opt.Max == 0 && opt.Filters != nil
+		})).Return(model.Artists{}, nil).Once()
+
+		mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
+			Return(nil, errors.New("error getting top songs")).Once()
+
+		songs, err := provider.SimilarSongs(ctx, "artist-1", 5)
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(songs).To(BeEmpty())
+	})
+
+	It("respects count parameter", func() {
+		artist1 := model.Artist{ID: "artist-1", Name: "Artist One"}
+		song1 := model.MediaFile{ID: "song-1", Title: "Song One", ArtistID: "artist-1", MbzRecordingID: "mbid-1"}
+		song2 := model.MediaFile{ID: "song-2", Title: "Song Two", ArtistID: "artist-1", MbzRecordingID: "mbid-2"}
+
+		artistRepo.On("Get", "artist-1").Return(&artist1, nil).Maybe()
+		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+			return opt.Max == 1 && opt.Filters != nil
+		})).Return(model.Artists{artist1}, nil).Maybe()
+
+		// New similar songs by artist returns ErrNotFound to trigger fallback
+		agentsCombined.On("GetSimilarSongsByArtist", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
+			Return(nil, agents.ErrNotFound).Once()
+
+		mockAgent.On("GetSimilarArtists", mock.Anything, "artist-1", "Artist One", "", 15).
+			Return([]agents.Artist{}, nil).Once()
+
+		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+			return opt.Max == 0 && opt.Filters != nil
+		})).Return(model.Artists{}, nil).Once()
+
+		mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
+			Return([]agents.Song{
+				{Name: "Song One", MBID: "mbid-1"},
+				{Name: "Song Two", MBID: "mbid-2"},
+			}, nil).Once()
+
+		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song1, song2}, nil).Once()
+
+		songs, err := provider.SimilarSongs(ctx, "artist-1", 1)
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(songs).To(HaveLen(1))
+		Expect(songs[0].ID).To(BeElementOf("song-1", "song-2"))
+	})
+})

core/library_test.go

@@ -9,7 +9,7 @@ import (
 	"sync"
 
 	"github.com/deluan/rest"
-	_ "github.com/navidrome/navidrome/adapters/taglib" // Register taglib extractor
+	_ "github.com/navidrome/navidrome/adapters/gotaglib" // Register taglib extractor
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/core"
 	_ "github.com/navidrome/navidrome/core/storage/local" // Register local storage

core/metrics/insights.go

@@ -265,6 +265,10 @@ func (c *insightsCollector) collect(ctx context.Context) []byte {
 	if err != nil {
 		log.Trace(ctx, "Error reading active users count", err)
 	}
+	data.Library.FileSuffixes, err = c.ds.MediaFile(ctx).CountBySuffix()
+	if err != nil {
+		log.Trace(ctx, "Error reading file suffixes count", err)
+	}
 
 	// Check for smart playlists
 	data.Config.HasSmartPlaylists, err = c.hasSmartPlaylists(ctx)

core/metrics/insights/data.go

@@ -40,6 +40,7 @@ type Data struct {
 		Libraries     int64            `json:"libraries"`
 		ActiveUsers   int64            `json:"activeUsers"`
 		ActivePlayers map[string]int64 `json:"activePlayers,omitempty"`
+		FileSuffixes  map[string]int64 `json:"fileSuffixes,omitempty"`
 	} `json:"library"`
 	Config struct {
 		LogLevel                string `json:"logLevel,omitempty"`

db/migrations/20260117201522_add_avg_rating_column.sql

@@ -0,0 +1,23 @@
+-- +goose Up
+ALTER TABLE album ADD COLUMN average_rating REAL NOT NULL DEFAULT 0;
+ALTER TABLE media_file ADD COLUMN average_rating REAL NOT NULL DEFAULT 0;
+ALTER TABLE artist ADD COLUMN average_rating REAL NOT NULL DEFAULT 0;
+
+-- Populate average_rating from existing ratings
+UPDATE album SET average_rating = coalesce(
+    (SELECT round(avg(rating), 2) FROM annotation WHERE item_id = album.id AND item_type = 'album' AND rating > 0),
+    0
+);
+UPDATE media_file SET average_rating = coalesce(
+    (SELECT round(avg(rating), 2) FROM annotation WHERE item_id = media_file.id AND item_type = 'media_file' AND rating > 0),
+    0
+);
+UPDATE artist SET average_rating = coalesce(
+    (SELECT round(avg(rating), 2) FROM annotation WHERE item_id = artist.id AND item_type = 'artist' AND rating > 0),
+    0
+);
+
+-- +goose Down
+ALTER TABLE artist DROP COLUMN average_rating;
+ALTER TABLE media_file DROP COLUMN average_rating;
+ALTER TABLE album DROP COLUMN average_rating;

go.mod

@@ -2,8 +2,13 @@ module github.com/navidrome/navidrome
 
 go 1.25
 
-// Fork to fix https://github.com/navidrome/navidrome/issues/3254
-replace github.com/dhowden/tag v0.0.0-20240417053706-3d75831295e8 => github.com/deluan/tag v0.0.0-20241002021117-dfe5e6ea396d
+replace (
+	// Fork to fix https://github.com/navidrome/navidrome/issues/3254
+	github.com/dhowden/tag v0.0.0-20240417053706-3d75831295e8 => github.com/deluan/tag v0.0.0-20241002021117-dfe5e6ea396d
+
+	// Fork to implement raw tags support
+	go.senan.xyz/taglib => github.com/deluan/go-taglib v0.0.0-20260119020817-8753c7531798
+)
 
 require (
 	github.com/Masterminds/squirrel v1.5.4
@@ -53,13 +58,15 @@ require (
 	github.com/rjeczalik/notify v0.9.3
 	github.com/robfig/cron/v3 v3.0.1
 	github.com/sabhiram/go-gitignore v0.0.0-20210923224102-525f6e181f06
-	github.com/sirupsen/logrus v1.9.3
+	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2
+	github.com/sirupsen/logrus v1.9.4
 	github.com/spf13/cobra v1.10.2
 	github.com/spf13/viper v1.21.0
 	github.com/stretchr/testify v1.11.1
 	github.com/tetratelabs/wazero v1.11.0
 	github.com/unrolled/secure v1.17.0
 	github.com/xrash/smetrics v0.0.0-20250705151800-55b8f293f342
+	go.senan.xyz/taglib v0.11.1
 	go.uber.org/goleak v1.3.0
 	golang.org/x/image v0.35.0
 	golang.org/x/net v0.49.0
@@ -91,7 +98,7 @@ require (
 	github.com/goccy/go-json v0.10.5 // indirect
 	github.com/goccy/go-yaml v1.19.2 // indirect
 	github.com/google/go-cmp v0.7.0 // indirect
-	github.com/google/pprof v0.0.0-20260111202518-71be6bfdd440 // indirect
+	github.com/google/pprof v0.0.0-20260115054156-294ebfa9ad83 // indirect
 	github.com/google/subcommands v1.2.0 // indirect
 	github.com/gorilla/css v1.0.1 // indirect
 	github.com/hashicorp/errwrap v1.1.0 // indirect

go.sum

@@ -36,6 +36,8 @@ github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.0 h1:NMZiJj8QnKe1LgsbDayM4UoHwbvwDRwnI3hwNaAHRnc=
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.0/go.mod h1:ZXNYxsqcloTdSy/rNShjYzMhyjf0LaoftYK0p+A3h40=
+github.com/deluan/go-taglib v0.0.0-20260119020817-8753c7531798 h1:q4fvcIK/LxElpyQILCejG6WPYjVb2F/4P93+k017ANk=
+github.com/deluan/go-taglib v0.0.0-20260119020817-8753c7531798/go.mod h1:sKDN0U4qXDlq6LFK+aOAkDH4Me5nDV1V/A4B+B69xBA=
 github.com/deluan/rest v0.0.0-20211102003136-6260bc399cbf h1:tb246l2Zmpt/GpF9EcHCKTtwzrd0HGfEmoODFA/qnk4=
 github.com/deluan/rest v0.0.0-20211102003136-6260bc399cbf/go.mod h1:tSgDythFsl0QgS/PFWfIZqcJKnkADWneY80jaVRlqK8=
 github.com/deluan/sanitize v0.0.0-20241120162836-fdfd8fdfaa55 h1:wSCnggTs2f2ji6nFwQmfwgINcmSMj0xF0oHnoyRSPe4=
@@ -54,6 +56,8 @@ github.com/djherbis/stream v1.4.0 h1:aVD46WZUiq5kJk55yxJAyw6Kuera6kmC3i2vEQyW/AE
 github.com/djherbis/stream v1.4.0/go.mod h1:cqjC1ZRq3FFwkGmUtHwcldbnW8f0Q4YuVsGW1eAFtOk=
 github.com/djherbis/times v1.6.0 h1:w2ctJ92J8fBvWPxugmXIv7Nz7Q3iDMKNx9v5ocVH20c=
 github.com/djherbis/times v1.6.0/go.mod h1:gOHeRAz2h+VJNZ5Gmc/o7iD9k4wW7NMVqieYCY99oc0=
+github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=
+github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/dylibso/observe-sdk/go v0.0.0-20240828172851-9145d8ad07e1 h1:idfl8M8rPW93NehFw5H1qqH8yG158t5POr+LX9avbJY=
@@ -106,8 +110,8 @@ github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/go-pipeline v0.0.0-20230411140531-6cbedfc1d3fc h1:hd+uUVsB1vdxohPneMrhGH2YfQuH5hRIK9u4/XCeUtw=
 github.com/google/go-pipeline v0.0.0-20230411140531-6cbedfc1d3fc/go.mod h1:SL66SJVysrh7YbDCP9tH30b8a9o/N2HeiQNUm85EKhc=
-github.com/google/pprof v0.0.0-20260111202518-71be6bfdd440 h1:oKBqR+eQXiIM7X8K1JEg9aoTEePLq/c6Awe484abOuA=
-github.com/google/pprof v0.0.0-20260111202518-71be6bfdd440/go.mod h1:MxpfABSjhmINe3F1It9d+8exIHFvUqtLIRCdOGNXqiI=
+github.com/google/pprof v0.0.0-20260115054156-294ebfa9ad83 h1:z2ogiKUYzX5Is6zr/vP9vJGqPwcdqsWjOt+V8J7+bTc=
+github.com/google/pprof v0.0.0-20260115054156-294ebfa9ad83/go.mod h1:MxpfABSjhmINe3F1It9d+8exIHFvUqtLIRCdOGNXqiI=
 github.com/google/subcommands v1.2.0 h1:vWQspBTo2nEqTUFita5/KeEWlUL8kQObDFbub/EN9oE=
 github.com/google/subcommands v1.2.0/go.mod h1:ZjhPrFU+Olkh9WazFPsl27BQ4UPiG37m3yTrtFlrHVk=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
@@ -234,13 +238,15 @@ github.com/sagikazarmark/locafero v0.12.0 h1:/NQhBAkUb4+fH1jivKHWusDYFjMOOKU88ee
 github.com/sagikazarmark/locafero v0.12.0/go.mod h1:sZh36u/YSZ918v0Io+U9ogLYQJ9tLLBmM4eneO6WwsI=
 github.com/sanity-io/litter v1.5.8 h1:uM/2lKrWdGbRXDrIq08Lh9XtVYoeGtcQxk9rtQ7+rYg=
 github.com/sanity-io/litter v1.5.8/go.mod h1:9gzJgR2i4ZpjZHsKvUXIRQVk7P+yM3e+jAF7bU2UI5U=
+github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 h1:KRzFb2m7YtdldCEkzs6KqmJw4nqEVZGK7IN2kJkjTuQ=
+github.com/santhosh-tekuri/jsonschema/v6 v6.0.2/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
 github.com/segmentio/asm v1.2.1 h1:DTNbBqs57ioxAD4PrArqftgypG4/qNpXoJx8TVXxPR0=
 github.com/segmentio/asm v1.2.1/go.mod h1:BqMnlJP91P8d+4ibuonYZw9mfnzI9HfxselHZr5aAcs=
 github.com/sethvargo/go-retry v0.3.0 h1:EEt31A35QhrcRZtrYFDTBg91cqZVnFL2navjDrah2SE=
 github.com/sethvargo/go-retry v0.3.0/go.mod h1:mNX17F0C/HguQMyMyJxcnU471gOZGxCLyYaFyAZraas=
 github.com/sirupsen/logrus v1.4.2/go.mod h1:tLMulIdttU9McNUspp0xgXVQah82FyeX6MwdIuYE2rE=
-github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ=
-github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ=
+github.com/sirupsen/logrus v1.9.4 h1:TsZE7l11zFCLZnZ+teH4Umoq5BhEIfIzfRDZ1Uzql2w=
+github.com/sirupsen/logrus v1.9.4/go.mod h1:ftWc9WdOfJ0a92nsE2jF5u5ZwH8Bv2zdeOC42RjbV2g=
 github.com/smartystreets/assertions v0.0.0-20180927180507-b2de0cb4f26d h1:zE9ykElWQ6/NYmHa3jpm/yHnI4xSofP+UP6SpjHcSeM=
 github.com/smartystreets/assertions v0.0.0-20180927180507-b2de0cb4f26d/go.mod h1:OnSkiWE9lh6wB0YB77sQom3nweQdgAjqCqsofrRNTgc=
 github.com/smartystreets/goconvey v1.6.4 h1:fv0U8FUIMPNf1L9lnHLvLhgicrIVChEkdzIKYqbNC9s=
@@ -269,7 +275,6 @@ github.com/stretchr/testify v0.0.0-20161117074351-18a02ba4a312/go.mod h1:a8OnRci
 github.com/stretchr/testify v1.2.2/go.mod h1:a8OnRcib4nhh0OaRAV+Yts87kKdq0PP7pXfy6kDkUVs=
 github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
 github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
-github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
@@ -358,7 +363,6 @@ golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7w
 golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220615213510-4f61da869c0c/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=

model/annotation.go

@@ -3,12 +3,13 @@ package model
 import "time"
 
 type Annotations struct {
-	PlayCount int64      `structs:"play_count" json:"playCount,omitempty"`
-	PlayDate  *time.Time `structs:"play_date"  json:"playDate,omitempty" `
-	Rating    int        `structs:"rating"     json:"rating,omitempty"   `
-	RatedAt   *time.Time `structs:"rated_at"   json:"ratedAt,omitempty"  `
-	Starred   bool       `structs:"starred"    json:"starred,omitempty"  `
-	StarredAt *time.Time `structs:"starred_at" json:"starredAt,omitempty"`
+	PlayCount     int64      `structs:"play_count"     json:"playCount,omitempty"`
+	PlayDate      *time.Time `structs:"play_date"      json:"playDate,omitempty" `
+	Rating        int        `structs:"rating"         json:"rating,omitempty"   `
+	RatedAt       *time.Time `structs:"rated_at"       json:"ratedAt,omitempty"  `
+	Starred       bool       `structs:"starred"        json:"starred,omitempty"  `
+	StarredAt     *time.Time `structs:"starred_at"     json:"starredAt,omitempty"`
+	AverageRating float64    `structs:"average_rating" json:"averageRating,omitempty"`
 }
 
 type AnnotatedRepository interface {

model/mediafile.go

@@ -353,6 +353,7 @@ type MediaFileCursor iter.Seq2[MediaFile, error]
 
 type MediaFileRepository interface {
 	CountAll(options ...QueryOptions) (int64, error)
+	CountBySuffix(options ...QueryOptions) (map[string]int64, error)
 	Exists(id string) (bool, error)
 	Put(m *MediaFile) error
 	Get(id string) (*MediaFile, error)

persistence/album_repository_test.go

@@ -126,6 +126,89 @@ var _ = Describe("AlbumRepository", func() {
 		)
 	})
 
+	Describe("Album.AverageRating", func() {
+		It("returns 0 when no ratings exist", func() {
+			newID := id.NewRandom()
+			Expect(albumRepo.Put(&model.Album{LibraryID: 1, ID: newID, Name: "no ratings album"})).To(Succeed())
+
+			album, err := albumRepo.Get(newID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(album.AverageRating).To(Equal(0.0))
+
+			_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": newID}))
+		})
+
+		It("returns the user's rating as average when only one user rated", func() {
+			newID := id.NewRandom()
+			Expect(albumRepo.Put(&model.Album{LibraryID: 1, ID: newID, Name: "single rating album"})).To(Succeed())
+			Expect(albumRepo.SetRating(4, newID)).To(Succeed())
+
+			album, err := albumRepo.Get(newID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(album.AverageRating).To(Equal(4.0))
+
+			_, _ = albumRepo.executeSQL(squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": newID}))
+			_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": newID}))
+		})
+
+		It("calculates average across multiple users", func() {
+			newID := id.NewRandom()
+			Expect(albumRepo.Put(&model.Album{LibraryID: 1, ID: newID, Name: "multi rating album"})).To(Succeed())
+
+			Expect(albumRepo.SetRating(4, newID)).To(Succeed())
+
+			user2Ctx := request.WithUser(GinkgoT().Context(), regularUser)
+			user2Repo := NewAlbumRepository(user2Ctx, GetDBXBuilder()).(*albumRepository)
+			Expect(user2Repo.SetRating(5, newID)).To(Succeed())
+
+			album, err := albumRepo.Get(newID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(album.AverageRating).To(Equal(4.5))
+
+			_, _ = albumRepo.executeSQL(squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": newID}))
+			_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": newID}))
+		})
+
+		It("excludes zero ratings from average calculation", func() {
+			newID := id.NewRandom()
+			Expect(albumRepo.Put(&model.Album{LibraryID: 1, ID: newID, Name: "zero rating excluded album"})).To(Succeed())
+			Expect(albumRepo.SetRating(3, newID)).To(Succeed())
+
+			user2Ctx := request.WithUser(GinkgoT().Context(), regularUser)
+			user2Repo := NewAlbumRepository(user2Ctx, GetDBXBuilder()).(*albumRepository)
+			Expect(user2Repo.SetRating(0, newID)).To(Succeed())
+
+			album, err := albumRepo.Get(newID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(album.AverageRating).To(Equal(3.0))
+
+			_, _ = albumRepo.executeSQL(squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": newID}))
+			_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": newID}))
+		})
+
+		It("rounds to 2 decimal places", func() {
+			newID := id.NewRandom()
+			Expect(albumRepo.Put(&model.Album{LibraryID: 1, ID: newID, Name: "rounding test album"})).To(Succeed())
+
+			Expect(albumRepo.SetRating(5, newID)).To(Succeed())
+
+			user2Ctx := request.WithUser(GinkgoT().Context(), regularUser)
+			user2Repo := NewAlbumRepository(user2Ctx, GetDBXBuilder()).(*albumRepository)
+			Expect(user2Repo.SetRating(4, newID)).To(Succeed())
+
+			user3Ctx := request.WithUser(GinkgoT().Context(), thirdUser)
+			user3Repo := NewAlbumRepository(user3Ctx, GetDBXBuilder()).(*albumRepository)
+			Expect(user3Repo.SetRating(4, newID)).To(Succeed())
+
+			album, err := albumRepo.Get(newID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(album.AverageRating).To(Equal(4.33)) // (5 + 4 + 4) / 3 = 4.333...
+
+			_, _ = albumRepo.executeSQL(squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": newID}))
+			_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": newID}))
+		})
+	})
+
 	Describe("dbAlbum mapping", func() {
 		var (
 			a    model.Album

persistence/mediafile_repository.go

@@ -124,6 +124,25 @@ func (r *mediaFileRepository) CountAll(options ...model.QueryOptions) (int64, er
 	return r.count(query, options...)
 }
 
+func (r *mediaFileRepository) CountBySuffix(options ...model.QueryOptions) (map[string]int64, error) {
+	sel := r.newSelect(options...).
+		Columns("lower(suffix) as suffix", "count(*) as count").
+		GroupBy("lower(suffix)")
+	var res []struct {
+		Suffix string
+		Count  int64
+	}
+	err := r.queryAll(sel, &res)
+	if err != nil {
+		return nil, err
+	}
+	counts := make(map[string]int64, len(res))
+	for _, c := range res {
+		counts[c.Suffix] = c.Count
+	}
+	return counts, nil
+}
+
 func (r *mediaFileRepository) Exists(id string) (bool, error) {
 	return r.exists(Eq{"media_file.id": id})
 }

persistence/mediafile_repository_test.go

@@ -41,6 +41,44 @@ var _ = Describe("MediaRepository", func() {
 		Expect(mr.CountAll()).To(Equal(int64(10)))
 	})
 
+	Describe("CountBySuffix", 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"}
+
+			Expect(mr.Put(&mp3File)).To(Succeed())
+			Expect(mr.Put(&flacFile1)).To(Succeed())
+			Expect(mr.Put(&flacFile2)).To(Succeed())
+			Expect(mr.Put(&flacUpperFile)).To(Succeed())
+		})
+
+		AfterEach(func() {
+			_ = mr.Delete(mp3File.ID)
+			_ = mr.Delete(flacFile1.ID)
+			_ = mr.Delete(flacFile2.ID)
+			_ = mr.Delete(flacUpperFile.ID)
+		})
+
+		It("counts media files grouped by suffix with lowercase normalization", func() {
+			counts, err := mr.CountBySuffix()
+			Expect(err).ToNot(HaveOccurred())
+
+			// Should have lowercase keys only
+			Expect(counts).To(HaveKey("mp3"))
+			Expect(counts).To(HaveKey("flac"))
+			Expect(counts).ToNot(HaveKey("FLAC"))
+
+			// mp3: 1 file
+			Expect(counts["mp3"]).To(Equal(int64(1)))
+			// flac: 3 files (2 lowercase + 1 uppercase normalized)
+			Expect(counts["flac"]).To(Equal(int64(3)))
+		})
+	})
+
 	It("returns songs ordered by lyrics with a specific title/artist", func() {
 		// attempt to mimic filters.SongsByArtistTitleWithLyricsFirst, except we want all items
 		results, err := mr.GetAll(model.QueryOptions{
@@ -119,6 +157,74 @@ var _ = Describe("MediaRepository", func() {
 			Expect(mf.PlayCount).To(Equal(int64(1)))
 		})
 
+		Describe("AverageRating", func() {
+			var raw *mediaFileRepository
+
+			BeforeEach(func() {
+				raw = mr.(*mediaFileRepository)
+			})
+
+			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())
+
+				mf, err := mr.Get(newID)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(mf.AverageRating).To(Equal(0.0))
+
+				_, _ = raw.executeSQL(squirrel.Delete("media_file").Where(squirrel.Eq{"id": newID}))
+			})
+
+			It("returns the user's rating as average when only one user rated", func() {
+				newID := id.NewRandom()
+				Expect(mr.Put(&model.MediaFile{LibraryID: 1, ID: newID, Path: "/test/single-rating.mp3"})).To(Succeed())
+				Expect(mr.SetRating(5, newID)).To(Succeed())
+
+				mf, err := mr.Get(newID)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(mf.AverageRating).To(Equal(5.0))
+
+				_, _ = raw.executeSQL(squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": newID}))
+				_, _ = raw.executeSQL(squirrel.Delete("media_file").Where(squirrel.Eq{"id": newID}))
+			})
+
+			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.SetRating(3, newID)).To(Succeed())
+
+				user2Ctx := request.WithUser(GinkgoT().Context(), regularUser)
+				user2Repo := NewMediaFileRepository(user2Ctx, GetDBXBuilder())
+				Expect(user2Repo.SetRating(5, newID)).To(Succeed())
+
+				mf, err := mr.Get(newID)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(mf.AverageRating).To(Equal(4.0))
+
+				_, _ = raw.executeSQL(squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": newID}))
+				_, _ = raw.executeSQL(squirrel.Delete("media_file").Where(squirrel.Eq{"id": newID}))
+			})
+
+			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.SetRating(4, newID)).To(Succeed())
+
+				user2Ctx := request.WithUser(GinkgoT().Context(), regularUser)
+				user2Repo := NewMediaFileRepository(user2Ctx, GetDBXBuilder())
+				Expect(user2Repo.SetRating(0, newID)).To(Succeed())
+
+				mf, err := mr.Get(newID)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(mf.AverageRating).To(Equal(4.0))
+
+				_, _ = raw.executeSQL(squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": newID}))
+				_, _ = raw.executeSQL(squirrel.Delete("media_file").Where(squirrel.Eq{"id": newID}))
+			})
+		})
+
 		It("preserves play date if and only if provided date is older", func() {
 			id := "incplay.playdate"
 			Expect(mr.Put(&model.MediaFile{LibraryID: 1, ID: id})).To(BeNil())

persistence/persistence_suite_test.go

@@ -130,7 +130,8 @@ var (
 var (
 	adminUser   = model.User{ID: "userid", UserName: "userid", Name: "admin", Email: "admin@email.com", IsAdmin: true}
 	regularUser = model.User{ID: "2222", UserName: "regular-user", Name: "Regular User", Email: "regular@example.com"}
-	testUsers   = model.Users{adminUser, regularUser}
+	thirdUser   = model.User{ID: "3333", UserName: "third-user", Name: "Third User", Email: "third@example.com"}
+	testUsers   = model.Users{adminUser, regularUser, thirdUser}
 )
 
 func p(path string) string {

persistence/sql_annotations.go

@@ -17,7 +17,7 @@ const annotationTable = "annotation"
 func (r sqlRepository) withAnnotation(query SelectBuilder, idField string) SelectBuilder {
 	userID := loggedUser(r.ctx).ID
 	if userID == invalidUserId {
-		return query
+		return query.Columns(fmt.Sprintf("%s.average_rating", r.tableName))
 	}
 	query = query.
 		LeftJoin("annotation on ("+
@@ -38,6 +38,8 @@ func (r sqlRepository) withAnnotation(query SelectBuilder, idField string) Selec
 		query = query.Columns("coalesce(play_count, 0) as play_count")
 	}
 
+	query = query.Columns(fmt.Sprintf("%s.average_rating", r.tableName))
+
 	return query
 }
 
@@ -79,7 +81,22 @@ func (r sqlRepository) SetStar(starred bool, ids ...string) error {
 
 func (r sqlRepository) SetRating(rating int, itemID string) error {
 	ratedAt := time.Now()
-	return r.annUpsert(map[string]interface{}{"rating": rating, "rated_at": ratedAt}, itemID)
+	err := r.annUpsert(map[string]interface{}{"rating": rating, "rated_at": ratedAt}, itemID)
+	if err != nil {
+		return err
+	}
+	return r.updateAvgRating(itemID)
+}
+
+func (r sqlRepository) updateAvgRating(itemID string) error {
+	upd := Update(r.tableName).
+		Where(Eq{"id": itemID}).
+		Set("average_rating", Expr(
+			"coalesce((select round(avg(rating), 2) from annotation where item_id = ? and item_type = ? and rating > 0), 0)",
+			itemID, r.tableName,
+		))
+	_, err := r.executeSQL(upd)
+	return err
 }
 
 func (r sqlRepository) IncPlayCount(itemID string, ts time.Time) error {

plugins/cmd/ndpgen/go.mod

@@ -4,10 +4,10 @@ go 1.25
 
 require (
 	github.com/extism/go-pdk v1.1.3
-	github.com/onsi/ginkgo/v2 v2.27.3
-	github.com/onsi/gomega v1.38.3
-	github.com/xeipuuv/gojsonschema v1.2.0
-	golang.org/x/tools v0.40.0
+	github.com/onsi/ginkgo/v2 v2.27.5
+	github.com/onsi/gomega v1.39.0
+	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2
+	golang.org/x/tools v0.41.0
 	gopkg.in/yaml.v3 v3.0.1
 )
 
@@ -16,13 +16,11 @@ require (
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-task/slim-sprig/v3 v3.0.0 // indirect
 	github.com/google/go-cmp v0.7.0 // indirect
-	github.com/google/pprof v0.0.0-20250403155104-27863c87afa6 // indirect
-	github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f // indirect
-	github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 // indirect
+	github.com/google/pprof v0.0.0-20260115054156-294ebfa9ad83 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
-	golang.org/x/mod v0.31.0 // indirect
-	golang.org/x/net v0.48.0 // indirect
+	golang.org/x/mod v0.32.0 // indirect
+	golang.org/x/net v0.49.0 // indirect
 	golang.org/x/sync v0.19.0 // indirect
-	golang.org/x/sys v0.39.0 // indirect
-	golang.org/x/text v0.32.0 // indirect
+	golang.org/x/sys v0.40.0 // indirect
+	golang.org/x/text v0.33.0 // indirect
 )

plugins/cmd/ndpgen/go.sum

@@ -1,8 +1,9 @@
 github.com/Masterminds/semver/v3 v3.4.0 h1:Zog+i5UMtVoCU8oKka5P7i9q9HgrJeGzI9SA1Xbatp0=
 github.com/Masterminds/semver/v3 v3.4.0/go.mod h1:4V+yj/TJE1HU9XfppCwVMZq3I84lprf4nC11bSS5beM=
-github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=
+github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
 github.com/extism/go-pdk v1.1.3 h1:hfViMPWrqjN6u67cIYRALZTZLk/enSPpNKa+rZ9X2SQ=
 github.com/extism/go-pdk v1.1.3/go.mod h1:Gz+LIU/YCKnKXhgge8yo5Yu1F/lbv7KtKFkiCSzW/P4=
 github.com/gkampitakis/ciinfo v0.3.2 h1:JcuOPk8ZU7nZQjdUhctuhQofk7BGHuIy0c9Ez8BNhXs=
@@ -19,8 +20,8 @@ github.com/goccy/go-yaml v1.18.0 h1:8W7wMFS12Pcas7KU+VVkaiCng+kG8QiFeFwzFb+rwuw=
 github.com/goccy/go-yaml v1.18.0/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
-github.com/google/pprof v0.0.0-20250403155104-27863c87afa6 h1:BHT72Gu3keYf3ZEu2J0b1vyeLSOYI8bm5wbJM/8yDe8=
-github.com/google/pprof v0.0.0-20250403155104-27863c87afa6/go.mod h1:boTsfXsheKC2y+lKOCMpSfarhxDeIzfZG1jqGcPl3cA=
+github.com/google/pprof v0.0.0-20260115054156-294ebfa9ad83 h1:z2ogiKUYzX5Is6zr/vP9vJGqPwcdqsWjOt+V8J7+bTc=
+github.com/google/pprof v0.0.0-20260115054156-294ebfa9ad83/go.mod h1:MxpfABSjhmINe3F1It9d+8exIHFvUqtLIRCdOGNXqiI=
 github.com/joshdk/go-junit v1.0.0 h1:S86cUKIdwBHWwA6xCmFlf3RTLfVXYQfvanM5Uh+K6GE=
 github.com/joshdk/go-junit v1.0.0/go.mod h1:TiiV0PqkaNfFXjEiyjWM3XXrhVyCa1K4Zfga6W52ung=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
@@ -31,16 +32,16 @@ github.com/maruel/natural v1.1.1 h1:Hja7XhhmvEFhcByqDoHz9QZbkWey+COd9xWfCfn1ioo=
 github.com/maruel/natural v1.1.1/go.mod h1:v+Rfd79xlw1AgVBjbO0BEQmptqb5HvL/k9GRHB7ZKEg=
 github.com/mfridman/tparse v0.18.0 h1:wh6dzOKaIwkUGyKgOntDW4liXSo37qg5AXbIhkMV3vE=
 github.com/mfridman/tparse v0.18.0/go.mod h1:gEvqZTuCgEhPbYk/2lS3Kcxg1GmTxxU7kTC8DvP0i/A=
-github.com/onsi/ginkgo/v2 v2.27.3 h1:ICsZJ8JoYafeXFFlFAG75a7CxMsJHwgKwtO+82SE9L8=
-github.com/onsi/ginkgo/v2 v2.27.3/go.mod h1:ArE1D/XhNXBXCBkKOLkbsb2c81dQHCRcF5zwn/ykDRo=
-github.com/onsi/gomega v1.38.3 h1:eTX+W6dobAYfFeGC2PV6RwXRu/MyT+cQguijutvkpSM=
-github.com/onsi/gomega v1.38.3/go.mod h1:ZCU1pkQcXDO5Sl9/VVEGlDyp+zm0m1cmeG5TOzLgdh4=
+github.com/onsi/ginkgo/v2 v2.27.5 h1:ZeVgZMx2PDMdJm/+w5fE/OyG6ILo1Y3e+QX4zSR0zTE=
+github.com/onsi/ginkgo/v2 v2.27.5/go.mod h1:ArE1D/XhNXBXCBkKOLkbsb2c81dQHCRcF5zwn/ykDRo=
+github.com/onsi/gomega v1.39.0 h1:y2ROC3hKFmQZJNFeGAMeHZKkjBL65mIZcvrLQBF9k6Q=
+github.com/onsi/gomega v1.39.0/go.mod h1:ZCU1pkQcXDO5Sl9/VVEGlDyp+zm0m1cmeG5TOzLgdh4=
 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/rogpeppe/go-internal v1.13.1 h1:KvO1DLK/DRN07sQ1LQKScxyZJuNnedQ5/wKSR38lUII=
 github.com/rogpeppe/go-internal v1.13.1/go.mod h1:uMEvuHeurkdAXX61udpOXGD/AzZDWNMNyH2VO9fmH0o=
-github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
-github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 h1:KRzFb2m7YtdldCEkzs6KqmJw4nqEVZGK7IN2kJkjTuQ=
+github.com/santhosh-tekuri/jsonschema/v6 v6.0.2/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
 github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
 github.com/tidwall/gjson v1.18.0 h1:FIDeeyB800efLX89e5a8Y0BNH+LOngJyGrIWxG2FKQY=
@@ -51,26 +52,20 @@ github.com/tidwall/pretty v1.2.1 h1:qjsOFOWWQl+N3RsoF5/ssm1pHmJJwhjlSbZ51I6wMl4=
 github.com/tidwall/pretty v1.2.1/go.mod h1:ITEVvHYasfjBbM0u2Pg8T2nJnzm8xPwvNhhsoaGGjNU=
 github.com/tidwall/sjson v1.2.5 h1:kLy8mja+1c9jlljvWTlSazM7cKDRfJuR/bOJhcY5NcY=
 github.com/tidwall/sjson v1.2.5/go.mod h1:Fvgq9kS/6ociJEDnK0Fk1cpYF4FIW6ZF7LAe+6jwd28=
-github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f h1:J9EGpcZtP0E/raorCMxlFGSTBrsSlaDGf3jU/qvAE2c=
-github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f/go.mod h1:N2zxlSyiKSe5eX1tZViRH5QA0qijqEDrYZiPEAiq3wU=
-github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 h1:EzJWgHovont7NscjpAxXsDA8S8BMYve8Y5+7cuRE7R0=
-github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415/go.mod h1:GwrjFmJcFw6At/Gs6z4yjiIwzuJ1/+UwLxMQDVQXShQ=
-github.com/xeipuuv/gojsonschema v1.2.0 h1:LhYJRs+L4fBtjZUfuSZIKGeVu0QRy8e5Xi7D17UxZ74=
-github.com/xeipuuv/gojsonschema v1.2.0/go.mod h1:anYRn/JVcOK2ZgGU+IjEV4nwlhoK5sQluxsYJ78Id3Y=
 go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
-golang.org/x/mod v0.31.0 h1:HaW9xtz0+kOcWKwli0ZXy79Ix+UW/vOfmWI5QVd2tgI=
-golang.org/x/mod v0.31.0/go.mod h1:43JraMp9cGx1Rx3AqioxrbrhNsLl2l/iNAvuBkrezpg=
-golang.org/x/net v0.48.0 h1:zyQRTTrjc33Lhh0fBgT/H3oZq9WuvRR5gPC70xpDiQU=
-golang.org/x/net v0.48.0/go.mod h1:+ndRgGjkh8FGtu1w1FGbEC31if4VrNVMuKTgcAAnQRY=
+golang.org/x/mod v0.32.0 h1:9F4d3PHLljb6x//jOyokMv3eX+YDeepZSEo3mFJy93c=
+golang.org/x/mod v0.32.0/go.mod h1:SgipZ/3h2Ci89DlEtEXWUk/HteuRin+HHhN+WbNhguU=
+golang.org/x/net v0.49.0 h1:eeHFmOGUTtaaPSGNmjBKpbng9MulQsJURQUAfUwY++o=
+golang.org/x/net v0.49.0/go.mod h1:/ysNB2EvaqvesRkuLAyjI1ycPZlQHM3q01F02UY/MV8=
 golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
 golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
-golang.org/x/sys v0.39.0 h1:CvCKL8MeisomCi6qNZ+wbb0DN9E5AATixKsvNtMoMFk=
-golang.org/x/sys v0.39.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
-golang.org/x/text v0.32.0 h1:ZD01bjUt1FQ9WJ0ClOL5vxgxOI/sVCNgX1YtKwcY0mU=
-golang.org/x/text v0.32.0/go.mod h1:o/rUWzghvpD5TXrTIBuJU77MTaN0ljMWE47kxGJQ7jY=
-golang.org/x/tools v0.40.0 h1:yLkxfA+Qnul4cs9QA3KnlFu0lVmd8JJfoq+E41uSutA=
-golang.org/x/tools v0.40.0/go.mod h1:Ik/tzLRlbscWpqqMRjyWYDisX8bG13FrdXp3o4Sr9lc=
+golang.org/x/sys v0.40.0 h1:DBZZqJ2Rkml6QMQsZywtnjnnGvHza6BTfYFWY9kjEWQ=
+golang.org/x/sys v0.40.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/text v0.33.0 h1:B3njUFyqtHDUI5jMn1YIr5B0IE2U0qck04r6d4KPAxE=
+golang.org/x/text v0.33.0/go.mod h1:LuMebE6+rBincTi9+xWTY8TztLzKHc/9C1uBCG27+q8=
+golang.org/x/tools v0.41.0 h1:a9b8iMweWG+S0OBnlU36rzLp20z1Rp10w+IY2czHTQc=
+golang.org/x/tools v0.41.0/go.mod h1:XSY6eDqxVNiYgezAVqqCeihT4j1U2CCsqvH3WhQpnlg=
 google.golang.org/protobuf v1.36.7 h1:IgrO7UwFQGJdRNXH/sQux4R1Dj1WAKcLElzeeRaXV2A=
 google.golang.org/protobuf v1.36.7/go.mod h1:jduwjTPXsFjZGTmRluh+L6NjiWu7pchiJ2/5YcXBHnY=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

plugins/cmd/ndpgen/internal/xtp_schema_validate.go

@@ -3,10 +3,11 @@ package internal
 import (
 	_ "embed"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"strings"
 
-	"github.com/xeipuuv/gojsonschema"
+	"github.com/santhosh-tekuri/jsonschema/v6"
 	"gopkg.in/yaml.v3"
 )
 
@@ -25,27 +26,61 @@ func ValidateXTPSchema(generatedSchema []byte) error {
 		return fmt.Errorf("failed to parse generated schema as YAML: %w", err)
 	}
 
-	// Convert to JSON for the validator
-	jsonBytes, err := json.Marshal(schemaDoc)
-	if err != nil {
-		return fmt.Errorf("failed to convert schema to JSON: %w", err)
+	// Parse the XTP schema JSON
+	var xtpSchema any
+	if err := json.Unmarshal([]byte(xtpSchemaJSON), &xtpSchema); err != nil {
+		return fmt.Errorf("failed to parse XTP schema: %w", err)
 	}
 
-	schemaLoader := gojsonschema.NewStringLoader(xtpSchemaJSON)
-	documentLoader := gojsonschema.NewBytesLoader(jsonBytes)
-
-	result, err := gojsonschema.Validate(schemaLoader, documentLoader)
-	if err != nil {
-		return fmt.Errorf("schema validation failed: %w", err)
+	// Compile the XTP schema
+	compiler := jsonschema.NewCompiler()
+	if err := compiler.AddResource("xtp-schema.json", xtpSchema); err != nil {
+		return fmt.Errorf("failed to add XTP schema resource: %w", err)
 	}
 
-	if !result.Valid() {
-		var errs []string
-		for _, desc := range result.Errors() {
-			errs = append(errs, fmt.Sprintf("- %s", desc))
-		}
-		return fmt.Errorf("schema validation errors:\n%s", strings.Join(errs, "\n"))
+	schema, err := compiler.Compile("xtp-schema.json")
+	if err != nil {
+		return fmt.Errorf("failed to compile XTP schema: %w", err)
+	}
+
+	// Validate the generated schema against XTP schema
+	if err := schema.Validate(schemaDoc); err != nil {
+		return fmt.Errorf("schema validation errors:\n%s", formatValidationErrors(err))
 	}
 
 	return nil
 }
+
+// formatValidationErrors formats jsonschema validation errors into readable strings.
+func formatValidationErrors(err error) string {
+	var validationErr *jsonschema.ValidationError
+	if !errors.As(err, &validationErr) {
+		return fmt.Sprintf("- %s", err.Error())
+	}
+
+	var errs []string
+	collectValidationErrors(validationErr, &errs)
+
+	if len(errs) == 0 {
+		return fmt.Sprintf("- %s", validationErr.Error())
+	}
+	return strings.Join(errs, "\n")
+}
+
+// collectValidationErrors recursively collects leaf validation errors.
+func collectValidationErrors(err *jsonschema.ValidationError, errs *[]string) {
+	if len(err.Causes) > 0 {
+		for _, cause := range err.Causes {
+			collectValidationErrors(cause, errs)
+		}
+		return
+	}
+
+	// Leaf error - format with location if available
+	msg := err.Error()
+	if len(err.InstanceLocation) > 0 {
+		location := strings.Join(err.InstanceLocation, "/")
+		msg = fmt.Sprintf("%s: %s", location, msg)
+	}
+	*errs = append(*errs, fmt.Sprintf("- %s", msg))
+}

plugins/config_validation.go

@@ -0,0 +1,129 @@
+package plugins
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/santhosh-tekuri/jsonschema/v6"
+)
+
+// ConfigValidationError represents a validation error with field path and message.
+type ConfigValidationError struct {
+	Field   string `json:"field"`
+	Message string `json:"message"`
+}
+
+// ConfigValidationErrors is a collection of validation errors.
+type ConfigValidationErrors struct {
+	Errors []ConfigValidationError `json:"errors"`
+}
+
+func (e *ConfigValidationErrors) Error() string {
+	if len(e.Errors) == 0 {
+		return "validation failed"
+	}
+	var msgs []string
+	for _, err := range e.Errors {
+		if err.Field != "" {
+			msgs = append(msgs, fmt.Sprintf("%s: %s", err.Field, err.Message))
+		} else {
+			msgs = append(msgs, err.Message)
+		}
+	}
+	return strings.Join(msgs, "; ")
+}
+
+// ValidateConfig validates a config JSON string against a plugin's config schema.
+// If the manifest has no config schema, it returns an error indicating the plugin
+// has no configurable options.
+// Returns nil if validation passes, ConfigValidationErrors if validation fails.
+func ValidateConfig(manifest *Manifest, configJSON string) error {
+	// If no config schema defined, plugin has no configurable options
+	if !manifest.HasConfigSchema() {
+		return fmt.Errorf("plugin has no configurable options")
+	}
+
+	// Parse the config JSON (empty string treated as empty object)
+	var configData any
+	if configJSON == "" {
+		configData = map[string]any{}
+	} else {
+		if err := json.Unmarshal([]byte(configJSON), &configData); err != nil {
+			return &ConfigValidationErrors{
+				Errors: []ConfigValidationError{{
+					Message: fmt.Sprintf("invalid JSON: %v", err),
+				}},
+			}
+		}
+	}
+
+	// Compile the schema
+	compiler := jsonschema.NewCompiler()
+	if err := compiler.AddResource("schema.json", manifest.Config.Schema); err != nil {
+		return fmt.Errorf("adding schema resource: %w", err)
+	}
+
+	schema, err := compiler.Compile("schema.json")
+	if err != nil {
+		return fmt.Errorf("compiling schema: %w", err)
+	}
+
+	// Validate config against schema
+	if err := schema.Validate(configData); err != nil {
+		return convertValidationError(err)
+	}
+
+	return nil
+}
+
+// convertValidationError converts jsonschema validation errors to our format.
+func convertValidationError(err error) *ConfigValidationErrors {
+	var validationErr *jsonschema.ValidationError
+	if !errors.As(err, &validationErr) {
+		return &ConfigValidationErrors{
+			Errors: []ConfigValidationError{{
+				Message: err.Error(),
+			}},
+		}
+	}
+
+	var configErrors []ConfigValidationError
+	collectErrors(validationErr, &configErrors)
+
+	if len(configErrors) == 0 {
+		configErrors = append(configErrors, ConfigValidationError{
+			Message: validationErr.Error(),
+		})
+	}
+
+	return &ConfigValidationErrors{Errors: configErrors}
+}
+
+// collectErrors recursively collects validation errors from the error tree.
+func collectErrors(err *jsonschema.ValidationError, errors *[]ConfigValidationError) {
+	// If there are child errors, collect from them
+	if len(err.Causes) > 0 {
+		for _, cause := range err.Causes {
+			collectErrors(cause, errors)
+		}
+		return
+	}
+
+	// Leaf error - add it
+	field := ""
+	if len(err.InstanceLocation) > 0 {
+		field = strings.Join(err.InstanceLocation, "/")
+	}
+
+	*errors = append(*errors, ConfigValidationError{
+		Field:   field,
+		Message: err.Error(),
+	})
+}
+
+// HasConfigSchema returns true if the manifest defines a config schema.
+func (m *Manifest) HasConfigSchema() bool {
+	return m.Config != nil && m.Config.Schema != nil
+}

plugins/config_validation_test.go

@@ -0,0 +1,186 @@
+//go:build !windows
+
+package plugins
+
+import (
+	"errors"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Config Validation", func() {
+	Describe("ValidateConfig", func() {
+		Context("when manifest has no config schema", func() {
+			It("returns an error", func() {
+				manifest := &Manifest{
+					Name:    "test",
+					Author:  "test",
+					Version: "1.0.0",
+				}
+				err := ValidateConfig(manifest, `{"key": "value"}`)
+				Expect(err).To(HaveOccurred())
+				Expect(err.Error()).To(ContainSubstring("no configurable options"))
+			})
+		})
+
+		Context("when manifest has config schema", func() {
+			var manifest *Manifest
+
+			BeforeEach(func() {
+				manifest = &Manifest{
+					Name:    "test",
+					Author:  "test",
+					Version: "1.0.0",
+					Config: &ConfigDefinition{
+						Schema: map[string]any{
+							"type": "object",
+							"properties": map[string]any{
+								"apiKey": map[string]any{
+									"type":        "string",
+									"description": "API key for the service",
+									"minLength":   float64(1),
+								},
+								"timeout": map[string]any{
+									"type":    "integer",
+									"minimum": float64(1),
+									"maximum": float64(300),
+								},
+								"enabled": map[string]any{
+									"type": "boolean",
+								},
+							},
+							"required": []any{"apiKey"},
+						},
+					},
+				}
+			})
+
+			It("accepts valid config", func() {
+				err := ValidateConfig(manifest, `{"apiKey": "secret123", "timeout": 30}`)
+				Expect(err).ToNot(HaveOccurred())
+			})
+
+			It("rejects empty config when required fields are missing", func() {
+				err := ValidateConfig(manifest, "")
+				Expect(err).To(HaveOccurred())
+				Expect(err.Error()).To(ContainSubstring("apiKey"))
+
+				err = ValidateConfig(manifest, "{}")
+				Expect(err).To(HaveOccurred())
+				Expect(err.Error()).To(ContainSubstring("apiKey"))
+			})
+
+			It("rejects config missing required field", func() {
+				err := ValidateConfig(manifest, `{"timeout": 30}`)
+				Expect(err).To(HaveOccurred())
+				Expect(err.Error()).To(ContainSubstring("apiKey"))
+			})
+
+			It("rejects config with wrong type", func() {
+				err := ValidateConfig(manifest, `{"apiKey": "secret", "timeout": "not a number"}`)
+				Expect(err).To(HaveOccurred())
+				Expect(err.Error()).To(ContainSubstring("timeout"))
+			})
+
+			It("rejects config with value out of range", func() {
+				err := ValidateConfig(manifest, `{"apiKey": "secret", "timeout": 500}`)
+				Expect(err).To(HaveOccurred())
+				Expect(err.Error()).To(ContainSubstring("timeout"))
+			})
+
+			It("rejects config with empty required string", func() {
+				err := ValidateConfig(manifest, `{"apiKey": ""}`)
+				Expect(err).To(HaveOccurred())
+				Expect(err.Error()).To(ContainSubstring("apiKey"))
+			})
+
+			It("rejects invalid JSON", func() {
+				err := ValidateConfig(manifest, `{invalid json}`)
+				Expect(err).To(HaveOccurred())
+				var validationErr *ConfigValidationErrors
+				Expect(errors.As(err, &validationErr)).To(BeTrue())
+				Expect(validationErr.Errors[0].Message).To(ContainSubstring("invalid JSON"))
+			})
+		})
+
+		Context("with enum values", func() {
+			It("accepts valid enum value", func() {
+				manifest := &Manifest{
+					Name:    "test",
+					Author:  "test",
+					Version: "1.0.0",
+					Config: &ConfigDefinition{
+						Schema: map[string]any{
+							"type": "object",
+							"properties": map[string]any{
+								"logLevel": map[string]any{
+									"type": "string",
+									"enum": []any{"debug", "info", "warn", "error"},
+								},
+							},
+						},
+					},
+				}
+				err := ValidateConfig(manifest, `{"logLevel": "info"}`)
+				Expect(err).ToNot(HaveOccurred())
+			})
+
+			It("rejects invalid enum value", func() {
+				manifest := &Manifest{
+					Name:    "test",
+					Author:  "test",
+					Version: "1.0.0",
+					Config: &ConfigDefinition{
+						Schema: map[string]any{
+							"type": "object",
+							"properties": map[string]any{
+								"logLevel": map[string]any{
+									"type": "string",
+									"enum": []any{"debug", "info", "warn", "error"},
+								},
+							},
+						},
+					},
+				}
+				err := ValidateConfig(manifest, `{"logLevel": "verbose"}`)
+				Expect(err).To(HaveOccurred())
+			})
+		})
+	})
+
+	Describe("HasConfigSchema", func() {
+		It("returns false when config is nil", func() {
+			manifest := &Manifest{
+				Name:    "test",
+				Author:  "test",
+				Version: "1.0.0",
+			}
+			Expect(manifest.HasConfigSchema()).To(BeFalse())
+		})
+
+		It("returns false when schema is nil", func() {
+			manifest := &Manifest{
+				Name:    "test",
+				Author:  "test",
+				Version: "1.0.0",
+				Config:  &ConfigDefinition{},
+			}
+			Expect(manifest.HasConfigSchema()).To(BeFalse())
+		})
+
+		It("returns true when schema is present", func() {
+			manifest := &Manifest{
+				Name:    "test",
+				Author:  "test",
+				Version: "1.0.0",
+				Config: &ConfigDefinition{
+					Schema: map[string]any{
+						"type": "object",
+					},
+				},
+			}
+			Expect(manifest.HasConfigSchema()).To(BeTrue())
+		})
+	})
+})

plugins/examples/crypto-ticker/main.go

@@ -25,6 +25,14 @@ const (
 
 	// ID for the reconnection schedule
 	reconnectScheduleID = "crypto-ticker-reconnect"
+
+	// Config keys (must match manifest.json schema property names)
+	symbolsKey        = "symbols"
+	reconnectDelayKey = "reconnectDelay"
+	logPricesKey      = "logPrices"
+
+	// Default values
+	defaultReconnectDelay = 5
 )
 
 // CoinbaseSubscription message structure
@@ -74,36 +82,67 @@ var (
 func (p *cryptoTickerPlugin) OnInit() error {
 	pdk.Log(pdk.LogInfo, "Crypto Ticker Plugin initializing...")
 
-	// Get ticker configuration
-	tickerConfig, ok := pdk.GetConfig("tickers")
-	if !ok || tickerConfig == "" {
-		tickerConfig = "BTC,ETH" // Default tickers
-	}
-
-	tickers := parseTickerSymbols(tickerConfig)
-	pdk.Log(pdk.LogInfo, fmt.Sprintf("Configured tickers: %v", tickers))
+	// Get ticker configuration from JSON schema config
+	symbols := getSymbols()
+	pdk.Log(pdk.LogInfo, fmt.Sprintf("Configured symbols: %v", symbols))
 
 	// Connect to WebSocket
 	// Errors won't fail init - reconnect logic will handle it
-	return connectAndSubscribe(tickers)
+	return connectAndSubscribe(symbols)
 }
 
-// parseTickerSymbols parses a comma-separated list of ticker symbols
-func parseTickerSymbols(tickerConfig string) []string {
-	parts := strings.Split(tickerConfig, ",")
-	tickers := make([]string, 0, len(parts))
-	for _, ticker := range parts {
-		ticker = strings.TrimSpace(ticker)
-		if ticker == "" {
-			continue
-		}
-		// Add -USD suffix if not present
-		if !strings.Contains(ticker, "-") {
-			ticker = ticker + "-USD"
-		}
-		tickers = append(tickers, ticker)
+// getSymbols reads the symbols array from config
+func getSymbols() []string {
+	defaultSymbols := []string{"BTC-USD"}
+	symbolsJSON, ok := pdk.GetConfig(symbolsKey)
+	if !ok || symbolsJSON == "" {
+		return defaultSymbols
 	}
-	return tickers
+
+	var symbols []string
+	if err := json.Unmarshal([]byte(symbolsJSON), &symbols); err != nil {
+		pdk.Log(pdk.LogWarn, fmt.Sprintf("failed to parse symbols config: %v, using defaults", err))
+		return defaultSymbols
+	}
+
+	if len(symbols) == 0 {
+		return defaultSymbols
+	}
+
+	// Normalize symbols - add -USD suffix if not present
+	for i, s := range symbols {
+		s = strings.TrimSpace(s)
+		if !strings.Contains(s, "-") {
+			symbols[i] = s + "-USD"
+		} else {
+			symbols[i] = s
+		}
+	}
+
+	return symbols
+}
+
+// getReconnectDelay reads the reconnect delay from config
+func getReconnectDelay() int32 {
+	delayStr, ok := pdk.GetConfig(reconnectDelayKey)
+	if !ok || delayStr == "" {
+		return defaultReconnectDelay
+	}
+
+	var delay int
+	if _, err := fmt.Sscanf(delayStr, "%d", &delay); err != nil || delay < 1 {
+		return defaultReconnectDelay
+	}
+	return int32(delay)
+}
+
+// shouldLogPrices reads the logPrices setting from config
+func shouldLogPrices() bool {
+	logStr, ok := pdk.GetConfig(logPricesKey)
+	if !ok || logStr == "" {
+		return false
+	}
+	return logStr == "true"
 }
 
 // connectAndSubscribe connects to Coinbase WebSocket and subscribes to tickers
@@ -164,14 +203,16 @@ func (p *cryptoTickerPlugin) OnTextMessage(input websocket.OnTextMessageRequest)
 	// Calculate 24h change percentage
 	change := calculatePercentChange(ticker.Open24h, ticker.Price)
 
-	// Log ticker information
-	pdk.Log(pdk.LogInfo, fmt.Sprintf("💰 %s: $%s (24h: %s%%) Bid: $%s Ask: $%s",
-		ticker.ProductID,
-		ticker.Price,
-		change,
-		ticker.BestBid,
-		ticker.BestAsk,
-	))
+	// Log ticker information (only if enabled in config)
+	if shouldLogPrices() {
+		pdk.Log(pdk.LogInfo, fmt.Sprintf("💰 %s: $%s (24h: %s%%) Bid: $%s Ask: $%s",
+			ticker.ProductID,
+			ticker.Price,
+			change,
+			ticker.BestBid,
+			ticker.BestAsk,
+		))
+	}
 
 	return nil
 }
@@ -196,10 +237,11 @@ func (p *cryptoTickerPlugin) OnClose(input websocket.OnCloseRequest) error {
 
 	// Only attempt reconnect for our connection
 	if input.ConnectionID == connectionID {
-		pdk.Log(pdk.LogInfo, "Scheduling reconnection attempt in 5 seconds...")
+		delay := getReconnectDelay()
+		pdk.Log(pdk.LogInfo, fmt.Sprintf("Scheduling reconnection attempt in %d seconds...", delay))
 
 		// Schedule a one-time reconnection attempt
-		_, err := host.SchedulerScheduleOneTime(5, "reconnect", reconnectScheduleID)
+		_, err := host.SchedulerScheduleOneTime(delay, "reconnect", reconnectScheduleID)
 		if err != nil {
 			pdk.Log(pdk.LogError, fmt.Sprintf("Failed to schedule reconnection: %v", err))
 		}
@@ -218,20 +260,16 @@ func (p *cryptoTickerPlugin) OnCallback(input scheduler.SchedulerCallbackRequest
 	pdk.Log(pdk.LogInfo, "Attempting to reconnect to Coinbase WebSocket API...")
 
 	// Get ticker configuration
-	tickerConfig, ok := pdk.GetConfig("tickers")
-	if !ok || tickerConfig == "" {
-		tickerConfig = "BTC,ETH"
-	}
-
-	tickers := parseTickerSymbols(tickerConfig)
+	symbols := getSymbols()
 
 	// Try to connect and subscribe
-	err := connectAndSubscribe(tickers)
+	err := connectAndSubscribe(symbols)
 	if err != nil {
-		pdk.Log(pdk.LogError, fmt.Sprintf("Reconnection failed: %v - will retry in 10 seconds", err))
+		delay := getReconnectDelay() * 2 // Double delay on failure
+		pdk.Log(pdk.LogError, fmt.Sprintf("Reconnection failed: %v - will retry in %d seconds", err, delay))
 
 		// Schedule another attempt
-		_, err := host.SchedulerScheduleOneTime(10, "reconnect", reconnectScheduleID)
+		_, err := host.SchedulerScheduleOneTime(delay, "reconnect", reconnectScheduleID)
 		if err != nil {
 			pdk.Log(pdk.LogError, fmt.Sprintf("Failed to schedule retry: %v", err))
 		}

plugins/examples/crypto-ticker/manifest.json

@@ -4,6 +4,61 @@
   "version": "1.0.0",
   "description": "Real-time cryptocurrency price ticker using Coinbase WebSocket API",
   "website": "https://github.com/navidrome/navidrome/tree/master/plugins/examples/crypto-ticker",
+  "config": {
+    "schema": {
+      "type": "object",
+      "properties": {
+        "symbols": {
+          "type": "array",
+          "title": "Trading Pairs",
+          "description": "Cryptocurrency trading pairs to track (default: BTC-USD)",
+          "items": {
+            "type": "string",
+            "title": "Trading Pair",
+            "pattern": "^[A-Z]{3,5}-[A-Z]{3,5}$",
+            "description": "Trading pair in the format BASE-QUOTE (e.g., BTC-USD, ETH-USD)"
+          },
+          "default": ["BTC-USD"]
+        },
+        "reconnectDelay": {
+          "type": "integer",
+          "title": "Reconnect Delay",
+          "description": "Delay in seconds before attempting to reconnect after connection loss",
+          "default": 5,
+          "minimum": 1,
+          "maximum": 60
+        },
+        "logPrices": {
+          "type": "boolean",
+          "title": "Log Prices",
+          "description": "Whether to log price updates to the server log",
+          "default": false
+        }
+      }
+    },
+    "uiSchema": {
+      "type": "VerticalLayout",
+      "elements": [
+        {
+          "type": "Control",
+          "scope": "#/properties/symbols"
+        },
+        {
+          "type": "HorizontalLayout",
+          "elements": [
+            {
+              "type": "Control",
+              "scope": "#/properties/reconnectDelay"
+            },
+            {
+              "type": "Control",
+              "scope": "#/properties/logPrices"
+            }
+          ]
+        }
+      ]
+    }
+  },
   "permissions": {
     "config": {
       "reason": "To read ticker symbols configuration"

plugins/examples/discord-rich-presence-rs/manifest.json

@@ -25,5 +25,74 @@
     "artwork": {
       "reason": "To get track artwork URLs for rich presence display"
     }
+  },
+  "config": {
+    "schema": {
+      "type": "object",
+      "properties": {
+        "clientid": {
+          "type": "string",
+          "title": "Discord Application Client ID",
+          "description": "The Client ID from your Discord Developer Application. Create one at https://discord.com/developers/applications",
+          "minLength": 17,
+          "maxLength": 20,
+          "pattern": "^[0-9]+$"
+        },
+        "users": {
+          "type": "array",
+          "title": "User Tokens",
+          "description": "Discord tokens for each Navidrome user. WARNING: Store tokens securely!",
+          "default": [{}],
+          "items": {
+            "type": "object",
+            "properties": {
+              "username": {
+                "type": "string",
+                "title": "Navidrome Username",
+                "description": "The Navidrome username to associate with this Discord token",
+                "minLength": 1
+              },
+              "token": {
+                "type": "string",
+                "title": "Discord Token",
+                "description": "The user's Discord token (keep this secret!)",
+                "minLength": 1
+              }
+            },
+            "required": ["username", "token"]
+          }
+        }
+      },
+      "required": ["clientid"]
+    },
+    "uiSchema": {
+      "type": "VerticalLayout",
+      "elements": [
+        {
+          "type": "Control",
+          "scope": "#/properties/clientid"
+        },
+        {
+          "type": "Control",
+          "scope": "#/properties/users",
+          "options": {
+            "elementLabelProp": "username",
+            "detail": {
+              "type": "HorizontalLayout",
+              "elements": [
+                {
+                  "type": "Control",
+                  "scope": "#/properties/username"
+                },
+                {
+                  "type": "Control",
+                  "scope": "#/properties/token"
+                }
+              ]
+            }
+          }
+        }
+      ]
+    }
   }
 }

plugins/examples/discord-rich-presence-rs/src/lib.rs

@@ -8,12 +8,9 @@
 //!
 //! ## Configuration
 //!
-//! ```toml
-//! [PluginConfig.discord-rich-presence-rs]
-//! clientid = "YOUR_DISCORD_APPLICATION_ID"
-//! "user.username1" = "discord_token1"
-//! "user.username2" = "discord_token2"
-//! ```
+//! Configure this plugin through the Navidrome UI with:
+//! - Discord Application Client ID
+//! - User tokens array mapping Navidrome usernames to Discord tokens
 //!
 //! **WARNING**: This plugin is for demonstration purposes only. Storing Discord tokens
 //! in configuration files is not secure and may violate Discord's terms of service.
@@ -32,6 +29,7 @@ use nd_pdk::websocket::{
     OnBinaryMessageRequest, OnCloseRequest, OnErrorRequest, OnTextMessageRequest,
     TextMessageProvider,
 };
+use serde::Deserialize;
 
 mod rpc;
 
@@ -48,7 +46,7 @@ nd_pdk::register_websocket_close!(DiscordPlugin);
 // ============================================================================
 
 const CLIENT_ID_KEY: &str = "clientid";
-const USER_KEY_PREFIX: &str = "user.";
+const USERS_KEY: &str = "users";
 const PAYLOAD_HEARTBEAT: &str = "heartbeat";
 const PAYLOAD_CLEAR_ACTIVITY: &str = "clear-activity";
 
@@ -64,19 +62,31 @@ struct DiscordPlugin;
 // Configuration
 // ============================================================================
 
+/// User token entry from the config schema
+#[derive(Debug, Deserialize)]
+struct UserToken {
+    username: String,
+    token: String,
+}
+
 fn get_config() -> Result<(String, std::collections::HashMap<String, String>), Error> {
     let client_id = config::get(CLIENT_ID_KEY)?
         .filter(|s| !s.is_empty())
         .ok_or_else(|| Error::msg("missing clientid in configuration"))?;
 
-    // Get all user keys with the "user." prefix
-    let user_keys = config::keys(USER_KEY_PREFIX)?;
-
+    // Get users array from config (JSON format)
+    let users_json = config::get(USERS_KEY)?.unwrap_or_default();
+    
     let mut users = std::collections::HashMap::new();
-    for key in user_keys {
-        let username = key.strip_prefix(USER_KEY_PREFIX).unwrap_or(&key);
-        if let Some(token) = config::get(&key)?.filter(|s| !s.is_empty()) {
-            users.insert(username.to_string(), token);
+    if !users_json.is_empty() {
+        // Parse JSON array of user tokens
+        let user_tokens: Vec<UserToken> = serde_json::from_str(&users_json)
+            .map_err(|e| Error::msg(format!("failed to parse users config: {}", e)))?;
+        
+        for user_token in user_tokens {
+            if !user_token.username.is_empty() && !user_token.token.is_empty() {
+                users.insert(user_token.username, user_token.token);
+            }
         }
     }
 

plugins/examples/discord-rich-presence/main.go

@@ -11,6 +11,7 @@
 package main
 
 import (
+	"encoding/json"
 	"fmt"
 	"strings"
 	"time"
@@ -24,10 +25,16 @@ import (
 
 // Configuration keys
 const (
-	clientIDKey   = "clientid"
-	userKeyPrefix = "user."
+	clientIDKey = "clientid"
+	usersKey    = "users"
 )
 
+// userToken represents a user-token mapping from the config
+type userToken struct {
+	Username string `json:"username"`
+	Token    string `json:"token"`
+}
+
 // discordPlugin implements the scrobbler and scheduler interfaces.
 type discordPlugin struct{}
 
@@ -49,24 +56,35 @@ func getConfig() (clientID string, users map[string]string, err error) {
 		return "", nil, nil
 	}
 
-	// Get all user keys with the "user." prefix
-	userKeys := host.ConfigKeys(userKeyPrefix)
-	if len(userKeys) == 0 {
+	// Get the users array from config
+	usersJSON, ok := pdk.GetConfig(usersKey)
+	if !ok || usersJSON == "" {
 		pdk.Log(pdk.LogWarn, "no users configured")
 		return clientID, nil, nil
 	}
 
+	// Parse the JSON array
+	var userTokens []userToken
+	if err := json.Unmarshal([]byte(usersJSON), &userTokens); err != nil {
+		pdk.Log(pdk.LogError, fmt.Sprintf("failed to parse users config: %v", err))
+		return clientID, nil, nil
+	}
+
+	if len(userTokens) == 0 {
+		pdk.Log(pdk.LogWarn, "no users configured")
+		return clientID, nil, nil
+	}
+
+	// Build the users map
 	users = make(map[string]string)
-	for _, key := range userKeys {
-		username := strings.TrimPrefix(key, userKeyPrefix)
-		token, exists := host.ConfigGet(key)
-		if exists && token != "" {
-			users[username] = token
+	for _, ut := range userTokens {
+		if ut.Username != "" && ut.Token != "" {
+			users[ut.Username] = ut.Token
 		}
 	}
 
 	if len(users) == 0 {
-		pdk.Log(pdk.LogWarn, "no users configured")
+		pdk.Log(pdk.LogWarn, "no valid users configured")
 		return clientID, nil, nil
 	}
 

plugins/examples/discord-rich-presence/manifest.json

@@ -29,5 +29,74 @@
     "artwork": {
       "reason": "To get track artwork URLs for rich presence display"
     }
+  },
+  "config": {
+    "schema": {
+      "type": "object",
+      "properties": {
+        "clientid": {
+          "type": "string",
+          "title": "Discord Application Client ID",
+          "description": "The Client ID from your Discord Developer Application. Create one at https://discord.com/developers/applications",
+          "minLength": 17,
+          "maxLength": 20,
+          "pattern": "^[0-9]+$"
+        },
+        "users": {
+          "type": "array",
+          "title": "User Tokens",
+          "description": "Discord tokens for each Navidrome user. WARNING: Store tokens securely!",
+          "default": [{}],
+          "items": {
+            "type": "object",
+            "properties": {
+              "username": {
+                "type": "string",
+                "title": "Navidrome Username",
+                "description": "The Navidrome username to associate with this Discord token",
+                "minLength": 1
+              },
+              "token": {
+                "type": "string",
+                "title": "Discord Token",
+                "description": "The user's Discord token (keep this secret!)",
+                "minLength": 1
+              }
+            },
+            "required": ["username", "token"]
+          }
+        }
+      },
+      "required": ["clientid"]
+    },
+    "uiSchema": {
+      "type": "VerticalLayout",
+      "elements": [
+        {
+          "type": "Control",
+          "scope": "#/properties/clientid"
+        },
+        {
+          "type": "Control",
+          "scope": "#/properties/users",
+          "options": {
+            "elementLabelProp": "username",
+            "detail": {
+              "type": "HorizontalLayout",
+              "elements": [
+                {
+                  "type": "Control",
+                  "scope": "#/properties/username"
+                },
+                {
+                  "type": "Control",
+                  "scope": "#/properties/token"
+                }
+              ]
+            }
+          }
+        }
+      ]
+    }
   }
 }

plugins/host_config_test.go

@@ -20,6 +20,105 @@ import (
 	. "github.com/onsi/gomega"
 )
 
+// testConfigInput is the input for nd_test_config callback.
+type testConfigInput struct {
+	Operation string `json:"operation"`
+	Key       string `json:"key,omitempty"`
+	Prefix    string `json:"prefix,omitempty"`
+}
+
+// testConfigOutput is the output from nd_test_config callback.
+type testConfigOutput struct {
+	StringVal string   `json:"string_val,omitempty"`
+	IntVal    int64    `json:"int_val,omitempty"`
+	Keys      []string `json:"keys,omitempty"`
+	Exists    bool     `json:"exists,omitempty"`
+	Error     *string  `json:"error,omitempty"`
+}
+
+// setupTestConfigPlugin sets up a test environment with the test-config plugin loaded.
+// Returns a cleanup function and a helper to call the plugin's nd_test_config function.
+func setupTestConfigPlugin(configJSON string) (*Manager, func(context.Context, testConfigInput) (*testConfigOutput, error)) {
+	tmpDir, err := os.MkdirTemp("", "config-test-*")
+	Expect(err).ToNot(HaveOccurred())
+
+	// Copy the test-config plugin
+	srcPath := filepath.Join(testdataDir, "test-config"+PackageExtension)
+	destPath := filepath.Join(tmpDir, "test-config"+PackageExtension)
+	data, err := os.ReadFile(srcPath)
+	Expect(err).ToNot(HaveOccurred())
+	err = os.WriteFile(destPath, data, 0600)
+	Expect(err).ToNot(HaveOccurred())
+
+	// Compute SHA256 for the plugin
+	hash := sha256.Sum256(data)
+	hashHex := hex.EncodeToString(hash[:])
+
+	// Setup config
+	DeferCleanup(configtest.SetupConfig())
+	conf.Server.Plugins.Enabled = true
+	conf.Server.Plugins.Folder = tmpDir
+	conf.Server.Plugins.AutoReload = false
+	conf.Server.CacheFolder = filepath.Join(tmpDir, "cache")
+
+	// Setup mock DataStore
+	mockPluginRepo := tests.CreateMockPluginRepo()
+	mockPluginRepo.Permitted = true
+	mockPluginRepo.SetData(model.Plugins{{
+		ID:       "test-config",
+		Path:     destPath,
+		SHA256:   hashHex,
+		Enabled:  true,
+		AllUsers: true,
+		Config:   configJSON,
+	}})
+	dataStore := &tests.MockDataStore{MockedPlugin: mockPluginRepo}
+
+	// Create and start manager
+	manager := &Manager{
+		plugins:        make(map[string]*plugin),
+		ds:             dataStore,
+		subsonicRouter: http.NotFoundHandler(),
+	}
+	err = manager.Start(GinkgoT().Context())
+	Expect(err).ToNot(HaveOccurred())
+
+	DeferCleanup(func() {
+		_ = manager.Stop()
+		_ = os.RemoveAll(tmpDir)
+	})
+
+	// Helper to call test plugin's exported function
+	callTestConfig := func(ctx context.Context, input testConfigInput) (*testConfigOutput, error) {
+		manager.mu.RLock()
+		p := manager.plugins["test-config"]
+		manager.mu.RUnlock()
+
+		instance, err := p.instance(ctx)
+		if err != nil {
+			return nil, err
+		}
+		defer instance.Close(ctx)
+
+		inputBytes, _ := json.Marshal(input)
+		_, outputBytes, err := instance.Call("nd_test_config", inputBytes)
+		if err != nil {
+			return nil, err
+		}
+
+		var output testConfigOutput
+		if err := json.Unmarshal(outputBytes, &output); err != nil {
+			return nil, err
+		}
+		if output.Error != nil {
+			return nil, errors.New(*output.Error)
+		}
+		return &output, nil
+	}
+
+	return manager, callTestConfig
+}
+
 var _ = Describe("ConfigService", func() {
 	var service *configServiceImpl
 	var ctx context.Context
@@ -144,59 +243,12 @@ var _ = Describe("ConfigService", func() {
 
 var _ = Describe("ConfigService Integration", Ordered, func() {
 	var (
-		manager *Manager
-		tmpDir  string
+		manager        *Manager
+		callTestConfig func(context.Context, testConfigInput) (*testConfigOutput, error)
 	)
 
 	BeforeAll(func() {
-		var err error
-		tmpDir, err = os.MkdirTemp("", "config-test-*")
-		Expect(err).ToNot(HaveOccurred())
-
-		// Copy the test-config plugin
-		srcPath := filepath.Join(testdataDir, "test-config"+PackageExtension)
-		destPath := filepath.Join(tmpDir, "test-config"+PackageExtension)
-		data, err := os.ReadFile(srcPath)
-		Expect(err).ToNot(HaveOccurred())
-		err = os.WriteFile(destPath, data, 0600)
-		Expect(err).ToNot(HaveOccurred())
-
-		// Compute SHA256 for the plugin
-		hash := sha256.Sum256(data)
-		hashHex := hex.EncodeToString(hash[:])
-
-		// Setup config
-		DeferCleanup(configtest.SetupConfig())
-		conf.Server.Plugins.Enabled = true
-		conf.Server.Plugins.Folder = tmpDir
-		conf.Server.Plugins.AutoReload = false
-		conf.Server.CacheFolder = filepath.Join(tmpDir, "cache")
-
-		// Setup mock DataStore with pre-enabled plugin and config
-		mockPluginRepo := tests.CreateMockPluginRepo()
-		mockPluginRepo.Permitted = true
-		mockPluginRepo.SetData(model.Plugins{{
-			ID:      "test-config",
-			Path:    destPath,
-			SHA256:  hashHex,
-			Enabled: true,
-			Config:  `{"api_key":"test_secret","max_retries":"5","timeout":"30"}`,
-		}})
-		dataStore := &tests.MockDataStore{MockedPlugin: mockPluginRepo}
-
-		// Create and start manager
-		manager = &Manager{
-			plugins:        make(map[string]*plugin),
-			ds:             dataStore,
-			subsonicRouter: http.NotFoundHandler(),
-		}
-		err = manager.Start(GinkgoT().Context())
-		Expect(err).ToNot(HaveOccurred())
-
-		DeferCleanup(func() {
-			_ = manager.Stop()
-			_ = os.RemoveAll(tmpDir)
-		})
+		manager, callTestConfig = setupTestConfigPlugin(`{"api_key":"test_secret","max_retries":"5","timeout":"30"}`)
 	})
 
 	Describe("Plugin Loading", func() {
@@ -205,54 +257,11 @@ var _ = Describe("ConfigService Integration", Ordered, func() {
 			p, ok := manager.plugins["test-config"]
 			manager.mu.RUnlock()
 			Expect(ok).To(BeTrue())
-			// Config service doesn't require permission, so Permissions can be nil
-			// Just verify the plugin loaded
 			Expect(p.manifest.Name).To(Equal("Test Config Plugin"))
 		})
 	})
 
 	Describe("Config Operations via Plugin", func() {
-		type testConfigInput struct {
-			Operation string `json:"operation"`
-			Key       string `json:"key,omitempty"`
-			Prefix    string `json:"prefix,omitempty"`
-		}
-		type testConfigOutput struct {
-			StringVal string   `json:"string_val,omitempty"`
-			IntVal    int64    `json:"int_val,omitempty"`
-			Keys      []string `json:"keys,omitempty"`
-			Exists    bool     `json:"exists,omitempty"`
-			Error     *string  `json:"error,omitempty"`
-		}
-
-		// Helper to call test plugin's exported function
-		callTestConfig := func(ctx context.Context, input testConfigInput) (*testConfigOutput, error) {
-			manager.mu.RLock()
-			p := manager.plugins["test-config"]
-			manager.mu.RUnlock()
-
-			instance, err := p.instance(ctx)
-			if err != nil {
-				return nil, err
-			}
-			defer instance.Close(ctx)
-
-			inputBytes, _ := json.Marshal(input)
-			_, outputBytes, err := instance.Call("nd_test_config", inputBytes)
-			if err != nil {
-				return nil, err
-			}
-
-			var output testConfigOutput
-			if err := json.Unmarshal(outputBytes, &output); err != nil {
-				return nil, err
-			}
-			if output.Error != nil {
-				return nil, errors.New(*output.Error)
-			}
-			return &output, nil
-		}
-
 		It("should get string value", func() {
 			output, err := callTestConfig(GinkgoT().Context(), testConfigInput{
 				Operation: "get",
@@ -285,7 +294,7 @@ var _ = Describe("ConfigService Integration", Ordered, func() {
 		It("should return not exists for non-integer value", func() {
 			output, err := callTestConfig(GinkgoT().Context(), testConfigInput{
 				Operation: "get_int",
-				Key:       "api_key", // This is a string, not an integer
+				Key:       "api_key",
 			})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(output.Exists).To(BeFalse())
@@ -310,3 +319,64 @@ var _ = Describe("ConfigService Integration", Ordered, func() {
 		})
 	})
 })
+
+var _ = Describe("Complex Config Values Integration", Ordered, func() {
+	var callTestConfig func(context.Context, testConfigInput) (*testConfigOutput, error)
+
+	BeforeAll(func() {
+		// Config with arrays and objects - these should be properly serialized as JSON strings
+		_, callTestConfig = setupTestConfigPlugin(`{"api_key":"secret123","users":[{"username":"admin","token":"tok1"},{"username":"user2","token":"tok2"}],"settings":{"enabled":true,"count":5}}`)
+	})
+
+	Describe("Config Serialization", func() {
+		It("should make simple string config values accessible to plugin", func() {
+			output, err := callTestConfig(GinkgoT().Context(), testConfigInput{
+				Operation: "get",
+				Key:       "api_key",
+			})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(output.Exists).To(BeTrue())
+			Expect(output.StringVal).To(Equal("secret123"))
+		})
+
+		It("should serialize array config values as JSON strings", func() {
+			output, err := callTestConfig(GinkgoT().Context(), testConfigInput{
+				Operation: "get",
+				Key:       "users",
+			})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(output.Exists).To(BeTrue())
+			// Array values are serialized as JSON strings - parse to verify structure
+			var users []map[string]string
+			Expect(json.Unmarshal([]byte(output.StringVal), &users)).To(Succeed())
+			Expect(users).To(HaveLen(2))
+			Expect(users[0]).To(HaveKeyWithValue("username", "admin"))
+			Expect(users[0]).To(HaveKeyWithValue("token", "tok1"))
+			Expect(users[1]).To(HaveKeyWithValue("username", "user2"))
+			Expect(users[1]).To(HaveKeyWithValue("token", "tok2"))
+		})
+
+		It("should serialize object config values as JSON strings", func() {
+			output, err := callTestConfig(GinkgoT().Context(), testConfigInput{
+				Operation: "get",
+				Key:       "settings",
+			})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(output.Exists).To(BeTrue())
+			// Object values are serialized as JSON strings - parse to verify structure
+			var settings map[string]any
+			Expect(json.Unmarshal([]byte(output.StringVal), &settings)).To(Succeed())
+			Expect(settings).To(HaveKeyWithValue("enabled", true))
+			Expect(settings).To(HaveKeyWithValue("count", float64(5)))
+		})
+
+		It("should list all config keys including complex values", func() {
+			output, err := callTestConfig(GinkgoT().Context(), testConfigInput{
+				Operation: "list",
+				Prefix:    "",
+			})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(output.Keys).To(ConsistOf("api_key", "users", "settings"))
+		})
+	})
+})

plugins/manager.go

@@ -381,6 +381,30 @@ func (m *Manager) DisablePlugin(ctx context.Context, id string) error {
 	return nil
 }
 
+// ValidatePluginConfig validates a config JSON string against the plugin's config schema.
+// If the plugin has no config schema defined, it returns an error.
+// Returns nil if validation passes, or an error describing the validation failure.
+func (m *Manager) ValidatePluginConfig(ctx context.Context, id, configJSON string) error {
+	if m.ds == nil {
+		return fmt.Errorf("datastore not configured")
+	}
+
+	adminCtx := adminContext(ctx)
+	repo := m.ds.Plugin(adminCtx)
+
+	plugin, err := repo.Get(id)
+	if err != nil {
+		return fmt.Errorf("getting plugin from DB: %w", err)
+	}
+
+	manifest, err := readManifest(plugin.Path)
+	if err != nil {
+		return fmt.Errorf("reading manifest: %w", err)
+	}
+
+	return ValidateConfig(manifest, configJSON)
+}
+
 // UpdatePluginConfig updates the configuration for a plugin.
 // If the plugin is enabled, it will be reloaded with the new config.
 func (m *Manager) UpdatePluginConfig(ctx context.Context, id, configJSON string) error {

plugins/manager_loader.go

@@ -230,11 +230,9 @@ func (m *Manager) loadPluginWithConfig(p *model.Plugin) error {
 	}
 
 	// Parse config from JSON
-	var pluginConfig map[string]string
-	if p.Config != "" {
-		if err := json.Unmarshal([]byte(p.Config), &pluginConfig); err != nil {
-			return fmt.Errorf("parsing plugin config: %w", err)
-		}
+	pluginConfig, err := parsePluginConfig(p.Config)
+	if err != nil {
+		return err
 	}
 
 	// Parse users from JSON
@@ -379,3 +377,30 @@ func (m *Manager) loadPluginWithConfig(p *model.Plugin) error {
 
 	return nil
 }
+
+// parsePluginConfig parses a JSON config string into a map of string values.
+// For Extism, all config values must be strings, so non-string values are serialized as JSON.
+func parsePluginConfig(configJSON string) (map[string]string, error) {
+	if configJSON == "" {
+		return nil, nil
+	}
+	var rawConfig map[string]any
+	if err := json.Unmarshal([]byte(configJSON), &rawConfig); err != nil {
+		return nil, fmt.Errorf("parsing plugin config: %w", err)
+	}
+	pluginConfig := make(map[string]string)
+	for key, value := range rawConfig {
+		switch v := value.(type) {
+		case string:
+			pluginConfig[key] = v
+		default:
+			// Serialize non-string values as JSON
+			jsonBytes, err := json.Marshal(v)
+			if err != nil {
+				return nil, fmt.Errorf("serializing config value %q: %w", key, err)
+			}
+			pluginConfig[key] = string(jsonBytes)
+		}
+	}
+	return pluginConfig, nil
+}

plugins/manager_loader_test.go

@@ -0,0 +1,60 @@
+//go:build !windows
+
+package plugins
+
+import (
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("parsePluginConfig", func() {
+	It("returns nil for empty string", func() {
+		result, err := parsePluginConfig("")
+		Expect(err).ToNot(HaveOccurred())
+		Expect(result).To(BeNil())
+	})
+
+	It("serializes object values as JSON strings", func() {
+		result, err := parsePluginConfig(`{"settings": {"enabled": true, "count": 5}}`)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(result).To(HaveLen(1))
+		Expect(result["settings"]).To(Equal(`{"count":5,"enabled":true}`))
+	})
+
+	It("handles mixed value types", func() {
+		result, err := parsePluginConfig(`{"api_key": "secret", "timeout": 30, "rate": 1.5, "enabled": true, "tags": ["a", "b"]}`)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(result).To(HaveLen(5))
+		Expect(result["api_key"]).To(Equal("secret"))
+		Expect(result["timeout"]).To(Equal("30"))
+		Expect(result["rate"]).To(Equal("1.5"))
+		Expect(result["enabled"]).To(Equal("true"))
+		Expect(result["tags"]).To(Equal(`["a","b"]`))
+	})
+
+	It("returns error for invalid JSON", func() {
+		_, err := parsePluginConfig(`{invalid json}`)
+		Expect(err).To(HaveOccurred())
+		Expect(err.Error()).To(ContainSubstring("parsing plugin config"))
+	})
+
+	It("returns error for non-object JSON", func() {
+		_, err := parsePluginConfig(`["array", "not", "object"]`)
+		Expect(err).To(HaveOccurred())
+		Expect(err.Error()).To(ContainSubstring("parsing plugin config"))
+	})
+
+	It("handles null values", func() {
+		result, err := parsePluginConfig(`{"key": null}`)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(result).To(HaveLen(1))
+		Expect(result["key"]).To(Equal("null"))
+	})
+
+	It("handles empty object", func() {
+		result, err := parsePluginConfig(`{}`)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(result).To(HaveLen(0))
+		Expect(result).ToNot(BeNil())
+	})
+})

plugins/manifest-schema.json

@@ -36,9 +36,28 @@
     },
     "experimental": {
       "$ref": "#/$defs/Experimental"
+    },
+    "config": {
+      "$ref": "#/$defs/ConfigDefinition"
     }
   },
   "$defs": {
+    "ConfigDefinition": {
+      "type": "object",
+      "description": "Configuration schema for the plugin using JSON Schema (draft-07) and optional JSONForms UI Schema",
+      "additionalProperties": false,
+      "required": ["schema"],
+      "properties": {
+        "schema": {
+          "type": "object",
+          "description": "JSON Schema (draft-07) defining the plugin's configuration options"
+        },
+        "uiSchema": {
+          "type": "object",
+          "description": "Optional JSONForms UI Schema for customizing form layout"
+        }
+      }
+    },
     "Experimental": {
       "type": "object",
       "description": "Experimental features that may change or be removed in future versions",

plugins/manifest.go

@@ -3,6 +3,8 @@ package plugins
 import (
 	"encoding/json"
 	"fmt"
+
+	"github.com/santhosh-tekuri/jsonschema/v6"
 )
 
 //go:generate go tool go-jsonschema -p plugins --struct-name-from-title -o manifest_gen.go manifest-schema.json
@@ -29,6 +31,26 @@ func (m *Manifest) Validate() error {
 			return fmt.Errorf("'subsonicapi' permission requires 'users' permission to be declared")
 		}
 	}
+
+	// Validate config schema if present
+	if m.Config != nil && m.Config.Schema != nil {
+		if err := validateConfigSchema(m.Config.Schema); err != nil {
+			return fmt.Errorf("invalid config schema: %w", err)
+		}
+	}
+
+	return nil
+}
+
+// validateConfigSchema validates that the schema is a valid JSON Schema that can be compiled.
+func validateConfigSchema(schema map[string]any) error {
+	compiler := jsonschema.NewCompiler()
+	if err := compiler.AddResource("schema.json", schema); err != nil {
+		return fmt.Errorf("invalid schema structure: %w", err)
+	}
+	if _, err := compiler.Compile("schema.json"); err != nil {
+		return err
+	}
 	return nil
 }
 

plugins/manifest_gen.go

@@ -17,6 +17,34 @@ type CachePermission struct {
 	Reason *string `json:"reason,omitempty" yaml:"reason,omitempty" mapstructure:"reason,omitempty"`
 }
 
+// Configuration schema for the plugin using JSON Schema (draft-07) and optional
+// JSONForms UI Schema
+type ConfigDefinition struct {
+	// JSON Schema (draft-07) defining the plugin's configuration options
+	Schema map[string]interface{} `json:"schema" yaml:"schema" mapstructure:"schema"`
+
+	// Optional JSONForms UI Schema for customizing form layout
+	UiSchema map[string]interface{} `json:"uiSchema,omitempty" yaml:"uiSchema,omitempty" mapstructure:"uiSchema,omitempty"`
+}
+
+// UnmarshalJSON implements json.Unmarshaler.
+func (j *ConfigDefinition) UnmarshalJSON(value []byte) error {
+	var raw map[string]interface{}
+	if err := json.Unmarshal(value, &raw); err != nil {
+		return err
+	}
+	if _, ok := raw["schema"]; raw != nil && !ok {
+		return fmt.Errorf("field schema in ConfigDefinition: required")
+	}
+	type Plain ConfigDefinition
+	var plain Plain
+	if err := json.Unmarshal(value, &plain); err != nil {
+		return err
+	}
+	*j = ConfigDefinition(plain)
+	return nil
+}
+
 // Configuration access permissions for a plugin
 type ConfigPermission struct {
 	// Explanation for why config access is needed
@@ -81,6 +109,9 @@ type Manifest struct {
 	// The author of the plugin
 	Author string `json:"author" yaml:"author" mapstructure:"author"`
 
+	// Config corresponds to the JSON schema field "config".
+	Config *ConfigDefinition `json:"config,omitempty" yaml:"config,omitempty" mapstructure:"config,omitempty"`
+
 	// A brief description of what the plugin does
 	Description *string `json:"description,omitempty" yaml:"description,omitempty" mapstructure:"description,omitempty"`
 

plugins/manifest_test.go

@@ -286,6 +286,107 @@ var _ = Describe("Manifest", func() {
 			err := m.Validate()
 			Expect(err).ToNot(HaveOccurred())
 		})
+
+		It("validates manifest with valid config schema", func() {
+			m := &Manifest{
+				Name:    "Test",
+				Author:  "Author",
+				Version: "1.0.0",
+				Config: &ConfigDefinition{
+					Schema: map[string]any{
+						"type": "object",
+						"properties": map[string]any{
+							"api_key": map[string]any{
+								"type": "string",
+							},
+						},
+					},
+				},
+			}
+
+			err := m.Validate()
+			Expect(err).ToNot(HaveOccurred())
+		})
+
+		It("validates manifest with complex config schema", func() {
+			m := &Manifest{
+				Name:    "Test",
+				Author:  "Author",
+				Version: "1.0.0",
+				Config: &ConfigDefinition{
+					Schema: map[string]any{
+						"type": "object",
+						"properties": map[string]any{
+							"users": map[string]any{
+								"type": "array",
+								"items": map[string]any{
+									"type": "object",
+									"properties": map[string]any{
+										"username": map[string]any{"type": "string"},
+										"token":    map[string]any{"type": "string"},
+									},
+									"required": []any{"username", "token"},
+								},
+							},
+						},
+					},
+				},
+			}
+
+			err := m.Validate()
+			Expect(err).ToNot(HaveOccurred())
+		})
+
+		It("returns error for invalid config schema - bad type", func() {
+			m := &Manifest{
+				Name:    "Test",
+				Author:  "Author",
+				Version: "1.0.0",
+				Config: &ConfigDefinition{
+					Schema: map[string]any{
+						"type": "invalid_type",
+					},
+				},
+			}
+
+			err := m.Validate()
+			Expect(err).To(HaveOccurred())
+			Expect(err.Error()).To(ContainSubstring("config schema"))
+		})
+
+		It("returns error for invalid config schema - bad minLength", func() {
+			m := &Manifest{
+				Name:    "Test",
+				Author:  "Author",
+				Version: "1.0.0",
+				Config: &ConfigDefinition{
+					Schema: map[string]any{
+						"type": "object",
+						"properties": map[string]any{
+							"name": map[string]any{
+								"type":      "string",
+								"minLength": "not_a_number",
+							},
+						},
+					},
+				},
+			}
+
+			err := m.Validate()
+			Expect(err).To(HaveOccurred())
+			Expect(err.Error()).To(ContainSubstring("config schema"))
+		})
+
+		It("validates manifest without config", func() {
+			m := &Manifest{
+				Name:    "Test",
+				Author:  "Author",
+				Version: "1.0.0",
+			}
+
+			err := m.Validate()
+			Expect(err).ToNot(HaveOccurred())
+		})
 	})
 
 	Describe("ValidateWithCapabilities", func() {

plugins/testdata/test-config/manifest.json

@@ -2,5 +2,60 @@
   "name": "Test Config Plugin",
   "author": "Navidrome Test",
   "version": "1.0.0",
-  "description": "A test plugin for config service integration testing"
+  "description": "A test plugin for config service integration testing",
+  "config": {
+    "schema": {
+      "type": "object",
+      "properties": {
+        "api_key": {
+          "type": "string",
+          "title": "API Key",
+          "minLength": 1
+        },
+        "max_retries": {
+          "type": "string",
+          "title": "Max Retries"
+        },
+        "timeout": {
+          "type": "string",
+          "title": "Timeout"
+        },
+        "users": {
+          "type": "array",
+          "title": "Users",
+          "items": {
+            "type": "object",
+            "properties": {
+              "username": {
+                "type": "string",
+                "title": "Username",
+                "minLength": 1
+              },
+              "token": {
+                "type": "string",
+                "title": "Token",
+                "minLength": 1
+              }
+            },
+            "required": ["username", "token"]
+          }
+        },
+        "settings": {
+          "type": "object",
+          "title": "Settings",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "title": "Enabled"
+            },
+            "count": {
+              "type": "integer",
+              "title": "Count"
+            }
+          }
+        }
+      },
+      "required": ["api_key"]
+    }
+  }
 }

resources/i18n/es.json

@@ -12,12 +12,16 @@
         "artist": "Artista",
         "album": "Álbum",
         "path": "Ruta del archivo",
+        "libraryName": "Biblioteca",
         "genre": "Género",
         "compilation": "Compilación",
         "year": "Año",
         "size": "Tamaño del archivo",
         "updatedAt": "Actualizado el",
         "bitRate": "Tasa de bits",
+        "bitDepth": "Profundidad de bits",
+        "sampleRate": "Frecuencia de muestreo",
+        "channels": "Canales",
         "discSubtitle": "Subtítulo del disco",
         "starred": "Favorito",
         "comment": "Comentario",
@@ -25,7 +29,6 @@
         "quality": "Calidad",
         "bpm": "BPM",
         "playDate": "Últimas reproducciones",
-        "channels": "Canales",
         "createdAt": "Creado el",
         "grouping": "Agrupación",
         "mood": "Estado de ánimo",
@@ -33,20 +36,17 @@
         "tags": "Etiquetas",
         "mappedTags": "Etiquetas asignadas",
         "rawTags": "Etiquetas sin procesar",
-        "bitDepth": "Profundidad de bits",
-        "sampleRate": "Frecuencia de muestreo",
-        "missing": "Faltante",
-        "libraryName": "Biblioteca"
+        "missing": "Faltante"
       },
       "actions": {
         "addToQueue": "Reproducir después",
         "playNow": "Reproducir ahora",
         "addToPlaylist": "Agregar a la playlist",
+        "showInPlaylist": "Mostrar en la lista de reproducción",
         "shuffleAll": "Todas aleatorias",
         "download": "Descarga",
         "playNext": "Siguiente",
-        "info": "Obtener información",
-        "showInPlaylist": "Mostrar en la lista de reproducción"
+        "info": "Obtener información"
       }
     },
     "album": {
@@ -57,38 +57,38 @@
         "duration": "Duración",
         "songCount": "Canciones",
         "playCount": "Reproducciones",
+        "size": "Tamaño del archivo",
         "name": "Nombre",
+        "libraryName": "Biblioteca",
         "genre": "Género",
         "compilation": "Compilación",
         "year": "Año",
-        "updatedAt": "Actualizado el",
-        "comment": "Comentario",
-        "rating": "Calificación",
-        "createdAt": "Creado el",
-        "size": "Tamaño del archivo",
+        "date": "Fecha de grabación",
         "originalDate": "Original",
         "releaseDate": "Publicado",
         "releases": "Lanzamiento |||| Lanzamientos",
         "released": "Publicado",
+        "updatedAt": "Actualizado el",
+        "comment": "Comentario",
+        "rating": "Calificación",
+        "createdAt": "Creado el",
         "recordLabel": "Discográfica",
         "catalogNum": "Número de catálogo",
         "releaseType": "Tipo de lanzamiento",
         "grouping": "Agrupación",
         "media": "Medios",
         "mood": "Estado de ánimo",
-        "date": "Fecha de grabación",
-        "missing": "Faltante",
-        "libraryName": "Biblioteca"
+        "missing": "Faltante"
       },
       "actions": {
         "playAll": "Reproducir",
         "playNext": "Reproducir siguiente",
         "addToQueue": "Reproducir después",
+        "share": "Compartir",
         "shuffle": "Aleatorio",
         "addToPlaylist": "Agregar a la lista",
         "download": "Descargar",
-        "info": "Obtener información",
-        "share": "Compartir"
+        "info": "Obtener información"
       },
       "lists": {
         "all": "Todos",
@@ -106,33 +106,33 @@
         "name": "Nombre",
         "albumCount": "Número de álbumes",
         "songCount": "Número de canciones",
+        "size": "Tamaño",
         "playCount": "Reproducciones",
         "rating": "Calificación",
         "genre": "Género",
-        "size": "Tamaño",
         "role": "Rol",
         "missing": "Faltante"
       },
       "roles": {
-        "albumartist": "Artista del álbum",
-        "artist": "Artista",
-        "composer": "Compositor",
-        "conductor": "Director de orquesta",
-        "lyricist": "Letrista",
-        "arranger": "Arreglista",
-        "producer": "Productor",
-        "director": "Director",
-        "engineer": "Ingeniero de sonido",
-        "mixer": "Mezclador",
-        "remixer": "Remixer",
-        "djmixer": "DJ Mixer",
-        "performer": "Intérprete",
+        "albumartist": "Artista del álbum |||| Artistas del álbum",
+        "artist": "Artista |||| Artistas",
+        "composer": "Compositor |||| Compositores",
+        "conductor": "Director de orquesta |||| Directores de orquesta",
+        "lyricist": "Letrista |||| Letristas",
+        "arranger": "Arreglista |||| Arreglistas",
+        "producer": "Productor |||| Productores",
+        "director": "Director |||| Directores",
+        "engineer": "Ingeniero de sonido |||| Ingenieros de sonido",
+        "mixer": "Mezclador |||| Mezcladores",
+        "remixer": "Remezclador |||| Remezcladores",
+        "djmixer": "DJ Mezclador |||| DJ Mezcladores",
+        "performer": "Intérprete |||| Intérpretes",
         "maincredit": "Artista del álbum o Artista |||| Artistas del álbum o Artistas"
       },
       "actions": {
+        "topSongs": "Más destacadas",
         "shuffle": "Aleatorio",
-        "radio": "Radio",
-        "topSongs": "Más destacadas"
+        "radio": "Radio"
       }
     },
     "user": {
@@ -141,6 +141,7 @@
         "userName": "Nombre de usuario",
         "isAdmin": "Es administrador",
         "lastLoginAt": "Último inicio de sesión",
+        "lastAccessAt": "Último acceso",
         "updatedAt": "Actualizado el",
         "name": "Nombre",
         "password": "Contraseña",
@@ -149,7 +150,6 @@
         "currentPassword": "Contraseña actual",
         "newPassword": "Nueva contraseña",
         "token": "Token",
-        "lastAccessAt": "Último acceso",
         "libraries": "Bibliotecas"
       },
       "helperTexts": {
@@ -189,7 +189,7 @@
       "fields": {
         "name": "Nombre",
         "targetFormat": "Formato de destino",
-        "defaultBitRate": "Tasa de bits default",
+        "defaultBitRate": "Tasa de bits por defecto",
         "command": "Comando"
       }
     },
@@ -211,9 +211,9 @@
         "selectPlaylist": "Seleccione una lista:",
         "addNewPlaylist": "Creada \"%{name}\"",
         "export": "Exportar",
+        "saveQueue": "Guardar la fila de reproducción en una playlist",
         "makePublic": "Hazla pública",
         "makePrivate": "Hazla privada",
-        "saveQueue": "Guardar la fila de reproducción en una playlist",
         "searchOrCreate": "Buscar listas de reproducción o escribe para crear una nueva…",
         "pressEnterToCreate": "Pulsa Enter para crear una nueva lista de reproducción",
         "removeFromSelection": "Quitar de la selección"
@@ -239,11 +239,12 @@
       }
     },
     "share": {
-      "name": "Compartir",
+      "name": "Compartir |||| Compartidos",
       "fields": {
-        "username": "Nombre de usuario",
+        "username": "Compartido por",
         "url": "URL",
         "description": "Descripción",
+        "downloadable": "¿Permitir descargas?",
         "contents": "Contenido",
         "expiresAt": "Caduca el",
         "lastVisitedAt": "Visitado por última vez el",
@@ -251,12 +252,14 @@
         "format": "Formato",
         "maxBitRate": "Tasa de bits Máx.",
         "updatedAt": "Actualizado el",
-        "createdAt": "Creado el",
-        "downloadable": "¿Permitir descargas?"
-      }
+        "createdAt": "Creado el"
+      },
+      "notifications": {},
+      "actions": {}
     },
     "missing": {
-      "name": "Faltante",
+      "name": "Fichero faltante |||| Ficheros faltantes",
+      "empty": "No faltan archivos",
       "fields": {
         "path": "Ruta",
         "size": "Tamaño",
@@ -269,8 +272,7 @@
       },
       "notifications": {
         "removed": "Eliminado"
-      },
-      "empty": "No hay archivos perdidos"
+      }
     },
     "library": {
       "name": "Biblioteca |||| Bibliotecas",
@@ -290,7 +292,7 @@
         "totalMissingFiles": "Archivos faltantes",
         "totalSize": "Tamaño total",
         "totalDuration": "Duración",
-        "defaultNewUsers": "Valor por defecto para los nuevos usuarios",
+        "defaultNewUsers": "Por defecto para nuevos usuarios",
         "createdAt": "Creado",
         "updatedAt": "Actualizado"
       },
@@ -300,20 +302,20 @@
       },
       "actions": {
         "scan": "Escanear biblioteca",
-        "manageUsers": "Gestionar el acceso de usarios",
-        "viewDetails": "Ver detalles",
         "quickScan": "Escaneo rápido",
-        "fullScan": "Escaneo completo"
+        "fullScan": "Escaneo completo",
+        "manageUsers": "Gestionar el acceso de usarios",
+        "viewDetails": "Ver detalles"
       },
       "notifications": {
         "created": "La biblioteca se creó correctamente",
         "updated": "La biblioteca se actualizó correctamente",
         "deleted": "La biblioteca se eliminó correctamente",
         "scanStarted": "El escaneo de la biblioteca ha comenzado",
-        "scanCompleted": "El escaneo de la biblioteca se completó",
         "quickScanStarted": "Escaneo rápido ha comenzado",
         "fullScanStarted": "Escaneo completo ha comenzado",
-        "scanError": "Error al iniciar el escaneo. Revisa los registros"
+        "scanError": "Error al iniciar el escaneo. Revisa los registros",
+        "scanCompleted": "El escaneo de la biblioteca se completó"
       },
       "validation": {
         "nameRequired": "El nombre de la biblioteca es obligatorio",
@@ -328,6 +330,78 @@
         "scanInProgress": "Escaneo en curso...",
         "noLibrariesAssigned": "No hay bibliotecas asignadas a este usuario"
       }
+    },
+    "plugin": {
+      "name": "Plugin |||| Plugins",
+      "fields": {
+        "id": "ID",
+        "name": "Nombre",
+        "description": "Descripción",
+        "version": "Versión",
+        "author": "Autor",
+        "website": "Web",
+        "permissions": "Permisos",
+        "enabled": "Activado",
+        "status": "Estado",
+        "path": "Ruta",
+        "lastError": "Error",
+        "hasError": "Error",
+        "updatedAt": "Actualizado",
+        "createdAt": "Instalado",
+        "configKey": "Clave",
+        "configValue": "Valor",
+        "allUsers": "Permitir todos los usuarios",
+        "selectedUsers": "Usuarios seleccionados",
+        "allLibraries": "Permitir todas las bibliotecas",
+        "selectedLibraries": "Bibliotecas seleccionadas"
+      },
+      "sections": {
+        "status": "Estado",
+        "info": "Información del Plugin",
+        "configuration": "Configuración",
+        "manifest": "Manifiesto",
+        "usersPermission": "Permiso del usuario",
+        "libraryPermission": "Permiso de la biblioteca"
+      },
+      "status": {
+        "enabled": "Activado",
+        "disabled": "Deshabilitado"
+      },
+      "actions": {
+        "enable": "Activar",
+        "disable": "Desactivar",
+        "disabledDueToError": "Corrige el error antes de activar",
+        "disabledUsersRequired": "Selecciona usuarios antes de activar",
+        "disabledLibrariesRequired": "Selecciona bibliotecas antes de activar",
+        "addConfig": "Añadir configuración",
+        "rescan": "Reescanear"
+      },
+      "notifications": {
+        "enabled": "Plugin activado",
+        "disabled": "Plugin deshabilitado",
+        "updated": "Plugin actualizado",
+        "error": "Error al actualizar el plugin"
+      },
+      "validation": {
+        "invalidJson": "La configuración debe ser un JSON válido"
+      },
+      "messages": {
+        "configHelp": "Configura el plugin utilizando pares de clave-valor. Déjalo en blanco si el plugin no requiere configuración.",
+        "clickPermissions": "Haz clic en un permiso para ver los detalles",
+        "noConfig": "No hay configuración establecida",
+        "allUsersHelp": "Cuando se active, el plugin tendrá acceso a todos los usuarios, incluidos los que se creen en el futuro.",
+        "noUsers": "Ningún usuario seleccionado",
+        "permissionReason": "Razón",
+        "usersRequired": "Este plugin requiere acceso a la información de los usuarios. Selecciona a qué usuarios puede acceder el plugin, o activa 'Permitir todos los usuarios'.",
+        "allLibrariesHelp": "Cuando se active, el plugin tendrá acceso a todas las bibliotecas, incluidas las que se creen en el futuro.",
+        "noLibraries": "Ninguna biblioteca seleccionada",
+        "librariesRequired": "Este plugin requiere acceso a la información de las bibliotecas. Selecciona a qué bibliotecas puede acceder el plugin, o activa 'Permitir todas las bibliotecas'.",
+        "requiredHosts": "Hosts requeridos"
+      },
+      "placeholders": {
+        "configKey": "clave",
+        "configValue": "valor"
+      }
     }
   },
   "ra": {
@@ -365,6 +439,7 @@
       "add": "Añadir",
       "back": "Ir atrás",
       "bulk_actions": "1 elemento seleccionado |||| %{smart_count} elementos seleccionados",
+      "bulk_actions_mobile": "1 |||| %{smart_count}",
       "cancel": "Cancelar",
       "clear_input_value": "Limpiar valor",
       "clone": "Duplicar",
@@ -388,7 +463,6 @@
       "close_menu": "Cerrar menú",
       "unselect": "Deseleccionado",
       "skip": "Omitir",
-      "bulk_actions_mobile": "1 |||| %{smart_count}",
       "share": "Compartir",
       "download": "Descargar"
     },
@@ -480,41 +554,47 @@
     "transcodingDisabled": "Cambiar la configuración de la transcodificación a través de la interfaz web esta deshabilitado por motivos de seguridad. Si quieres cambiar (editar o agregar) opciones de transcodificación, reinicia el servidor con la %{config} opción de configuración.",
     "transcodingEnabled": "Navidrom se esta ejecutando con %{config}, lo que hace posible ejecutar comandos de sistema desde el apartado de transcodificación en la interfaz web. Recomendamos deshabilitarlo por motivos de seguridad y solo habilitarlo cuando se este configurando opciones de transcodificación.",
     "songsAddedToPlaylist": "1 canción agregada a la lista |||| %{smart_count} canciones agregadas a la lista",
+    "noSimilarSongsFound": "No se encontraron canciones similares",
+    "noTopSongsFound": "No se encontraron canciones destacadas",
     "noPlaylistsAvailable": "Ninguna lista disponible",
     "delete_user_title": "Eliminar usuario '%{name}'",
     "delete_user_content": "¿Esta seguro de eliminar a este usuario y todos sus datos (incluyendo listas y preferencias)?",
+    "remove_missing_title": "Eliminar archivos faltantes",
+    "remove_missing_content": "¿Realmente desea eliminar los archivos faltantes seleccionados de la base de datos? Esto eliminará permanentemente cualquier referencia a ellos, incluidas sus reproducciones y valoraciones.",
+    "remove_all_missing_title": "Eliminar todos los archivos faltantes",
+    "remove_all_missing_content": "¿Realmente desea eliminar todos los archivos faltantes de la base de datos? Esto eliminará permanentemente cualquier referencia a ellos, incluidas sus reproducciones y valoraciones.",
     "notifications_blocked": "Las notificaciones de este sitio están bloqueadas en tu navegador",
     "notifications_not_available": "Este navegador no soporta notificaciones o no ingresaste a Navidrome usando https",
     "lastfmLinkSuccess": "Last.fm esta conectado y el scrobbling esta activado",
     "lastfmLinkFailure": "No se pudo conectar con Last.fm",
     "lastfmUnlinkSuccess": "Last.fm se ha desconectado y el scrobbling se desactivo",
     "lastfmUnlinkFailure": "No se pudo desconectar Last.fm",
+    "listenBrainzLinkSuccess": "Se ha conectado correctamente a ListenBrainz y se activó el scrobbling como el usuario: %{user}",
+    "listenBrainzLinkFailure": "No se pudo conectar con ListenBrainz: %{error}",
+    "listenBrainzUnlinkSuccess": "Se desconectó ListenBrainz y se desactivó el scrobbling",
+    "listenBrainzUnlinkFailure": "No se pudo desconectar ListenBrainz",
     "openIn": {
       "lastfm": "Ver en Last.fm",
       "musicbrainz": "Ver en MusicBrainz"
     },
     "lastfmLink": "Leer más...",
-    "listenBrainzLinkSuccess": "Se ha conectado correctamente a ListenBrainz y se activo el scrobbling como el usuario: %{user}",
-    "listenBrainzLinkFailure": "No se pudo conectar con ListenBrainz: %{error}",
-    "listenBrainzUnlinkSuccess": "Se desconecto ListenBrainz y se desactivo el scrobbling",
-    "listenBrainzUnlinkFailure": "No se pudo desconectar ListenBrainz",
-    "downloadOriginalFormat": "Descargar formato original",
     "shareOriginalFormat": "Compartir formato original",
     "shareDialogTitle": "Compartir %{resource} '%{name}'",
     "shareBatchDialogTitle": "Compartir 1 %{resource} |||| Compartir %{smart_count} %{resource}",
+    "shareCopyToClipboard": "Copiar al portapapeles: Ctrl+C, Intro",
     "shareSuccess": "URL copiada al portapapeles: %{url}",
     "shareFailure": "Error al copiar la URL %{url} al portapapeles",
     "downloadDialogTitle": "Descargar %{resource} '%{name}' (%{size})",
-    "shareCopyToClipboard": "Copiar al portapapeles: Ctrl+C, Intro",
-    "remove_missing_title": "Eliminar elemento faltante",
-    "remove_missing_content": "¿Realmente desea eliminar los archivos faltantes seleccionados de la base de datos? Esto eliminará permanentemente cualquier referencia a ellos, incluidas sus reproducciones y valoraciones.",
-    "remove_all_missing_title": "Eliminar todos los archivos perdidos",
-    "remove_all_missing_content": "¿Realmente desea eliminar todos los archivos faltantes de la base de datos? Esto eliminará permanentemente cualquier referencia a ellos, incluidas sus reproducciones y valoraciones.",
-    "noSimilarSongsFound": "No se encontraron canciones similares",
-    "noTopSongsFound": "No se encontraron canciones destacadas"
+    "downloadOriginalFormat": "Descargar formato original"
   },
   "menu": {
     "library": "Biblioteca",
+    "librarySelector": {
+      "allLibraries": "Todas las bibliotecas (%{count})",
+      "multipleLibraries": "%{selected} de %{total} bibliotecas",
+      "selectLibraries": "Seleccionar bibliotecas",
+      "none": "Ninguno"
+    },
     "settings": "Ajustes",
     "version": "Versión",
     "theme": "Tema",
@@ -525,28 +605,22 @@
         "language": "Idioma",
         "defaultView": "Vista por defecto",
         "desktop_notifications": "Notificaciones de escritorio",
+        "lastfmNotConfigured": "La clave API de Last.fm no está configurada",
         "lastfmScrobbling": "Scrobble a Last.fm",
         "listenBrainzScrobbling": "Scrobble a ListenBrainz",
         "replaygain": "Modo de ReplayGain",
         "preAmp": "ReplayGain PreAmp (dB)",
         "gain": {
-          "none": "Ninguno",
-          "album": "Álbum",
-          "track": "Pista"
-        },
-        "lastfmNotConfigured": "La clave API de Last.fm no está configurada"
+          "none": "Desactivado",
+          "album": "Ganancia del álbum",
+          "track": "Ganancia de pista"
+        }
       }
     },
     "albumList": "Álbumes",
-    "about": "Acerca de",
     "playlists": "Playlists",
     "sharedPlaylists": "Playlists Compartidas",
-    "librarySelector": {
-      "allLibraries": "Todas las bibliotecas (%{count})",
-      "multipleLibraries": "%{selected} de %{total} bibliotecas",
-      "selectLibraries": "Seleccionar bibliotecas",
-      "none": "Ninguno"
-    }
+    "about": "Acerca de"
   },
   "player": {
     "playListsText": "Fila de reproducción",
@@ -605,12 +679,17 @@
     "totalScanned": "Total de carpetas escaneadas",
     "quickScan": "Escaneo rápido",
     "fullScan": "Escaneo completo",
+    "selectiveScan": "Selectivo",
     "serverUptime": "Uptime del servidor",
     "serverDown": "OFFLINE",
     "scanType": "Tipo",
     "status": "Error de escaneo",
-    "elapsedTime": "Tiempo transcurrido",
-    "selectiveScan": "Selectivo"
+    "elapsedTime": "Tiempo transcurrido"
+  },
+  "nowPlaying": {
+    "title": "En reproducción",
+    "empty": "Nada en reproducción",
+    "minutesAgo": "Hace %{smart_count} minuto |||| Hace %{smart_count} minutos"
   },
   "help": {
     "title": "Atajos de teclado de Navidrome",
@@ -620,15 +699,10 @@
       "toggle_play": "Reproducir / Pausar",
       "prev_song": "Canción anterior",
       "next_song": "Siguiente canción",
+      "current_song": "Canción actual",
       "vol_up": "Subir volumen",
       "vol_down": "Bajar volumen",
-      "toggle_love": "Marca esta canción como favorita",
-      "current_song": "Canción actual"
+      "toggle_love": "Marca esta canción como favorita"
     }
-  },
-  "nowPlaying": {
-    "title": "En reproducción",
-    "empty": "Nada en reproducción",
-    "minutesAgo": "Hace %{smart_count} minuto |||| Hace %{smart_count} minutos"
   }
-}
+}

resources/i18n/pt-br.json

@@ -387,6 +387,8 @@
       },
       "messages": {
         "configHelp": "Configure o plugin usando pares chave-valor. Deixe vazio se o plugin não precisa de configuração.",
+        "configValidationError": "Falha na validação da configuração:",
+        "schemaRenderError": "Não foi possível renderizar o formulário de configuração. O schema do plugin pode estar inválido.",
         "clickPermissions": "Clique em uma permissão para ver detalhes",
         "noConfig": "Nenhuma configuração definida",
         "allUsersHelp": "Quando habilitado, o plugin terá acesso a todos os usuários, incluindo os criados no futuro.",

resources/i18n/sv.json

@@ -10,6 +10,7 @@
         "playCount": "Spelningar",
         "title": "Titel",
         "artist": "Artist",
+        "composer": "Kompositör",
         "album": "Album",
         "path": "Sökväg",
         "genre": "Genre",

scanner/scanner_suite_test.go

@@ -14,8 +14,8 @@ import (
 )
 
 func TestScanner(t *testing.T) {
-	// Only run goleak checks when not in CI environment
-	if os.Getenv("CI") == "" {
+	// Only run goleak checks when the GOLEAK env var is set
+	if os.Getenv("GOLEAK") != "" {
 		// Detect any goroutine leaks in the scanner code under test
 		defer goleak.VerifyNone(t,
 			goleak.IgnoreTopFunction("github.com/onsi/ginkgo/v2/internal/interrupt_handler.(*InterruptHandler).registerForInterrupts.func2"),

server/nativeapi/native_api.go

@@ -25,6 +25,7 @@ import (
 type PluginManager interface {
 	EnablePlugin(ctx context.Context, id string) error
 	DisablePlugin(ctx context.Context, id string) error
+	ValidatePluginConfig(ctx context.Context, id, configJSON string) error
 	UpdatePluginConfig(ctx context.Context, id, configJSON string) error
 	UpdatePluginUsers(ctx context.Context, id, usersJSON string, allUsers bool) error
 	UpdatePluginLibraries(ctx context.Context, id, librariesJSON string, allLibraries bool) error

server/nativeapi/plugin.go

@@ -171,13 +171,26 @@ func isValidJSON(s string) bool {
 	return json.Unmarshal([]byte(s), &js) == nil
 }
 
-// validateAndUpdateConfig validates the config JSON and updates the plugin.
+// validateAndUpdateConfig validates the config JSON against the plugin's schema and updates the plugin.
 // Returns an error if validation or update fails (error response already written).
 func validateAndUpdateConfig(ctx context.Context, pm PluginManager, id, configJSON string, w http.ResponseWriter) error {
+	// Basic JSON syntax check
 	if configJSON != "" && !isValidJSON(configJSON) {
 		http.Error(w, "Invalid JSON in config field", http.StatusBadRequest)
 		return errors.New("invalid JSON")
 	}
+
+	// Validate against plugin's config schema
+	if err := pm.ValidatePluginConfig(ctx, id, configJSON); err != nil {
+		log.Warn(ctx, "Config validation failed", "id", id, err)
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusBadRequest)
+		// Try to return structured validation errors if available
+		response := map[string]any{"message": err.Error()}
+		_ = json.NewEncoder(w).Encode(response)
+		return err
+	}
+
 	if err := pm.UpdatePluginConfig(ctx, id, configJSON); err != nil {
 		log.Error(ctx, "Error updating plugin config", "id", id, err)
 		http.Error(w, "Error updating plugin configuration: "+err.Error(), http.StatusInternalServerError)

server/subsonic/browsing.go

@@ -354,7 +354,7 @@ func (api *Router) GetSimilarSongs(r *http.Request) (*responses.Subsonic, error)
 	}
 	count := p.IntOr("count", 50)
 
-	songs, err := api.provider.ArtistRadio(ctx, id, count)
+	songs, err := api.provider.SimilarSongs(ctx, id, count)
 	if err != nil {
 		return nil, err
 	}
@@ -410,6 +410,9 @@ func (api *Router) buildArtistDirectory(ctx context.Context, artist *model.Artis
 	}
 	dir.AlbumCount = getArtistAlbumCount(artist)
 	dir.UserRating = int32(artist.Rating)
+	if conf.Server.Subsonic.EnableAverageRating {
+		dir.AverageRating = artist.AverageRating
+	}
 	if artist.Starred {
 		dir.Starred = artist.StarredAt
 	}
@@ -447,6 +450,9 @@ func (api *Router) buildAlbumDirectory(ctx context.Context, album *model.Album)
 		dir.Played = album.PlayDate
 	}
 	dir.UserRating = int32(album.Rating)
+	if conf.Server.Subsonic.EnableAverageRating {
+		dir.AverageRating = album.AverageRating
+	}
 	dir.SongCount = int32(album.SongCount)
 	dir.CoverArt = album.CoverArtID().String()
 	if album.Starred {

server/subsonic/helpers.go

@@ -101,6 +101,9 @@ func toArtist(r *http.Request, a model.Artist) responses.Artist {
 		CoverArt:       a.CoverArtID().String(),
 		ArtistImageUrl: publicurl.ImageURL(r, a.CoverArtID(), 600),
 	}
+	if conf.Server.Subsonic.EnableAverageRating {
+		artist.AverageRating = a.AverageRating
+	}
 	if a.Starred {
 		artist.Starred = a.StarredAt
 	}
@@ -116,6 +119,9 @@ func toArtistID3(r *http.Request, a model.Artist) responses.ArtistID3 {
 		ArtistImageUrl: publicurl.ImageURL(r, a.CoverArtID(), 600),
 		UserRating:     int32(a.Rating),
 	}
+	if conf.Server.Subsonic.EnableAverageRating {
+		artist.AverageRating = a.AverageRating
+	}
 	if a.Starred {
 		artist.Starred = a.StarredAt
 	}
@@ -218,6 +224,9 @@ func childFromMediaFile(ctx context.Context, mf model.MediaFile) responses.Child
 		child.Starred = mf.StarredAt
 	}
 	child.UserRating = int32(mf.Rating)
+	if conf.Server.Subsonic.EnableAverageRating {
+		child.AverageRating = mf.AverageRating
+	}
 
 	format, _ := getTranscoding(ctx)
 	if mf.Suffix != "" && format != "" && mf.Suffix != format {
@@ -329,6 +338,9 @@ func childFromAlbum(ctx context.Context, al model.Album) responses.Child {
 	}
 	child.PlayCount = al.PlayCount
 	child.UserRating = int32(al.Rating)
+	if conf.Server.Subsonic.EnableAverageRating {
+		child.AverageRating = al.AverageRating
+	}
 	child.OpenSubsonicChild = osChildFromAlbum(ctx, al)
 	return child
 }
@@ -422,6 +434,9 @@ func buildOSAlbumID3(ctx context.Context, album model.Album) *responses.OpenSubs
 		dir.Played = album.PlayDate
 	}
 	dir.UserRating = int32(album.Rating)
+	if conf.Server.Subsonic.EnableAverageRating {
+		dir.AverageRating = album.AverageRating
+	}
 	dir.RecordLabels = slice.Map(album.Tags.Values(model.TagRecordLabel), func(s string) responses.RecordLabel {
 		return responses.RecordLabel{Name: s}
 	})

server/subsonic/helpers_test.go

@@ -4,8 +4,10 @@ import (
 	"context"
 	"net/http/httptest"
 
+	"github.com/go-chi/jwtauth/v5"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/core/auth"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/server/subsonic/responses"
@@ -17,6 +19,7 @@ import (
 var _ = Describe("helpers", func() {
 	BeforeEach(func() {
 		DeferCleanup(configtest.SetupConfig())
+		auth.TokenAuth = jwtauth.New("HS256", []byte("test secret"), nil)
 	})
 
 	Describe("fakePath", func() {
@@ -456,4 +459,131 @@ var _ = Describe("helpers", func() {
 			})
 		})
 	})
+
+	Describe("AverageRating in responses", func() {
+		var ctx context.Context
+
+		BeforeEach(func() {
+			ctx = context.Background()
+			conf.Server.Subsonic.EnableAverageRating = true
+		})
+
+		Describe("childFromMediaFile", func() {
+			It("includes averageRating when set", func() {
+				mf := model.MediaFile{
+					ID:    "mf-avg-1",
+					Title: "Test Song",
+					Annotations: model.Annotations{
+						AverageRating: 4.5,
+					},
+				}
+				child := childFromMediaFile(ctx, mf)
+				Expect(child.AverageRating).To(Equal(4.5))
+			})
+
+			It("returns 0 for averageRating when not set", func() {
+				mf := model.MediaFile{
+					ID:    "mf-avg-2",
+					Title: "Test Song No Rating",
+				}
+				child := childFromMediaFile(ctx, mf)
+				Expect(child.AverageRating).To(Equal(0.0))
+			})
+		})
+
+		Describe("childFromAlbum", func() {
+			It("includes averageRating when set", func() {
+				al := model.Album{
+					ID:   "al-avg-1",
+					Name: "Test Album",
+					Annotations: model.Annotations{
+						AverageRating: 3.75,
+					},
+				}
+				child := childFromAlbum(ctx, al)
+				Expect(child.AverageRating).To(Equal(3.75))
+			})
+
+			It("returns 0 for averageRating when not set", func() {
+				al := model.Album{
+					ID:   "al-avg-2",
+					Name: "Test Album No Rating",
+				}
+				child := childFromAlbum(ctx, al)
+				Expect(child.AverageRating).To(Equal(0.0))
+			})
+		})
+
+		Describe("toArtist", func() {
+			It("includes averageRating when set", func() {
+				conf.Server.Subsonic.EnableAverageRating = true
+				r := httptest.NewRequest("GET", "/test", nil)
+				a := model.Artist{
+					ID:   "ar-avg-1",
+					Name: "Test Artist",
+					Annotations: model.Annotations{
+						AverageRating: 5.0,
+					},
+				}
+				artist := toArtist(r, a)
+				Expect(artist.AverageRating).To(Equal(5.0))
+			})
+		})
+
+		Describe("toArtistID3", func() {
+			It("includes averageRating when set", func() {
+				conf.Server.Subsonic.EnableAverageRating = true
+				r := httptest.NewRequest("GET", "/test", nil)
+				a := model.Artist{
+					ID:   "ar-avg-2",
+					Name: "Test Artist ID3",
+					Annotations: model.Annotations{
+						AverageRating: 2.5,
+					},
+				}
+				artist := toArtistID3(r, a)
+				Expect(artist.AverageRating).To(Equal(2.5))
+			})
+		})
+
+		Describe("EnableAverageRating config", func() {
+			It("excludes averageRating when disabled", func() {
+				conf.Server.Subsonic.EnableAverageRating = false
+
+				mf := model.MediaFile{
+					ID:    "mf-cfg-1",
+					Title: "Test Song",
+					Annotations: model.Annotations{
+						AverageRating: 4.5,
+					},
+				}
+				child := childFromMediaFile(ctx, mf)
+				Expect(child.AverageRating).To(Equal(0.0))
+
+				al := model.Album{
+					ID:   "al-cfg-1",
+					Name: "Test Album",
+					Annotations: model.Annotations{
+						AverageRating: 3.75,
+					},
+				}
+				albumChild := childFromAlbum(ctx, al)
+				Expect(albumChild.AverageRating).To(Equal(0.0))
+
+				r := httptest.NewRequest("GET", "/test", nil)
+				a := model.Artist{
+					ID:   "ar-cfg-1",
+					Name: "Test Artist",
+					Annotations: model.Annotations{
+						AverageRating: 5.0,
+					},
+				}
+				artist := toArtist(r, a)
+				Expect(artist.AverageRating).To(Equal(0.0))
+
+				artistID3 := toArtistID3(r, a)
+				Expect(artistID3.AverageRating).To(Equal(0.0))
+			})
+		})
+	})
 })

server/subsonic/responses/responses.go

@@ -95,11 +95,9 @@ type Artist struct {
 	Name           string     `xml:"name,attr"                         json:"name"`
 	Starred        *time.Time `xml:"starred,attr,omitempty"            json:"starred,omitempty"`
 	UserRating     int32      `xml:"userRating,attr,omitempty"         json:"userRating,omitempty"`
+	AverageRating  float64    `xml:"averageRating,attr,omitempty"      json:"averageRating,omitempty"`
 	CoverArt       string     `xml:"coverArt,attr,omitempty"           json:"coverArt,omitempty"`
 	ArtistImageUrl string     `xml:"artistImageUrl,attr,omitempty"     json:"artistImageUrl,omitempty"`
-	/* TODO:
-	<xs:attribute name="averageRating" type="sub:AverageRating" use="optional"/>  <!-- Added in 1.13.0 -->
-	*/
 }
 
 type Index struct {
@@ -160,13 +158,11 @@ type Child struct {
 	ArtistId              string     `xml:"artistId,attr,omitempty"                 json:"artistId,omitempty"`
 	Type                  string     `xml:"type,attr,omitempty"                     json:"type,omitempty"`
 	UserRating            int32      `xml:"userRating,attr,omitempty"               json:"userRating,omitempty"`
+	AverageRating         float64    `xml:"averageRating,attr,omitempty"            json:"averageRating,omitempty"`
 	SongCount             int32      `xml:"songCount,attr,omitempty"                json:"songCount,omitempty"`
 	IsVideo               bool       `xml:"isVideo,attr,omitempty"                  json:"isVideo,omitempty"`
 	BookmarkPosition      int64      `xml:"bookmarkPosition,attr,omitempty"         json:"bookmarkPosition,omitempty"`
-	/*
-	   <xs:attribute name="averageRating" type="sub:AverageRating" use="optional"/>  <!-- Added in 1.6.0 -->
-	*/
-	*OpenSubsonicChild `xml:",omitempty" json:",omitempty"`
+	*OpenSubsonicChild    `xml:",omitempty" json:",omitempty"`
 }
 
 type OpenSubsonicChild struct {
@@ -198,14 +194,15 @@ type Songs struct {
 }
 
 type Directory struct {
-	Child      []Child    `xml:"child"                              json:"child,omitempty"`
-	Id         string     `xml:"id,attr"                            json:"id"`
-	Name       string     `xml:"name,attr"                          json:"name"`
-	Parent     string     `xml:"parent,attr,omitempty"              json:"parent,omitempty"`
-	Starred    *time.Time `xml:"starred,attr,omitempty"             json:"starred,omitempty"`
-	PlayCount  int64      `xml:"playCount,attr,omitempty"           json:"playCount,omitempty"`
-	Played     *time.Time `xml:"played,attr,omitempty"              json:"played,omitempty"`
-	UserRating int32      `xml:"userRating,attr,omitempty"          json:"userRating,omitempty"`
+	Child         []Child    `xml:"child"                              json:"child,omitempty"`
+	Id            string     `xml:"id,attr"                            json:"id"`
+	Name          string     `xml:"name,attr"                          json:"name"`
+	Parent        string     `xml:"parent,attr,omitempty"              json:"parent,omitempty"`
+	Starred       *time.Time `xml:"starred,attr,omitempty"             json:"starred,omitempty"`
+	PlayCount     int64      `xml:"playCount,attr,omitempty"           json:"playCount,omitempty"`
+	Played        *time.Time `xml:"played,attr,omitempty"              json:"played,omitempty"`
+	UserRating    int32      `xml:"userRating,attr,omitempty"          json:"userRating,omitempty"`
+	AverageRating float64    `xml:"averageRating,attr,omitempty"       json:"averageRating,omitempty"`
 
 	// ID3
 	Artist     string     `xml:"artist,attr,omitempty"              json:"artist,omitempty"`
@@ -217,10 +214,6 @@ type Directory struct {
 	Created    *time.Time `xml:"created,attr,omitempty"             json:"created,omitempty"`
 	Year       int32      `xml:"year,attr,omitempty"                json:"year,omitempty"`
 	Genre      string     `xml:"genre,attr,omitempty"               json:"genre,omitempty"`
-
-	/*
-	   <xs:attribute name="averageRating" type="sub:AverageRating" use="optional"/>  <!-- Added in 1.13.0 -->
-	*/
 }
 
 // ArtistID3Ref is a reference to an artist, a simplified version of ArtistID3. This is used to resolve the
@@ -237,6 +230,7 @@ type ArtistID3 struct {
 	AlbumCount             int32      `xml:"albumCount,attr"                    json:"albumCount"`
 	Starred                *time.Time `xml:"starred,attr,omitempty"             json:"starred,omitempty"`
 	UserRating             int32      `xml:"userRating,attr,omitempty"          json:"userRating,omitempty"`
+	AverageRating          float64    `xml:"averageRating,attr,omitempty"       json:"averageRating,omitempty"`
 	ArtistImageUrl         string     `xml:"artistImageUrl,attr,omitempty"      json:"artistImageUrl,omitempty"`
 	*OpenSubsonicArtistID3 `xml:",omitempty" json:",omitempty"`
 }
@@ -268,6 +262,7 @@ type OpenSubsonicAlbumID3 struct {
 	// OpenSubsonic extensions
 	Played              *time.Time          `xml:"played,attr,omitempty"         json:"played,omitempty"`
 	UserRating          int32               `xml:"userRating,attr,omitempty"     json:"userRating"`
+	AverageRating       float64             `xml:"averageRating,attr,omitempty"  json:"averageRating,omitempty"`
 	Genres              Array[ItemGenre]    `xml:"genres,omitempty"              json:"genres"`
 	MusicBrainzId       string              `xml:"musicBrainzId,attr,omitempty"  json:"musicBrainzId"`
 	IsCompilation       bool                `xml:"isCompilation,attr,omitempty"  json:"isCompilation"`

tests/fixtures/lastfm.track.getsimilar.json

@@ -0,0 +1 @@
+{"similartracks":{"track":[{"name":"Dreaming of Me","mbid":"027b553e-7c74-3ed4-a95e-1d4fea51f174","match":1.0,"url":"https://www.last.fm/music/Depeche+Mode/_/Dreaming+of+Me","artist":{"name":"Depeche Mode","mbid":"8538e728-ca0b-4321-b7e5-cff6565dd4c0","url":"https://www.last.fm/music/Depeche+Mode"}},{"name":"Everything Counts","mbid":"5a5a3ca4-bdb8-4641-a674-9b54b9b319a6","match":0.892602,"url":"https://www.last.fm/music/Depeche+Mode/_/Everything+Counts","artist":{"name":"Depeche Mode","mbid":"8538e728-ca0b-4321-b7e5-cff6565dd4c0","url":"https://www.last.fm/music/Depeche+Mode"}},{"name":"Don't You Want Me","mbid":"","match":0.491341,"url":"https://www.last.fm/music/The+Human+League/_/Don%27t+You+Want+Me","artist":{"name":"The Human League","mbid":"7adaabfb-acfb-47bc-8c7c-59471c2f0db8","url":"https://www.last.fm/music/The+Human+League"}},{"name":"Tainted Love","mbid":"","match":0.454811,"url":"https://www.last.fm/music/Soft+Cell/_/Tainted+Love","artist":{"name":"Soft Cell","mbid":"7fb50287-029d-47cc-825a-235ca28024b2","url":"https://www.last.fm/music/Soft+Cell"}},{"name":"Blue Monday","mbid":"727e84c6-1b56-31dd-a958-a5f46305cec0","match":0.381057,"url":"https://www.last.fm/music/New+Order/_/Blue+Monday","artist":{"name":"New Order","mbid":"f1106b17-dcbb-45f6-b938-199ccfab50cc","url":"https://www.last.fm/music/New+Order"}}],"@attr":{"artist":"Depeche Mode","track":"Just Can't Get Enough"}}}

tests/fixtures/lastfm.track.getsimilar.unknown.json

@@ -0,0 +1 @@
+{"similartracks":{"track":[],"@attr":{"track":"UnknownTrack","artist":"UnknownArtist"}}}

tests/mock_plugin_manager.go

@@ -5,7 +5,7 @@ import (
 )
 
 // MockPluginManager is a mock implementation of plugins.PluginManager for testing.
-// It implements EnablePlugin, DisablePlugin, UpdatePluginConfig, UpdatePluginUsers, UpdatePluginLibraries and RescanPlugins methods.
+// It implements EnablePlugin, DisablePlugin, UpdatePluginConfig, ValidatePluginConfig, UpdatePluginUsers, UpdatePluginLibraries and RescanPlugins methods.
 type MockPluginManager struct {
 	// EnablePluginFn is called when EnablePlugin is invoked. If nil, returns EnableError.
 	EnablePluginFn func(ctx context.Context, id string) error
@@ -13,6 +13,8 @@ type MockPluginManager struct {
 	DisablePluginFn func(ctx context.Context, id string) error
 	// UpdatePluginConfigFn is called when UpdatePluginConfig is invoked. If nil, returns ConfigError.
 	UpdatePluginConfigFn func(ctx context.Context, id, configJSON string) error
+	// ValidatePluginConfigFn is called when ValidatePluginConfig is invoked. If nil, returns ValidateError.
+	ValidatePluginConfigFn func(ctx context.Context, id, configJSON string) error
 	// UpdatePluginUsersFn is called when UpdatePluginUsers is invoked. If nil, returns UsersError.
 	UpdatePluginUsersFn func(ctx context.Context, id, usersJSON string, allUsers bool) error
 	// UpdatePluginLibrariesFn is called when UpdatePluginLibraries is invoked. If nil, returns LibrariesError.
@@ -24,6 +26,7 @@ type MockPluginManager struct {
 	EnableError    error
 	DisableError   error
 	ConfigError    error
+	ValidateError  error
 	UsersError     error
 	LibrariesError error
 	RescanError    error
@@ -35,6 +38,10 @@ type MockPluginManager struct {
 		ID         string
 		ConfigJSON string
 	}
+	ValidatePluginConfigCalls []struct {
+		ID         string
+		ConfigJSON string
+	}
 	UpdatePluginUsersCalls []struct {
 		ID        string
 		UsersJSON string
@@ -75,6 +82,17 @@ func (m *MockPluginManager) UpdatePluginConfig(ctx context.Context, id, configJS
 	return m.ConfigError
 }
 
+func (m *MockPluginManager) ValidatePluginConfig(ctx context.Context, id, configJSON string) error {
+	m.ValidatePluginConfigCalls = append(m.ValidatePluginConfigCalls, struct {
+		ID         string
+		ConfigJSON string
+	}{ID: id, ConfigJSON: configJSON})
+	if m.ValidatePluginConfigFn != nil {
+		return m.ValidatePluginConfigFn(ctx, id, configJSON)
+	}
+	return m.ValidateError
+}
+
 func (m *MockPluginManager) UpdatePluginUsers(ctx context.Context, id, usersJSON string, allUsers bool) error {
 	m.UpdatePluginUsersCalls = append(m.UpdatePluginUsersCalls, struct {
 		ID        string

ui/index.html

@@ -27,6 +27,10 @@
     <meta property="og:image:width" content="300">
     <meta property="og:image:height" content="300">
     <title>Navidrome</title>
+    <script>
+      // Shim for libraries that check for Node.js process object
+      window.process = { env: {} };
+    </script>
     <script>
       window.__APP_CONFIG__ = {{ .AppConfig }}
     </script>

ui/package.json

@@ -16,6 +16,9 @@
     "postinstall": "bin/update-workbox.sh"
   },
   "dependencies": {
+    "@jsonforms/core": "^2.5.2",
+    "@jsonforms/material-renderers": "^2.5.2",
+    "@jsonforms/react": "^2.5.2",
     "@material-ui/core": "^4.12.4",
     "@material-ui/icons": "^4.11.3",
     "@material-ui/lab": "^4.0.0-alpha.61",

ui/src/album/AlbumDetails.jsx

@@ -228,7 +228,7 @@ const AlbumDetails = (props) => {
   let notes =
     albumInfo?.notes?.replace(new RegExp('<.*>', 'g'), '') || record.notes
 
-  if (notes !== undefined) {
+  if (notes) {
     notes += '..'
   }
 
@@ -340,7 +340,7 @@ const AlbumDetails = (props) => {
                 )}
               </Typography>
             )}
-            {isDesktop && (
+            {isDesktop && notes && (
               <Collapse
                 collapsedHeight={'2.75em'}
                 in={expanded}
@@ -364,7 +364,7 @@ const AlbumDetails = (props) => {
       {!isDesktop && record['comment'] && (
         <CollapsibleComment record={record} />
       )}
-      {!isDesktop && (
+      {!isDesktop && notes && (
         <div className={classes.notes}>
           <Collapse collapsedHeight={'1.5em'} in={expanded} timeout={'auto'}>
             <Typography

ui/src/album/AlbumSongs.jsx

@@ -108,6 +108,9 @@ const AlbumSongs = (props) => {
         />
       ),
       artist: isDesktop && <ArtistLinkField source="artist" sortable={false} />,
+      composer: isDesktop && (
+        <ArtistLinkField source="composer" sortable={false} />
+      ),
       duration: <DurationField source="duration" sortable={false} />,
       year: isDesktop && (
         <FunctionField
@@ -148,6 +151,7 @@ const AlbumSongs = (props) => {
     columns: toggleableFields,
     omittedColumns: ['title'],
     defaultOff: [
+      'composer',
       'channels',
       'bpm',
       'year',

ui/src/audioplayer/Player.jsx

@@ -95,6 +95,19 @@ const Player = () => {
     }
   }, [audioInstance, context, gainNode, playerState, gainInfo])
 
+  useEffect(() => {
+    const handleBeforeUnload = (e) => {
+      // Check there's a current track and is actually playing/not paused
+      if (playerState.current?.uuid && audioInstance && !audioInstance.paused) {
+        e.preventDefault()
+        e.returnValue = '' // Chrome requires returnValue to be set
+      }
+    }
+
+    window.addEventListener('beforeunload', handleBeforeUnload)
+    return () => window.removeEventListener('beforeunload', handleBeforeUnload)
+  }, [playerState, audioInstance])
+
   const defaultOptions = useMemo(
     () => ({
       theme: playerTheme,

ui/src/common/LoveButton.jsx

@@ -4,18 +4,26 @@ import FavoriteIcon from '@material-ui/icons/Favorite'
 import FavoriteBorderIcon from '@material-ui/icons/FavoriteBorder'
 import IconButton from '@material-ui/core/IconButton'
 import { makeStyles } from '@material-ui/core/styles'
+import clsx from 'clsx'
 import { useToggleLove } from './useToggleLove'
 import { useRecordContext } from 'react-admin'
 import config from '../config'
 import { isDateSet } from '../utils/validations'
 
-const useStyles = makeStyles({
-  love: {
-    color: (props) => props.color,
-    visibility: (props) =>
-      props.visible === false ? 'hidden' : props.loved ? 'visible' : 'inherit',
+const useStyles = makeStyles(
+  {
+    love: {
+      color: (props) => props.color,
+      visibility: (props) =>
+        props.visible === false
+          ? 'hidden'
+          : props.loved
+            ? 'visible'
+            : 'inherit',
+    },
   },
-})
+  { name: 'NDLoveButton' },
+)
 
 export const LoveButton = ({
   resource,
@@ -25,9 +33,11 @@ export const LoveButton = ({
   component: Button,
   addLabel,
   disabled,
+  className,
+  record: recordProp,
   ...rest
 }) => {
-  const record = useRecordContext(rest) || {}
+  const record = useRecordContext({ record: recordProp }) || {}
   const classes = useStyles({ color, visible, loved: record.starred })
   const [toggleLove, loading] = useToggleLove(resource, record)
 
@@ -48,7 +58,7 @@ export const LoveButton = ({
       onClick={handleToggleLove}
       size={'small'}
       disabled={disabled || loading || record.missing}
-      className={classes.love}
+      className={clsx(classes.love, className)}
       title={
         isDateSet(record.starredAt)
           ? new Date(record.starredAt).toLocaleString()

ui/src/dialogs/SelectPlaylistInput.jsx

@@ -318,11 +318,10 @@ export const SelectPlaylistInput = ({ onChange }) => {
 
   const canCreateNew = Boolean(
     searchText.trim() &&
-      !filteredOptions.some(
-        (option) =>
-          option.name.toLowerCase() === searchText.toLowerCase().trim(),
-      ) &&
-      !selectedPlaylists.some((p) => p.name === searchText.trim()),
+    !filteredOptions.some(
+      (option) => option.name.toLowerCase() === searchText.toLowerCase().trim(),
+    ) &&
+    !selectedPlaylists.some((p) => p.name === searchText.trim()),
   )
 
   return (

ui/src/i18n/en.json

@@ -10,6 +10,7 @@
         "playCount": "Plays",
         "title": "Title",
         "artist": "Artist",
+        "composer": "Composer",
         "album": "Album",
         "path": "File path",
         "libraryName": "Library",
@@ -387,6 +388,8 @@
       },
       "messages": {
         "configHelp": "Configure the plugin using key-value pairs. Leave empty if the plugin requires no configuration.",
+        "configValidationError": "Configuration validation failed:",
+        "schemaRenderError": "Unable to render configuration form. The plugin's schema may be invalid.",
         "clickPermissions": "Click a permission for details",
         "noConfig": "No configuration set",
         "allUsersHelp": "When enabled, the plugin will have access to all users, including those created in the future.",

ui/src/layout/UserMenu.jsx

@@ -28,6 +28,9 @@ import { useDispatch } from 'react-redux'
 
 const useStyles = makeStyles((theme) => ({
   user: {},
+  button: {
+    color: 'inherit',
+  },
   avatar: {
     width: theme.spacing(4),
     height: theme.spacing(4),
@@ -72,12 +75,11 @@ const UserMenu = (props) => {
     <div className={classes.user}>
       <Tooltip title={label && translate(label, { _: label })}>
         <IconButton
+          className={classes.button}
           aria-label={label && translate(label, { _: label })}
           aria-owns={open ? 'menu-appbar' : null}
           aria-haspopup={true}
-          color="inherit"
           onClick={handleMenu}
-          size={'small'}
         >
           {loaded && identity.avatar ? (
             <Avatar

ui/src/playlist/PlaylistEdit.jsx

@@ -34,7 +34,15 @@ const PlaylistEditForm = (props) => {
   return (
     <SimpleForm redirect="list" variant={'outlined'} {...props}>
       <TextInput source="name" validate={required()} />
-      <TextInput multiline source="comment" />
+      <TextInput
+        multiline
+        minRows={3}
+        source="comment"
+        fullWidth
+        inputProps={{
+          style: { resize: 'vertical' },
+        }}
+      />
       {permissions === 'admin' ? (
         <ReferenceInput
           source="ownerId"

ui/src/plugin/AlwaysExpandedArrayLayout.jsx

@@ -0,0 +1,276 @@
+import React, { useCallback, useMemo } from 'react'
+import {
+  composePaths,
+  computeLabel,
+  createDefaultValue,
+  isObjectArrayWithNesting,
+  isPrimitiveArrayControl,
+  rankWith,
+  findUISchema,
+  Resolve,
+} from '@jsonforms/core'
+import {
+  JsonFormsDispatch,
+  withJsonFormsArrayLayoutProps,
+} from '@jsonforms/react'
+import range from 'lodash/range'
+import merge from 'lodash/merge'
+import { Box, IconButton, Tooltip, Typography } from '@material-ui/core'
+import { Add, Delete } from '@material-ui/icons'
+import { makeStyles } from '@material-ui/core/styles'
+
+const useStyles = makeStyles((theme) => ({
+  arrayItem: {
+    position: 'relative',
+    padding: theme.spacing(2),
+    marginBottom: theme.spacing(2),
+    border: `1px solid ${theme.palette.divider}`,
+    borderRadius: theme.shape.borderRadius,
+    '&:last-child': {
+      marginBottom: 0,
+    },
+  },
+  deleteButton: {
+    position: 'absolute',
+    top: theme.spacing(1),
+    right: theme.spacing(1),
+  },
+  itemContent: {
+    paddingRight: theme.spacing(4), // Space for delete button
+  },
+}))
+
+// Default translations for array controls
+const defaultTranslations = {
+  addTooltip: 'Add',
+  addAriaLabel: 'Add button',
+  removeTooltip: 'Delete',
+  removeAriaLabel: 'Delete button',
+  noDataMessage: 'No data',
+}
+
+// Simplified array item renderer - clean card layout
+// eslint-disable-next-line react-refresh/only-export-components
+const ArrayItem = ({
+  index,
+  path,
+  schema,
+  uischema,
+  uischemas,
+  rootSchema,
+  renderers,
+  cells,
+  enabled,
+  removeItems,
+  translations,
+  disableRemove,
+}) => {
+  const classes = useStyles()
+  const childPath = composePaths(path, `${index}`)
+
+  const foundUISchema = useMemo(
+    () =>
+      findUISchema(
+        uischemas,
+        schema,
+        uischema.scope,
+        path,
+        undefined,
+        uischema,
+        rootSchema,
+      ),
+    [uischemas, schema, path, uischema, rootSchema],
+  )
+
+  return (
+    <Box className={classes.arrayItem}>
+      {enabled && !disableRemove && (
+        <Tooltip
+          title={translations.removeTooltip}
+          className={classes.deleteButton}
+        >
+          <IconButton
+            onClick={() => removeItems(path, [index])()}
+            size="small"
+            aria-label={translations.removeAriaLabel}
+          >
+            <Delete fontSize="small" />
+          </IconButton>
+        </Tooltip>
+      )}
+      <Box className={classes.itemContent}>
+        <JsonFormsDispatch
+          enabled={enabled}
+          schema={schema}
+          uischema={foundUISchema}
+          path={childPath}
+          key={childPath}
+          renderers={renderers}
+          cells={cells}
+        />
+      </Box>
+    </Box>
+  )
+}
+
+// Array toolbar with add button
+// eslint-disable-next-line react-refresh/only-export-components
+const ArrayToolbar = ({
+  label,
+  description,
+  enabled,
+  addItem,
+  path,
+  createDefault,
+  translations,
+  disableAdd,
+}) => (
+  <Box mb={1}>
+    <Box display="flex" alignItems="center" justifyContent="space-between">
+      <Typography variant="h6">{label}</Typography>
+      {!disableAdd && (
+        <Tooltip
+          title={translations.addTooltip}
+          aria-label={translations.addAriaLabel}
+        >
+          <IconButton
+            onClick={addItem(path, createDefault())}
+            disabled={!enabled}
+            size="small"
+          >
+            <Add />
+          </IconButton>
+        </Tooltip>
+      )}
+    </Box>
+    {description && (
+      <Typography variant="caption" color="textSecondary">
+        {description}
+      </Typography>
+    )}
+  </Box>
+)
+
+const useArrayStyles = makeStyles((theme) => ({
+  container: {
+    marginBottom: theme.spacing(2),
+  },
+}))
+
+// Main array layout component - items always expanded
+// eslint-disable-next-line react-refresh/only-export-components
+const AlwaysExpandedArrayLayoutComponent = (props) => {
+  const arrayClasses = useArrayStyles()
+  const {
+    enabled,
+    data,
+    path,
+    schema,
+    uischema,
+    addItem,
+    removeItems,
+    renderers,
+    cells,
+    label,
+    description,
+    required,
+    rootSchema,
+    config,
+    uischemas,
+    disableAdd,
+    disableRemove,
+  } = props
+
+  const innerCreateDefaultValue = useCallback(
+    () => createDefaultValue(schema, rootSchema),
+    [schema, rootSchema],
+  )
+
+  const appliedUiSchemaOptions = merge({}, config, uischema.options)
+  const doDisableAdd = disableAdd || appliedUiSchemaOptions.disableAdd
+  const doDisableRemove = disableRemove || appliedUiSchemaOptions.disableRemove
+  const translations = defaultTranslations
+
+  return (
+    <div className={arrayClasses.container}>
+      <ArrayToolbar
+        translations={translations}
+        label={computeLabel(
+          label,
+          required,
+          appliedUiSchemaOptions.hideRequiredAsterisk,
+        )}
+        description={description}
+        path={path}
+        enabled={enabled}
+        addItem={addItem}
+        createDefault={innerCreateDefaultValue}
+        disableAdd={doDisableAdd}
+      />
+      <div>
+        {data > 0 ? (
+          range(data).map((index) => (
+            <ArrayItem
+              key={index}
+              index={index}
+              path={path}
+              schema={schema}
+              uischema={uischema}
+              uischemas={uischemas}
+              rootSchema={rootSchema}
+              renderers={renderers}
+              cells={cells}
+              enabled={enabled}
+              removeItems={removeItems}
+              translations={translations}
+              disableRemove={doDisableRemove}
+            />
+          ))
+        ) : (
+          <Typography color="textSecondary">
+            {translations.noDataMessage}
+          </Typography>
+        )}
+      </div>
+    </div>
+  )
+}
+
+// Wrap with JSONForms HOC
+const WrappedArrayLayout = withJsonFormsArrayLayoutProps(
+  AlwaysExpandedArrayLayoutComponent,
+)
+
+// Custom tester that matches arrays but NOT enum arrays
+// Enum arrays should be handled by MaterialEnumArrayRenderer (for checkboxes)
+const isNonEnumArrayControl = (uischema, schema) => {
+  // First check if it matches our base conditions (object array or primitive array)
+  const baseCheck =
+    isObjectArrayWithNesting(uischema, schema) ||
+    isPrimitiveArrayControl(uischema, schema)
+
+  if (!baseCheck) {
+    return false
+  }
+
+  // Resolve the actual schema for this control using JSONForms utility
+  const rootSchema = schema
+  const resolved = Resolve.schema(rootSchema, uischema?.scope, rootSchema)
+
+  // Exclude enum arrays (uniqueItems + oneOf/enum) - let MaterialEnumArrayRenderer handle them
+  if (resolved?.uniqueItems && resolved?.items) {
+    const { items } = resolved
+    if (items.oneOf?.every((e) => e.const !== undefined) || items.enum) {
+      return false
+    }
+  }
+
+  return true
+}
+
+// Export as a renderer entry with high priority (5 > default 4)
+// Matches both object arrays with nesting and primitive arrays, but NOT enum arrays
+export const AlwaysExpandedArrayLayout = {
+  tester: rankWith(5, isNonEnumArrayControl),
+  renderer: WrappedArrayLayout,
+}

ui/src/plugin/ConfigCard.jsx

@@ -1,55 +1,119 @@
-import React, { useCallback } from 'react'
-import {
-  Card,
-  CardContent,
-  Typography,
-  TextField as MuiTextField,
-  Table,
-  TableBody,
-  TableCell,
-  TableContainer,
-  TableHead,
-  TableRow,
-  IconButton,
-  Paper,
-} from '@material-ui/core'
-import { MdDelete } from 'react-icons/md'
+import React, { useCallback, useState, useMemo } from 'react'
+import PropTypes from 'prop-types'
+import { Card, CardContent, Typography, Box } from '@material-ui/core'
+import Alert from '@material-ui/lab/Alert'
+import { SchemaConfigEditor } from './SchemaConfigEditor'
+
+// Navigate schema by path parts to find the title for a field
+const findFieldTitle = (schema, parts) => {
+  let currentSchema = schema
+  let fieldName = parts[parts.length - 1] // Default to last part
+
+  for (const part of parts) {
+    if (!currentSchema) break
+
+    // Skip array indices (just move to items schema)
+    if (/^\d+$/.test(part)) {
+      if (currentSchema.items) {
+        currentSchema = currentSchema.items
+      }
+      continue
+    }
+
+    // Navigate to property and always update fieldName
+    if (currentSchema.properties?.[part]) {
+      const propSchema = currentSchema.properties[part]
+      fieldName = propSchema.title || part
+      currentSchema = propSchema
+    }
+  }
+
+  return fieldName
+}
+
+// Extract human-readable field name from JSONForms error
+const getFieldName = (error, schema) => {
+  // JSONForms errors can have different path formats:
+  // - dataPath: "users.1.token" (dot-separated)
+  // - instancePath: "/users/1/token" (slash-separated)
+  // - property: "users.1.username" (dot-separated)
+  const dataPath = error.dataPath || ''
+  const instancePath = error.instancePath || ''
+  const property = error.property || ''
+
+  // Try dataPath first (dot-separated like "users.1.token")
+  if (dataPath) {
+    const parts = dataPath.split('.').filter(Boolean)
+    if (parts.length > 0) {
+      return findFieldTitle(schema, parts)
+    }
+  }
+
+  // Try property (also dot-separated)
+  if (property) {
+    const parts = property.split('.').filter(Boolean)
+    if (parts.length > 0) {
+      return findFieldTitle(schema, parts)
+    }
+  }
+
+  // Fall back to instancePath (slash-separated like "/users/1/token")
+  if (instancePath) {
+    const parts = instancePath.split('/').filter(Boolean)
+    if (parts.length > 0) {
+      return findFieldTitle(schema, parts)
+    }
+  }
+
+  // Try to extract from schemaPath like "#/properties/users/items/properties/username/minLength"
+  const schemaPath = error.schemaPath || ''
+  const propMatches = [...schemaPath.matchAll(/\/properties\/([^/]+)/g)]
+  if (propMatches.length > 0) {
+    const parts = propMatches.map((m) => m[1])
+    return findFieldTitle(schema, parts)
+  }
+
+  return null
+}
 
 export const ConfigCard = ({
-  configPairs,
-  onConfigPairsChange,
+  manifest,
+  configData,
+  onConfigDataChange,
   classes,
   translate,
 }) => {
-  const handleKeyChange = useCallback(
-    (index, newKey) => {
-      const newPairs = [...configPairs]
-      newPairs[index] = { ...newPairs[index], key: newKey }
-      onConfigPairsChange(newPairs)
+  const [validationErrors, setValidationErrors] = useState([])
+
+  // Handle changes from JSONForms
+  const handleChange = useCallback(
+    (newData, errors) => {
+      setValidationErrors(errors || [])
+      onConfigDataChange(newData, errors)
     },
-    [configPairs, onConfigPairsChange],
+    [onConfigDataChange],
   )
 
-  const handleValueChange = useCallback(
-    (index, newValue) => {
-      const newPairs = [...configPairs]
-      newPairs[index] = { ...newPairs[index], value: newValue }
-      onConfigPairsChange(newPairs)
-    },
-    [configPairs, onConfigPairsChange],
-  )
+  // Only show config card if manifest has config schema defined
+  const hasConfigSchema = manifest?.config?.schema
 
-  const handleDeleteRow = useCallback(
-    (index) => {
-      const newPairs = configPairs.filter((_, i) => i !== index)
-      onConfigPairsChange(newPairs)
-    },
-    [configPairs, onConfigPairsChange],
-  )
+  // Format validation errors with proper field names
+  const formattedErrors = useMemo(() => {
+    if (!hasConfigSchema) {
+      return []
+    }
+    const { schema } = manifest.config
+    return validationErrors.map((error) => ({
+      fieldName: getFieldName(error, schema),
+      message: error.message,
+    }))
+  }, [validationErrors, manifest, hasConfigSchema])
 
-  const handleAddRow = useCallback(() => {
-    onConfigPairsChange([...configPairs, { key: '', value: '' }])
-  }, [configPairs, onConfigPairsChange])
+  if (!hasConfigSchema) {
+    return null
+  }
+
+  const { schema, uiSchema } = manifest.config
 
   return (
     <Card className={classes.section}>
@@ -57,95 +121,44 @@ export const ConfigCard = ({
         <Typography variant="h6" className={classes.sectionTitle}>
           {translate('resources.plugin.sections.configuration')}
         </Typography>
-        <Typography variant="body2" color="textSecondary" gutterBottom>
-          {translate('resources.plugin.messages.configHelp')}
-        </Typography>
 
-        <TableContainer component={Paper} variant="outlined">
-          <Table size="small" className={classes.configTable}>
-            <TableHead>
-              <TableRow>
-                <TableCell width="40%">
-                  {translate('resources.plugin.fields.configKey')}
-                </TableCell>
-                <TableCell width="50%">
-                  {translate('resources.plugin.fields.configValue')}
-                </TableCell>
-                <TableCell width="10%" align="right">
-                  <IconButton
-                    size="small"
-                    onClick={handleAddRow}
-                    aria-label={translate('resources.plugin.actions.addConfig')}
-                    className={classes.configActionIconButton}
-                  >
-                    +
-                  </IconButton>
-                </TableCell>
-              </TableRow>
-            </TableHead>
-            <TableBody>
-              {configPairs.map((pair, index) => (
-                <TableRow key={index}>
-                  <TableCell>
-                    <MuiTextField
-                      fullWidth
-                      size="small"
-                      variant="outlined"
-                      value={pair.key}
-                      onChange={(e) => handleKeyChange(index, e.target.value)}
-                      placeholder={translate(
-                        'resources.plugin.placeholders.configKey',
-                      )}
-                      InputProps={{
-                        className: classes.configTableInput,
-                      }}
-                    />
-                  </TableCell>
-                  <TableCell>
-                    <MuiTextField
-                      fullWidth
-                      size="small"
-                      variant="outlined"
-                      multiline
-                      minRows={1}
-                      value={pair.value}
-                      onChange={(e) => handleValueChange(index, e.target.value)}
-                      placeholder={translate(
-                        'resources.plugin.placeholders.configValue',
-                      )}
-                      InputProps={{
-                        className: classes.configTableInput,
-                      }}
-                      inputProps={{
-                        style: { resize: 'vertical' },
-                      }}
-                    />
-                  </TableCell>
-                  <TableCell align="right">
-                    <IconButton
-                      size="small"
-                      onClick={() => handleDeleteRow(index)}
-                      aria-label={translate('ra.action.delete')}
-                      className={classes.configActionIconButton}
-                    >
-                      <MdDelete />
-                    </IconButton>
-                  </TableCell>
-                </TableRow>
-              ))}
-              {configPairs.length === 0 && (
-                <TableRow>
-                  <TableCell colSpan={3} align="center">
-                    <Typography variant="body2" color="textSecondary">
-                      {translate('resources.plugin.messages.noConfig')}
-                    </Typography>
-                  </TableCell>
-                </TableRow>
-              )}
-            </TableBody>
-          </Table>
-        </TableContainer>
+        {formattedErrors.length > 0 && (
+          <Box mb={2}>
+            <Alert severity="error">
+              {translate('resources.plugin.messages.configValidationError')}
+              <ul style={{ margin: '8px 0 0', paddingLeft: 20 }}>
+                {formattedErrors.map((error, index) => (
+                  <li key={index}>
+                    {error.fieldName && <strong>{error.fieldName}</strong>}
+                    {error.fieldName && ': '}
+                    {error.message}
+                  </li>
+                ))}
+              </ul>
+            </Alert>
+          </Box>
+        )}
+
+        <SchemaConfigEditor
+          schema={schema}
+          uiSchema={uiSchema}
+          data={configData}
+          onChange={handleChange}
+        />
       </CardContent>
     </Card>
   )
 }
+
+ConfigCard.propTypes = {
+  manifest: PropTypes.shape({
+    config: PropTypes.shape({
+      schema: PropTypes.object,
+      uiSchema: PropTypes.object,
+    }),
+  }),
+  configData: PropTypes.object,
+  onConfigDataChange: PropTypes.func.isRequired,
+  classes: PropTypes.object.isRequired,
+  translate: PropTypes.func.isRequired,
+}

ui/src/plugin/OutlinedRenderers.jsx

@@ -0,0 +1,257 @@
+/* eslint-disable react-refresh/only-export-components */
+import React, { useState } from 'react'
+import {
+  rankWith,
+  isStringControl,
+  isIntegerControl,
+  isNumberControl,
+  isEnumControl,
+  isOneOfEnumControl,
+  and,
+  not,
+  or,
+  optionIs,
+  isDescriptionHidden,
+} from '@jsonforms/core'
+import {
+  withJsonFormsControlProps,
+  withJsonFormsEnumProps,
+  withJsonFormsOneOfEnumProps,
+} from '@jsonforms/react'
+import {
+  TextField,
+  FormControl,
+  FormHelperText,
+  InputLabel,
+  Select,
+  MenuItem,
+} from '@material-ui/core'
+import { makeStyles } from '@material-ui/core/styles'
+import merge from 'lodash/merge'
+
+const useStyles = makeStyles(
+  (theme) => ({
+    control: {
+      marginBottom: theme.spacing(2),
+    },
+  }),
+  { name: 'NDOutlinedRenderers' },
+)
+
+/**
+ * Hook for common control state (focus, validation, description visibility)
+ * Tracks "touched" state to only show errors after the user has interacted with the field
+ */
+const useControlState = (props) => {
+  const { config, uischema, description, visible, errors } = props
+  const [isFocused, setIsFocused] = useState(false)
+  const [isTouched, setIsTouched] = useState(false)
+
+  const appliedUiSchemaOptions = merge({}, config, uischema?.options)
+  // errors is a string when there are validation errors, empty/undefined when valid
+  const hasErrors = errors && errors.length > 0
+  // Only show as invalid after the field has been touched (blurred)
+  const showError = isTouched && hasErrors
+
+  const showDescription = !isDescriptionHidden(
+    visible,
+    description,
+    isFocused,
+    appliedUiSchemaOptions.showUnfocusedDescription,
+  )
+
+  const helperText = showError ? errors : showDescription ? description : ''
+
+  const handleFocus = () => setIsFocused(true)
+  const handleBlur = () => {
+    setIsFocused(false)
+    setIsTouched(true)
+  }
+
+  return {
+    isFocused,
+    appliedUiSchemaOptions,
+    showError,
+    helperText,
+    handleFocus,
+    handleBlur,
+  }
+}
+
+/**
+ * Base outlined control component that uses TextField with outlined variant
+ * instead of the default Input component used by JSONForms 2.x
+ */
+const OutlinedControl = (props) => {
+  const classes = useStyles()
+  const {
+    data,
+    id,
+    enabled,
+    label,
+    visible,
+    type = 'text',
+    inputProps: extraInputProps = {},
+    onChange,
+  } = props
+
+  const {
+    appliedUiSchemaOptions,
+    showError,
+    helperText,
+    handleFocus,
+    handleBlur,
+  } = useControlState(props)
+
+  if (!visible) {
+    return null
+  }
+
+  return (
+    <TextField
+      id={id}
+      label={label}
+      type={type}
+      value={data ?? ''}
+      onChange={onChange}
+      onFocus={handleFocus}
+      onBlur={handleBlur}
+      disabled={!enabled}
+      autoFocus={appliedUiSchemaOptions.focus}
+      multiline={type === 'text' && appliedUiSchemaOptions.multi}
+      rows={appliedUiSchemaOptions.multi ? 3 : undefined}
+      variant="outlined"
+      fullWidth
+      size="small"
+      error={showError}
+      helperText={helperText}
+      inputProps={extraInputProps}
+      className={classes.control}
+    />
+  )
+}
+
+// Text control wrapper
+const OutlinedTextControl = (props) => {
+  const { path, handleChange, schema, config, uischema } = props
+  const appliedUiSchemaOptions = merge({}, config, uischema?.options)
+
+  const inputProps = {}
+  if (appliedUiSchemaOptions.restrict && schema?.maxLength) {
+    inputProps.maxLength = schema.maxLength
+  }
+
+  return (
+    <OutlinedControl
+      {...props}
+      type={appliedUiSchemaOptions.format === 'password' ? 'password' : 'text'}
+      inputProps={inputProps}
+      onChange={(ev) => handleChange(path, ev.target.value)}
+    />
+  )
+}
+
+// Number control wrapper
+const OutlinedNumberControl = (props) => {
+  const { path, handleChange, schema } = props
+  const { minimum, maximum } = schema || {}
+
+  const inputProps = {}
+  if (minimum !== undefined) inputProps.min = minimum
+  if (maximum !== undefined) inputProps.max = maximum
+
+  const handleNumberChange = (ev) => {
+    const value = ev.target.value
+    if (value === '') {
+      handleChange(path, undefined)
+    } else {
+      const numValue = Number(value)
+      if (!isNaN(numValue)) {
+        handleChange(path, numValue)
+      }
+    }
+  }
+
+  return (
+    <OutlinedControl
+      {...props}
+      type="number"
+      inputProps={inputProps}
+      onChange={handleNumberChange}
+    />
+  )
+}
+
+// Enum/Select control wrapper
+const OutlinedEnumControl = (props) => {
+  const classes = useStyles()
+  const { data, id, enabled, path, handleChange, options, label, visible } =
+    props
+  const {
+    appliedUiSchemaOptions,
+    showError,
+    helperText,
+    handleFocus,
+    handleBlur,
+  } = useControlState(props)
+
+  if (!visible) {
+    return null
+  }
+
+  return (
+    <FormControl
+      fullWidth
+      variant="outlined"
+      size="small"
+      error={showError}
+      className={classes.control}
+    >
+      <InputLabel id={`${id}-label`}>{label}</InputLabel>
+      <Select
+        labelId={`${id}-label`}
+        id={id}
+        value={data ?? ''}
+        onChange={(ev) => handleChange(path, ev.target.value)}
+        onFocus={handleFocus}
+        onBlur={handleBlur}
+        disabled={!enabled}
+        autoFocus={appliedUiSchemaOptions.focus}
+        label={label}
+        fullWidth
+      >
+        <MenuItem value="">
+          <em>None</em>
+        </MenuItem>
+        {options?.map((option) => (
+          <MenuItem key={option.value} value={option.value}>
+            {option.label}
+          </MenuItem>
+        ))}
+      </Select>
+      {helperText && <FormHelperText>{helperText}</FormHelperText>}
+    </FormControl>
+  )
+}
+
+// Testers - higher rank than default to override default renderers
+// Enum renderers have highest rank since isStringControl also matches enum fields
+export const OutlinedEnumRenderer = {
+  tester: rankWith(5, isEnumControl),
+  renderer: withJsonFormsEnumProps(OutlinedEnumControl),
+}
+
+export const OutlinedOneOfEnumRenderer = {
+  tester: rankWith(5, isOneOfEnumControl),
+  renderer: withJsonFormsOneOfEnumProps(OutlinedEnumControl),
+}
+
+export const OutlinedTextRenderer = {
+  tester: rankWith(3, and(isStringControl, not(optionIs('format', 'radio')))),
+  renderer: withJsonFormsControlProps(OutlinedTextControl),
+}
+
+export const OutlinedNumberRenderer = {
+  tester: rankWith(3, or(isIntegerControl, isNumberControl)),
+  renderer: withJsonFormsControlProps(OutlinedNumberControl),
+}

ui/src/plugin/PluginShow.jsx

@@ -33,9 +33,11 @@ const PluginShowLayout = () => {
   const isSmall = useMediaQuery((theme) => theme.breakpoints.down('xs'))
   useResourceRefresh('plugin')
 
-  const [configPairs, setConfigPairs] = useState([])
+  const [configData, setConfigData] = useState({})
+  const [configErrors, setConfigErrors] = useState([])
   const [isDirty, setIsDirty] = useState(false)
   const [lastRecordConfig, setLastRecordConfig] = useState(null)
+  const [isConfigInitialized, setIsConfigInitialized] = useState(false)
 
   // Users permission state
   const [selectedUsers, setSelectedUsers] = useState([])
@@ -49,41 +51,26 @@ const PluginShowLayout = () => {
   const [lastRecordLibraries, setLastRecordLibraries] = useState(null)
   const [lastRecordAllLibraries, setLastRecordAllLibraries] = useState(null)
 
-  // Convert JSON config to key-value pairs
-  const jsonToPairs = useCallback((jsonString) => {
-    if (!jsonString || jsonString.trim() === '') return []
+  // Parse JSON config to object
+  const jsonToObject = useCallback((jsonString) => {
+    if (!jsonString || jsonString.trim() === '') return {}
     try {
-      const obj = JSON.parse(jsonString)
-      return Object.entries(obj).map(([key, value]) => ({
-        key,
-        value: typeof value === 'string' ? value : JSON.stringify(value),
-      }))
+      return JSON.parse(jsonString)
     } catch {
-      return []
+      return {}
     }
   }, [])
 
-  // Convert key-value pairs to JSON config
-  const pairsToJson = useCallback((pairs) => {
-    if (pairs.length === 0) return ''
-    const obj = {}
-    pairs.forEach((pair) => {
-      if (pair.key.trim()) {
-        // Always store values as strings (backend expects map[string]string)
-        obj[pair.key] = pair.value
-      }
-    })
-    return JSON.stringify(obj)
-  }, [])
-
   // Initialize/update config when record loads or changes (e.g., from SSE refresh)
   React.useEffect(() => {
     const recordConfig = record?.config || ''
     if (record && recordConfig !== lastRecordConfig && !isDirty) {
-      setConfigPairs(jsonToPairs(recordConfig))
+      setConfigData(jsonToObject(recordConfig))
       setLastRecordConfig(recordConfig)
+      // Reset initialization flag - AJV will apply defaults on first render
+      setIsConfigInitialized(false)
     }
-  }, [record, lastRecordConfig, isDirty, jsonToPairs])
+  }, [record, lastRecordConfig, isDirty, jsonToObject])
 
   // Initialize/update users permission state when record loads or changes
   React.useEffect(() => {
@@ -131,10 +118,19 @@ const PluginShowLayout = () => {
     }
   }, [record, lastRecordLibraries, lastRecordAllLibraries, isDirty])
 
-  const handleConfigPairsChange = useCallback((newPairs) => {
-    setConfigPairs(newPairs)
-    setIsDirty(true)
-  }, [])
+  const handleConfigDataChange = useCallback(
+    (newData, errors) => {
+      setConfigData(newData)
+      setConfigErrors(errors || [])
+      // Skip marking dirty on initial onChange (when AJV applies defaults)
+      if (isConfigInitialized) {
+        setIsDirty(true)
+      } else {
+        setIsConfigInitialized(true)
+      }
+    },
+    [isConfigInitialized],
+  )
 
   const handleSelectedUsersChange = useCallback((newSelectedUsers) => {
     setSelectedUsers(newSelectedUsers)
@@ -184,18 +180,23 @@ const PluginShowLayout = () => {
 
   const handleSaveConfig = useCallback(() => {
     if (!record) return
-    const config = pairsToJson(configPairs)
-    const data = { config }
+    const parsedManifest = record.manifest ? JSON.parse(record.manifest) : null
+    const data = {}
+
+    // Only include config if the plugin has a config schema
+    if (parsedManifest?.config?.schema) {
+      data.config =
+        Object.keys(configData).length > 0 ? JSON.stringify(configData) : ''
+    }
 
     // Include users data if users permission is present
-    const manifest = record.manifest ? JSON.parse(record.manifest) : null
-    if (manifest?.permissions?.users) {
+    if (parsedManifest?.permissions?.users) {
       data.users = JSON.stringify(selectedUsers)
       data.allUsers = allUsers
     }
 
     // Include libraries data if library permission is present
-    if (manifest?.permissions?.library) {
+    if (parsedManifest?.permissions?.library) {
       data.libraries = JSON.stringify(selectedLibraries)
       data.allLibraries = allLibraries
     }
@@ -204,8 +205,7 @@ const PluginShowLayout = () => {
   }, [
     updatePlugin,
     record,
-    configPairs,
-    pairsToJson,
+    configData,
     selectedUsers,
     allUsers,
     selectedLibraries,
@@ -273,8 +273,9 @@ const PluginShowLayout = () => {
         />
 
         <ConfigCard
-          configPairs={configPairs}
-          onConfigPairsChange={handleConfigPairsChange}
+          manifest={manifest}
+          configData={configData}
+          onConfigDataChange={handleConfigDataChange}
           classes={classes}
           translate={translate}
         />
@@ -303,7 +304,7 @@ const PluginShowLayout = () => {
             color="primary"
             startIcon={<MdSave />}
             onClick={handleSaveConfig}
-            disabled={!isDirty || loading}
+            disabled={!isDirty || loading || configErrors.length > 0}
             className={classes.saveButton}
           >
             {translate('ra.action.save')}

ui/src/plugin/SchemaConfigEditor.jsx

@@ -0,0 +1,241 @@
+import React, { useCallback, useEffect, useMemo, useRef } from 'react'
+import PropTypes from 'prop-types'
+import { JsonForms } from '@jsonforms/react'
+import { materialRenderers, materialCells } from '@jsonforms/material-renderers'
+import { makeStyles } from '@material-ui/core/styles'
+import { Typography } from '@material-ui/core'
+import { useTranslate } from 'react-admin'
+import Ajv from 'ajv'
+import { AlwaysExpandedArrayLayout } from './AlwaysExpandedArrayLayout'
+import {
+  OutlinedTextRenderer,
+  OutlinedNumberRenderer,
+  OutlinedEnumRenderer,
+  OutlinedOneOfEnumRenderer,
+} from './OutlinedRenderers'
+
+// Error boundary for catching JSONForms rendering errors
+class SchemaErrorBoundary extends React.Component {
+  constructor(props) {
+    super(props)
+    this.state = { hasError: false, error: null }
+  }
+
+  static getDerivedStateFromError(error) {
+    return { hasError: true, error }
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return this.props.fallback(this.state.error)
+    }
+    return this.props.children
+  }
+}
+
+SchemaErrorBoundary.propTypes = {
+  children: PropTypes.node.isRequired,
+  fallback: PropTypes.func.isRequired,
+}
+
+// Custom AJV instance that fixes "required" error paths for JSONForms.
+// AJV outputs required errors pointing to the parent (e.g., "/users/1") with
+// params.missingProperty. We transform them to point to the field directly
+// (e.g., "/users/1/username") so JSONForms displays them under the correct input.
+const ajv = new Ajv({
+  useDefaults: true,
+  allErrors: true,
+  verbose: true,
+  jsonPointers: true,
+})
+const origCompile = ajv.compile.bind(ajv)
+ajv.compile = (schema) => {
+  const validate = origCompile(schema)
+  const wrapped = (data) => {
+    const valid = validate(data)
+    validate.errors?.forEach((e) => {
+      if (e.keyword === 'required' && e.params?.missingProperty) {
+        e.dataPath = `${e.dataPath || ''}/${e.params.missingProperty}`
+      }
+    })
+    wrapped.errors = validate.errors
+    return valid
+  }
+  wrapped.schema = validate.schema
+  return wrapped
+}
+
+const useStyles = makeStyles(
+  (theme) => ({
+    root: {
+      '& .MuiFormControl-root': {
+        marginBottom: theme.spacing(2),
+      },
+      // Label elements (type: "Label" in UI schema) - make slightly smaller
+      '& .MuiTypography-h6': {
+        fontSize: '0.95rem',
+      },
+      // Group/array styling
+      '& .MuiPaper-root': {
+        backgroundColor: 'transparent',
+      },
+      // Array items styling
+      '& .MuiAccordion-root': {
+        marginBottom: theme.spacing(1),
+        '&:before': {
+          display: 'none',
+        },
+      },
+      '& .MuiAccordionSummary-root': {
+        backgroundColor:
+          theme.palette.type === 'dark'
+            ? theme.palette.grey[800]
+            : theme.palette.grey[100],
+        // Hide expand icon - items are always expanded
+        '& .MuiAccordionSummary-expandIcon': {
+          display: 'none',
+        },
+      },
+      // Checkbox/switch styling
+      '& .MuiCheckbox-root, & .MuiSwitch-root': {
+        color: theme.palette.text.secondary,
+      },
+      '& .Mui-checked': {
+        color: theme.palette.primary.main,
+      },
+    },
+    errorContainer: {
+      padding: theme.spacing(2),
+      backgroundColor:
+        theme.palette.type === 'dark'
+          ? 'rgba(244, 67, 54, 0.1)'
+          : 'rgba(244, 67, 54, 0.05)',
+      borderRadius: theme.shape.borderRadius,
+      border: `1px solid ${theme.palette.error.main}`,
+    },
+    errorMessage: {
+      color: theme.palette.error.main,
+      marginBottom: theme.spacing(1),
+    },
+    errorDetails: {
+      color: theme.palette.text.secondary,
+      fontSize: '0.85em',
+      fontFamily: 'monospace',
+      whiteSpace: 'pre-wrap',
+      wordBreak: 'break-word',
+    },
+  }),
+  { name: 'NDSchemaConfigEditor' },
+)
+
+// Custom renderers with outlined text inputs and always-expanded array layout
+const customRenderers = [
+  // Put our custom renderers first (higher priority)
+  OutlinedTextRenderer,
+  OutlinedNumberRenderer,
+  OutlinedEnumRenderer,
+  OutlinedOneOfEnumRenderer,
+  AlwaysExpandedArrayLayout,
+  // Then all the standard material renderers
+  ...materialRenderers,
+]
+
+export const SchemaConfigEditor = ({
+  schema,
+  uiSchema,
+  data,
+  onChange,
+  readOnly = false,
+}) => {
+  const classes = useStyles()
+  const translate = useTranslate()
+  const containerRef = useRef(null)
+
+  // Disable browser autocomplete on all inputs
+  useEffect(() => {
+    if (!containerRef.current) return
+
+    const disableAutocomplete = () => {
+      const inputs = containerRef.current.querySelectorAll('input')
+      inputs.forEach((input) => {
+        input.setAttribute('autocomplete', 'off')
+      })
+    }
+
+    // Run immediately and observe for changes (new inputs added)
+    disableAutocomplete()
+    const observer = new MutationObserver(disableAutocomplete)
+    observer.observe(containerRef.current, { childList: true, subtree: true })
+
+    return () => observer.disconnect()
+  }, [data])
+
+  // Memoize the change handler to extract just the data
+  const handleChange = useCallback(
+    ({ data: newData, errors }) => {
+      if (onChange) {
+        onChange(newData, errors)
+      }
+    },
+    [onChange],
+  )
+
+  // Use custom renderers with always-expanded array layout
+  const renderers = useMemo(() => customRenderers, [])
+  const cells = useMemo(() => materialCells, [])
+
+  // JSONForms config - always show descriptions
+  const config = {
+    showUnfocusedDescription: true,
+  }
+
+  // Ensure schema has required fields for JSONForms
+  const normalizedSchema = useMemo(() => {
+    if (!schema) return null
+    // JSONForms requires type to be set at root level
+    return {
+      type: 'object',
+      ...schema,
+    }
+  }, [schema])
+
+  if (!normalizedSchema) {
+    return null
+  }
+
+  const renderError = (error) => (
+    <div className={classes.errorContainer}>
+      <Typography className={classes.errorMessage}>
+        {translate('resources.plugin.messages.schemaRenderError')}
+      </Typography>
+      <Typography className={classes.errorDetails}>{error?.message}</Typography>
+    </div>
+  )
+
+  return (
+    <div ref={containerRef} className={classes.root}>
+      <SchemaErrorBoundary fallback={renderError}>
+        <JsonForms
+          schema={normalizedSchema}
+          uischema={uiSchema}
+          data={data || {}}
+          renderers={renderers}
+          cells={cells}
+          config={config}
+          onChange={handleChange}
+          readonly={readOnly}
+          ajv={ajv}
+          validationMode="ValidateAndShow"
+        />
+      </SchemaErrorBoundary>
+    </div>
+  )
+}
+
+SchemaConfigEditor.propTypes = {
+  schema: PropTypes.object,
+  uiSchema: PropTypes.object,
+  data: PropTypes.object,
+  onChange: PropTypes.func,
+  readOnly: PropTypes.bool,
+}

ui/src/plugin/SchemaConfigEditor.test.jsx

@@ -0,0 +1,86 @@
+import React from 'react'
+import { describe, it, expect, vi } from 'vitest'
+import { render } from '@testing-library/react'
+import { ThemeProvider, createTheme } from '@material-ui/core/styles'
+import { Provider } from 'react-redux'
+import { createStore } from 'redux'
+import { SchemaConfigEditor } from './SchemaConfigEditor'
+
+const theme = createTheme()
+
+// JSONForms requires Redux
+const mockStore = createStore(() => ({}))
+
+const renderWithProviders = (component) => {
+  return render(
+    <Provider store={mockStore}>
+      <ThemeProvider theme={theme}>{component}</ThemeProvider>
+    </Provider>,
+  )
+}
+
+describe('SchemaConfigEditor', () => {
+  const basicSchema = {
+    type: 'object',
+    properties: {
+      name: {
+        type: 'string',
+        title: 'Name',
+      },
+      enabled: {
+        type: 'boolean',
+        title: 'Enabled',
+      },
+    },
+  }
+
+  it('renders nothing when schema is null', () => {
+    const { container } = renderWithProviders(
+      <SchemaConfigEditor schema={null} data={{}} onChange={vi.fn()} />,
+    )
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('renders the component wrapper with valid schema', () => {
+    const { container } = renderWithProviders(
+      <SchemaConfigEditor schema={basicSchema} data={{}} onChange={vi.fn()} />,
+    )
+    // Check that the wrapper div is rendered (class name is generated)
+    expect(
+      container.querySelector('[class*="NDSchemaConfigEditor-root"]'),
+    ).toBeTruthy()
+  })
+
+  it('calls onChange on initial render', () => {
+    const onChange = vi.fn()
+    renderWithProviders(
+      <SchemaConfigEditor
+        schema={basicSchema}
+        data={{ name: 'Test' }}
+        onChange={onChange}
+      />,
+    )
+
+    // JSONForms calls onChange on initial render with initial state
+    expect(onChange).toHaveBeenCalled()
+  })
+
+  it('passes data and errors to onChange callback', () => {
+    const onChange = vi.fn()
+    const initialData = { name: 'Test Value' }
+
+    renderWithProviders(
+      <SchemaConfigEditor
+        schema={basicSchema}
+        data={initialData}
+        onChange={onChange}
+      />,
+    )
+
+    // Check that onChange was called with data and errors
+    expect(onChange).toHaveBeenCalledWith(
+      expect.objectContaining({ name: 'Test Value' }),
+      expect.any(Array),
+    )
+  })
+})

ui/src/plugin/ToggleEnabledSwitch.jsx

@@ -22,6 +22,15 @@ const useStyles = makeStyles((theme) => ({
         theme.palette.success?.main || theme.palette.primary.main,
     },
   },
+  errorSwitch: {
+    '& .MuiSwitch-thumb': {
+      backgroundColor: theme.palette.warning.main,
+    },
+    '& .MuiSwitch-track': {
+      backgroundColor: theme.palette.warning.light,
+      opacity: 0.7,
+    },
+  },
 }))
 
 /**
@@ -146,7 +155,7 @@ const ToggleEnabledSwitch = ({
       checked={record?.enabled ?? false}
       onClick={handleClick}
       disabled={isDisabled}
-      className={classes.enabledSwitch}
+      className={isDisabled ? classes.errorSwitch : classes.enabledSwitch}
       size={size}
       color="primary"
     />

ui/src/song/SongList.jsx

@@ -145,6 +145,7 @@ const SongList = (props) => {
     return {
       album: isDesktop && <AlbumLinkField source="album" sortByOrder={'ASC'} />,
       artist: <ArtistLinkField source="artist" />,
+      composer: <ArtistLinkField source="composer" />,
       albumArtist: <ArtistLinkField source="albumArtist" />,
       trackNumber: isDesktop && <NumberField source="trackNumber" />,
       playCount: isDesktop && (
@@ -192,6 +193,7 @@ const SongList = (props) => {
     resource: 'song',
     columns: toggleableFields,
     defaultOff: [
+      'composer',
       'channels',
       'bpm',
       'playDate',

ui/src/themes/index.js

@@ -12,6 +12,7 @@ import CatppuccinMacchiatoTheme from './catppuccinMacchiato'
 import NuclearTheme from './nuclear'
 import AmusicTheme from './amusic'
 import SquiddiesGlassTheme from './SquiddiesGlass'
+import NautilineTheme from './nautiline'
 
 export default {
   // Classic default themes
@@ -27,6 +28,7 @@ export default {
   GruvboxDarkTheme,
   LigeraTheme,
   MonokaiTheme,
+  NautilineTheme,
   NordTheme,
   NuclearTheme,
   SpotifyTheme,

ui/src/themes/nautiline.js

@@ -0,0 +1,905 @@
+/**
+ * Nautiline Theme for Navidrome
+ * Light theme inspired by the Nautiline iOS app
+ */
+
+// ============================================
+// CONFIGURATION
+// ============================================
+
+const ACCENT_COLOR = '#009688' // Material teal
+
+// ============================================
+// DESIGN TOKENS
+// ============================================
+
+const hexToRgb = (hex) => {
+  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex)
+  return result
+    ? {
+        r: parseInt(result[1], 16),
+        g: parseInt(result[2], 16),
+        b: parseInt(result[3], 16),
+      }
+    : null
+}
+
+const rgb = hexToRgb(ACCENT_COLOR)
+const rgba = (alpha) =>
+  rgb ? `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${alpha})` : 'transparent'
+
+const tokens = {
+  colors: {
+    accent: {
+      main: ACCENT_COLOR,
+      faded: rgba(0.1),
+      hover: rgba(0.15),
+    },
+    background: {
+      primary: '#FFFFFF',
+      secondary: '#F5F5F7',
+      tertiary: '#E5E5EA',
+    },
+    text: {
+      primary: '#1A1A1A',
+      secondary: '#8E8E93',
+      tertiary: '#AEAEB2',
+    },
+    ui: {
+      separator: 'rgba(0, 0, 0, 0.08)',
+      shadow: 'rgba(0, 0, 0, 0.04)',
+      glassBg: 'rgba(255, 255, 255, 0.72)',
+    },
+  },
+  typography: {
+    fontFamily: {
+      base: [
+        '-apple-system',
+        'BlinkMacSystemFont',
+        '"SF Pro Text"',
+        '"Helvetica Neue"',
+        'Arial',
+        'sans-serif',
+      ].join(','),
+      heading: '"Unbounded", sans-serif',
+    },
+    fontFace: `
+      @font-face {
+        font-family: 'Unbounded';
+        font-style: normal;
+        font-weight: 300 800;
+        font-display: swap;
+        src: url('/fonts/Unbounded-Variable.woff2') format('woff2');
+      }
+    `,
+  },
+  spacing: {
+    xs: '0.25rem',
+    sm: '0.5rem',
+    md: '0.75rem',
+    lg: '1rem',
+    xl: '1.5rem',
+  },
+  radii: {
+    sm: '0.25rem',
+    md: '0.5rem',
+    lg: '0.625rem',
+    xl: '0.75rem',
+    full: '50%',
+    pill: '1rem',
+  },
+  breakpoints: {
+    xs: 599,
+    sm: 600,
+    md: 720,
+    lg: 1280,
+  },
+  sizing: {
+    cover: {
+      sm: '14em',
+      lg: '18em',
+    },
+    icon: '1.25rem',
+    iconMinWidth: '2.5rem',
+  },
+  blur: '1.25rem',
+}
+
+const { colors, typography, spacing, radii, sizing, breakpoints } = tokens
+
+// ============================================
+// REUSABLE STYLE FACTORIES
+// ============================================
+
+const headingStyle = (weight, letterSpacing) => ({
+  fontFamily: typography.fontFamily.heading,
+  fontWeight: weight,
+  ...(letterSpacing && { letterSpacing }),
+})
+
+const coverSizing = () => ({
+  [`@media (min-width: ${breakpoints.sm}px)`]: {
+    height: sizing.cover.sm,
+    width: sizing.cover.sm,
+    minWidth: sizing.cover.sm,
+  },
+  [`@media (min-width: ${breakpoints.lg}px)`]: {
+    height: sizing.cover.lg,
+    width: sizing.cover.lg,
+    minWidth: sizing.cover.lg,
+  },
+})
+
+const customTooltipStyle = () => ({
+  display: 'inline',
+  position: 'absolute',
+  bottom: '100%',
+  left: '50%',
+  transform: 'translateX(-50%)',
+  marginBottom: spacing.xs,
+  fontSize: '0.75rem',
+  whiteSpace: 'nowrap',
+  backgroundColor: colors.text.primary,
+  color: colors.background.primary,
+  padding: `${spacing.xs} ${spacing.sm}`,
+  borderRadius: radii.sm,
+  zIndex: 9999,
+})
+
+const actionButtonsStyle = () => ({
+  padding: `${spacing.lg} 0`,
+  alignItems: 'center',
+  '@global': {
+    button: {
+      border: '1px solid transparent',
+      backgroundColor: colors.background.secondary,
+      color: colors.text.secondary,
+      margin: `0 ${spacing.sm}`,
+      borderRadius: radii.full,
+      minWidth: 0,
+      padding: spacing.lg,
+      position: 'relative',
+      '&:hover': {
+        backgroundColor: `${colors.background.tertiary} !important`,
+        border: '1px solid transparent',
+      },
+    },
+    'button:first-child:not(:only-child)': {
+      [`@media screen and (max-width: ${breakpoints.md}px)`]: {
+        transform: 'scale(1.5)',
+        margin: spacing.lg,
+        '&:hover': {
+          transform: 'scale(1.6) !important',
+        },
+      },
+      transform: 'scale(2)',
+      margin: spacing.xl,
+      minWidth: 0,
+      padding: '0.3125rem',
+      transition: 'transform .3s ease',
+      background: colors.accent.main,
+      color: '#fff',
+      borderRadius: radii.full,
+      border: 0,
+      '&:hover': {
+        transform: 'scale(2.1)',
+        backgroundColor: `${colors.accent.main} !important`,
+        border: 0,
+      },
+    },
+    'button:only-child': {
+      margin: spacing.xl,
+    },
+    'button:first-child>span:first-child': {
+      padding: 0,
+    },
+    'button>span:first-child>span': {
+      display: 'none',
+    },
+    'button:not(:first-child):hover>span:first-child>span':
+      customTooltipStyle(),
+    'button:not(:first-child)>span:first-child>svg': {
+      color: colors.text.secondary,
+    },
+  },
+})
+
+const menuIconStyle = () => ({
+  color: colors.text.primary,
+  minWidth: sizing.iconMinWidth,
+  '& svg': {
+    fontSize: sizing.icon,
+  },
+})
+
+const activeLinkStyle = {
+  color: `${colors.accent.main} !important`,
+  '& .MuiListItemIcon-root': {
+    color: `${colors.accent.main} !important`,
+  },
+}
+
+// ============================================
+// THEME DEFINITION
+// ============================================
+
+// Note: !important declarations are required to override react-admin and third-party component styles
+const NautilineTheme = {
+  themeName: 'Nautiline',
+  palette: {
+    type: 'light',
+    primary: {
+      main: colors.accent.main,
+      contrastText: '#FFFFFF',
+    },
+    secondary: {
+      main: colors.accent.main,
+      contrastText: '#FFFFFF',
+    },
+    background: {
+      default: colors.background.primary,
+      paper: colors.background.primary,
+    },
+    text: {
+      primary: colors.text.primary,
+      secondary: colors.text.secondary,
+    },
+    action: {
+      active: colors.accent.main,
+      hover: colors.accent.faded,
+      selected: colors.accent.faded,
+    },
+  },
+  typography: {
+    fontFamily: typography.fontFamily.base,
+    h1: headingStyle(700, '-0.02em'),
+    h2: headingStyle(700, '-0.02em'),
+    h3: headingStyle(600, '-0.01em'),
+    h4: headingStyle(600),
+    h5: headingStyle(600),
+    h6: headingStyle(600),
+    subtitle1: { fontWeight: 500 },
+    subtitle2: { fontWeight: 500 },
+    body1: { fontWeight: 400 },
+    body2: { fontWeight: 400 },
+    button: { fontWeight: 500, textTransform: 'none' },
+  },
+  shape: {
+    borderRadius: radii.xl,
+  },
+  overrides: {
+    MuiCssBaseline: {
+      '@global': {
+        '@font-face': {
+          fontFamily: 'Unbounded',
+          fontStyle: 'normal',
+          fontWeight: '300 800',
+          fontDisplay: 'swap',
+          src: "url('/fonts/Unbounded-Variable.woff2') format('woff2')",
+        },
+        body: {
+          backgroundColor: colors.background.primary,
+        },
+      },
+    },
+    MuiAppBar: {
+      root: {
+        boxShadow: 'none',
+        borderBottom: `1px solid ${colors.ui.separator}`,
+      },
+      colorSecondary: {
+        backgroundColor: colors.background.primary,
+        color: colors.text.primary,
+      },
+    },
+    MuiToolbar: {
+      root: {
+        backgroundColor: colors.background.primary,
+      },
+    },
+    MuiPaper: {
+      root: {
+        backgroundColor: colors.background.primary,
+      },
+      elevation1: {
+        boxShadow: `0 0.0625rem 0.1875rem ${colors.ui.shadow}`,
+      },
+      elevation2: {
+        boxShadow: `0 0.125rem ${spacing.sm} ${colors.ui.shadow}`,
+      },
+    },
+    MuiCard: {
+      root: {
+        backgroundColor: colors.background.primary,
+        borderRadius: radii.xl,
+        boxShadow: `0 0.125rem ${spacing.sm} ${colors.ui.shadow}`,
+      },
+    },
+    MuiButton: {
+      root: {
+        borderRadius: radii.md,
+        textTransform: 'none',
+        fontWeight: 600,
+      },
+      contained: {
+        boxShadow: 'none',
+        '&:hover': { boxShadow: 'none' },
+      },
+      containedPrimary: {
+        backgroundColor: colors.accent.main,
+        '&:hover': {
+          backgroundColor: colors.accent.main,
+          filter: 'brightness(0.9)',
+        },
+      },
+      text: {
+        color: colors.accent.main,
+      },
+    },
+    MuiIconButton: {
+      root: {
+        color: colors.text.primary,
+        '&:hover': {
+          backgroundColor: colors.accent.faded,
+        },
+      },
+      colorPrimary: {
+        color: colors.accent.main,
+      },
+      sizeSmall: {
+        padding: spacing.md,
+      },
+    },
+    MuiSvgIcon: {
+      colorPrimary: {
+        color: colors.accent.main,
+      },
+    },
+    MuiCheckbox: {
+      root: {
+        color: 'rgba(0, 0, 0, 0.15)',
+        '&$checked': {
+          color: colors.accent.main,
+        },
+      },
+    },
+    MuiChip: {
+      root: {
+        backgroundColor: colors.background.secondary,
+        color: colors.text.primary,
+        borderRadius: radii.pill,
+      },
+      colorPrimary: {
+        backgroundColor: colors.accent.faded,
+        color: colors.accent.main,
+      },
+    },
+    MuiTableRow: {
+      root: {
+        '&:hover': {
+          backgroundColor: `${colors.accent.faded} !important`,
+        },
+      },
+    },
+    MuiTableCell: {
+      root: {
+        borderBottomColor: 'rgba(0, 0, 0, 0.04)',
+      },
+      head: {
+        backgroundColor: colors.background.secondary,
+        color: colors.text.secondary,
+        fontWeight: 600,
+        fontSize: '0.75rem',
+        textTransform: 'uppercase',
+        letterSpacing: '0.05em',
+      },
+      body: {
+        color: colors.text.primary,
+      },
+    },
+    MuiListItem: {
+      root: {
+        color: colors.text.primary,
+        '&:hover': {
+          backgroundColor: colors.accent.faded,
+        },
+        '&$selected': {
+          backgroundColor: colors.accent.faded,
+          color: colors.accent.main,
+          '& .MuiListItemIcon-root': {
+            color: colors.accent.main,
+          },
+          '&:hover': {
+            backgroundColor: colors.accent.faded,
+          },
+        },
+      },
+      button: {
+        color: colors.text.primary,
+        '&:hover': {
+          backgroundColor: colors.accent.faded,
+          color: colors.text.primary,
+        },
+      },
+    },
+    MuiListItemIcon: {
+      root: menuIconStyle(),
+    },
+    MuiListItemText: {
+      primary: {
+        color: 'inherit',
+      },
+    },
+    MuiMenuItem: {
+      root: {
+        fontSize: '0.875rem',
+        paddingTop: '4px',
+        paddingBottom: '4px',
+        paddingLeft: '10px',
+        margin: '5px',
+        borderRadius: radii.md,
+        color: colors.text.primary,
+      },
+    },
+    MuiDrawer: {
+      paper: {
+        backgroundColor: colors.background.primary,
+        borderRight: `1px solid ${colors.ui.separator}`,
+      },
+    },
+    MuiSlider: {
+      root: {
+        color: colors.accent.main,
+      },
+      track: {
+        backgroundColor: colors.accent.main,
+      },
+      thumb: {
+        backgroundColor: colors.accent.main,
+        '&:hover': {
+          boxShadow: `0 0 0 ${spacing.sm} ${colors.accent.faded}`,
+        },
+      },
+      rail: {
+        backgroundColor: colors.background.tertiary,
+      },
+    },
+    MuiLinearProgress: {
+      root: {
+        backgroundColor: colors.background.tertiary,
+        borderRadius: radii.sm,
+      },
+      bar: {
+        backgroundColor: colors.accent.main,
+        borderRadius: radii.sm,
+      },
+    },
+    MuiTabs: {
+      root: {
+        borderBottom: `1px solid ${colors.ui.separator}`,
+      },
+      indicator: {
+        backgroundColor: colors.accent.main,
+        height: '0.1875rem',
+        borderRadius: '0.1875rem 0.1875rem 0 0',
+      },
+    },
+    MuiTab: {
+      root: {
+        textTransform: 'none',
+        fontWeight: 500,
+        fontFamily: typography.fontFamily.heading,
+        '&$selected': {
+          color: colors.accent.main,
+          fontWeight: 600,
+        },
+      },
+    },
+    MuiInputBase: {
+      root: {
+        backgroundColor: colors.background.secondary,
+        borderRadius: radii.lg,
+      },
+    },
+    MuiOutlinedInput: {
+      root: {
+        borderRadius: radii.lg,
+        '& $notchedOutline': {
+          borderColor: colors.ui.separator,
+        },
+        '&:hover $notchedOutline': {
+          borderColor: colors.text.tertiary,
+        },
+        '&$focused $notchedOutline': {
+          borderColor: colors.accent.main,
+          borderWidth: '0.125rem',
+        },
+      },
+    },
+    MuiFilledInput: {
+      root: {
+        backgroundColor: colors.background.secondary,
+        borderRadius: radii.lg,
+        '&:hover': {
+          backgroundColor: colors.background.tertiary,
+        },
+        '&$focused': {
+          backgroundColor: colors.background.secondary,
+        },
+      },
+    },
+    MuiFab: {
+      primary: {
+        backgroundColor: colors.accent.main,
+        '&:hover': {
+          backgroundColor: colors.accent.main,
+          filter: 'brightness(0.9)',
+        },
+      },
+    },
+    MuiAvatar: {
+      root: {
+        borderRadius: radii.md,
+      },
+    },
+    MuiRating: {
+      iconFilled: {
+        color: colors.accent.main,
+      },
+      iconHover: {
+        color: colors.accent.main,
+      },
+    },
+    MuiTooltip: {
+      tooltip: {
+        backgroundColor: colors.text.primary,
+        color: colors.background.primary,
+        fontSize: '0.75rem',
+        padding: `${spacing.xs} ${spacing.sm}`,
+        borderRadius: radii.sm,
+      },
+    },
+    MuiBottomNavigation: {
+      root: {
+        backgroundColor: colors.ui.glassBg,
+        backdropFilter: `blur(${tokens.blur})`,
+        borderTop: `1px solid ${colors.ui.separator}`,
+      },
+    },
+    MuiBottomNavigationAction: {
+      root: {
+        color: colors.text.secondary,
+        '&$selected': {
+          color: colors.accent.main,
+        },
+      },
+      label: {
+        fontFamily: typography.fontFamily.heading,
+        fontSize: '0.65rem',
+        '&$selected': {
+          fontSize: '0.65rem',
+        },
+      },
+    },
+    NDAppBar: {
+      root: {
+        color: colors.text.primary,
+      },
+    },
+    NDLogin: {
+      main: {
+        backgroundColor: colors.background.primary,
+      },
+      card: {
+        backgroundColor: colors.background.primary,
+        borderRadius: radii.pill,
+        boxShadow: `0 ${spacing.xs} ${spacing.xl} ${colors.ui.shadow}`,
+      },
+    },
+    NDAlbumGridView: {
+      albumContainer: {
+        borderRadius: radii.md,
+        '& img': {
+          borderRadius: radii.md,
+        },
+      },
+      albumTitle: {
+        fontWeight: 600,
+        color: colors.text.primary,
+      },
+      albumSubtitle: {
+        color: colors.text.secondary,
+      },
+      albumPlayButton: {
+        backgroundColor: colors.accent.main,
+        borderRadius: radii.full,
+        boxShadow: `0 ${spacing.sm} ${spacing.sm} rgba(0, 0, 0, 0.15)`,
+        padding: '0.35rem',
+        transition: 'padding .3s ease',
+        '&:hover': {
+          backgroundColor: `${colors.accent.main} !important`,
+          padding: '0.45rem',
+        },
+      },
+    },
+    NDAlbumDetails: {
+      root: {
+        [`@media (max-width: ${breakpoints.xs}px)`]: {
+          padding: '0.7em',
+          width: '100%',
+          minWidth: 'unset',
+        },
+      },
+      cardContents: {
+        [`@media (max-width: ${breakpoints.xs}px)`]: {
+          flexDirection: 'column',
+          alignItems: 'center',
+        },
+      },
+      details: {
+        [`@media (max-width: ${breakpoints.xs}px)`]: {
+          width: '100%',
+        },
+      },
+      cover: {
+        borderRadius: radii.md,
+      },
+      coverParent: {
+        marginRight: spacing.xl,
+        [`@media (max-width: ${breakpoints.xs}px)`]: {
+          width: '100%',
+          height: 'auto',
+          minWidth: 'unset',
+          aspectRatio: '1',
+          marginRight: 0,
+          marginBottom: spacing.lg,
+        },
+        ...coverSizing(),
+      },
+      recordName: {
+        fontSize: '1.75rem',
+        fontWeight: 700,
+        marginBottom: '0.15rem',
+      },
+      recordArtist: {
+        marginBottom: spacing.md,
+      },
+      recordMeta: {
+        marginBottom: spacing.sm,
+      },
+      genreList: {
+        marginTop: spacing.md,
+      },
+      loveButton: {
+        marginLeft: spacing.sm,
+      },
+    },
+    NDAlbumShow: {
+      albumActions: actionButtonsStyle(),
+    },
+    NDPlaylistShow: {
+      playlistActions: actionButtonsStyle(),
+    },
+    NDSubMenu: {
+      icon: menuIconStyle(),
+      menuHeader: {
+        color: colors.text.primary,
+        '& .MuiTypography-root': {
+          color: colors.text.primary,
+        },
+      },
+      actionIcon: {
+        marginLeft: spacing.sm,
+      },
+    },
+    RaMenuItemLink: {
+      root: {
+        color: `${colors.text.primary} !important`,
+        '& .MuiListItemIcon-root': menuIconStyle(),
+        '&[class*="makeStyles-active"]': activeLinkStyle,
+      },
+      active: activeLinkStyle,
+    },
+    NDDesktopArtistDetails: {
+      root: {
+        [`@media (min-width: ${breakpoints.sm}px)`]: {
+          padding: '1em',
+        },
+        [`@media (min-width: ${breakpoints.lg}px)`]: {
+          padding: '1em',
+        },
+      },
+      cover: {
+        borderRadius: radii.md,
+        ...coverSizing(),
+      },
+      artistImage: {
+        borderRadius: radii.md,
+        marginRight: spacing.xl,
+        [`@media (min-width: ${breakpoints.sm}px)`]: {
+          height: sizing.cover.sm,
+          width: sizing.cover.sm,
+          minWidth: sizing.cover.sm,
+          maxHeight: sizing.cover.sm,
+          minHeight: sizing.cover.sm,
+        },
+        [`@media (min-width: ${breakpoints.lg}px)`]: {
+          height: sizing.cover.lg,
+          width: sizing.cover.lg,
+          minWidth: sizing.cover.lg,
+          maxHeight: sizing.cover.lg,
+          minHeight: sizing.cover.lg,
+        },
+      },
+      artistName: {
+        fontSize: '1.75rem',
+        fontWeight: 700,
+        marginBottom: spacing.sm,
+      },
+    },
+    NDMobileArtistDetails: {
+      cover: {
+        borderRadius: radii.md,
+      },
+      artistImage: {
+        borderRadius: radii.md,
+      },
+    },
+    RaList: {
+      content: {
+        overflow: 'visible',
+      },
+    },
+    RaBulkActionsToolbar: {
+      topToolbar: {
+        backgroundColor: 'transparent',
+        boxShadow: 'none',
+        padding: spacing.sm,
+        '@global': {
+          button: {
+            border: '1px solid transparent',
+            backgroundColor: colors.background.secondary,
+            color: colors.text.secondary,
+            margin: `0 ${spacing.xs}`,
+            borderRadius: radii.full,
+            minWidth: 0,
+            padding: spacing.sm,
+            position: 'relative',
+            '&:hover': {
+              backgroundColor: `${colors.background.tertiary} !important`,
+              border: '1px solid transparent',
+            },
+          },
+          'button>span:first-child>span': {
+            display: 'none',
+          },
+          'button:hover>span:first-child>span': customTooltipStyle(),
+          'button>span:first-child>svg': {
+            color: colors.text.secondary,
+          },
+        },
+      },
+    },
+    RaPaginationActions: {
+      currentPageButton: {
+        backgroundColor: colors.accent.faded,
+      },
+    },
+  },
+  player: {
+    theme: 'light',
+    stylesheet: `
+      @font-face {
+        font-family: 'Unbounded';
+        font-style: normal;
+        font-weight: 300 800;
+        font-display: swap;
+        src: url('/fonts/Unbounded-Variable.woff2') format('woff2');
+      }
+
+      .react-jinke-music-player-main {
+        background-color: ${colors.background.primary} !important;
+        font-family: ${typography.fontFamily.base} !important;
+      }
+
+      .react-jinke-music-player-main .music-player-panel {
+        background-color: ${colors.ui.glassBg} !important;
+        backdrop-filter: blur(${tokens.blur}) !important;
+        -webkit-backdrop-filter: blur(${tokens.blur}) !important;
+        border-top: 1px solid ${colors.ui.separator} !important;
+        box-shadow: 0 -0.125rem 1.25rem rgba(0, 0, 0, 0.06) !important;
+      }
+
+      .react-jinke-music-player-main svg {
+        color: ${colors.text.primary} !important;
+      }
+
+      .react-jinke-music-player-main svg:hover {
+        color: ${colors.accent.main} !important;
+      }
+
+      .react-jinke-music-player-main .rc-slider-track,
+      .react-jinke-music-player-main .rc-slider-handle {
+        background-color: ${colors.accent.main} !important;
+      }
+
+      .react-jinke-music-player-main .rc-slider-handle {
+        border-color: ${colors.accent.main} !important;
+      }
+
+      .react-jinke-music-player-main .rc-slider-rail {
+        background-color: ${colors.background.secondary} !important;
+      }
+
+      .react-jinke-music-player-main .rc-slider {
+        height: 4px !important;
+      }
+
+      .react-jinke-music-player-main .rc-slider-rail,
+      .react-jinke-music-player-main .rc-slider-track {
+        height: 4px !important;
+        border-radius: 2px !important;
+      }
+
+      .react-jinke-music-player-main .rc-slider-handle {
+        width: 12px !important;
+        height: 12px !important;
+        margin-top: -4px !important;
+      }
+
+      .react-jinke-music-player-main .audio-lists-panel,
+      .react-jinke-music-player-main .audio-lists-panel-content {
+        background-color: ${colors.background.primary} !important;
+      }
+
+      .react-jinke-music-player-main .audio-lists-panel-content .audio-item {
+        background-color: transparent !important;
+        color: ${colors.text.primary} !important;
+      }
+
+      .react-jinke-music-player-main .audio-lists-panel-content .audio-item:hover {
+        background-color: ${colors.accent.faded} !important;
+      }
+
+      .react-jinke-music-player-main .audio-lists-panel-content .audio-item.playing {
+        background-color: ${colors.accent.faded} !important;
+        color: ${colors.accent.main} !important;
+      }
+
+      .react-jinke-music-player-main .lyric-btn-active,
+      .react-jinke-music-player-main .play-mode-title {
+        color: ${colors.accent.main} !important;
+      }
+
+      .react-jinke-music-player-main .music-player-panel .player-content .music-player-controller .music-player-info .music-player-title {
+        color: ${colors.text.primary} !important;
+        font-weight: 600 !important;
+        font-family: ${typography.fontFamily.heading} !important;
+      }
+
+      .react-jinke-music-player-main .music-player-panel .player-content .music-player-controller .music-player-info .music-player-artist {
+        color: ${colors.text.secondary} !important;
+      }
+
+      .react-jinke-music-player-main.mini-player {
+        background-color: ${colors.ui.glassBg} !important;
+        backdrop-filter: blur(${tokens.blur}) !important;
+        -webkit-backdrop-filter: blur(${tokens.blur}) !important;
+        border-radius: ${radii.xl} !important;
+        box-shadow: 0 ${spacing.xs} 1.25rem rgba(0, 0, 0, 0.08) !important;
+      }
+
+
+      .MuiTypography-h1,
+      .MuiTypography-h2,
+      .MuiTypography-h3,
+      .MuiTypography-h4,
+      .MuiTypography-h5,
+      .MuiTypography-h6 {
+        font-family: ${typography.fontFamily.heading} !important;
+      }
+    `,
+  },
+}
+
+export default NautilineTheme

ui/vite.config.js

@@ -14,6 +14,9 @@ export default defineConfig({
       strategies: 'injectManifest',
       srcDir: 'src',
       filename: 'sw.js',
+      injectManifest: {
+        maximumFileSizeToCacheInBytes: 3 * 1024 * 1024, // 3 MiB
+      },
       devOptions: {
         enabled: true,
       },
@@ -27,6 +30,10 @@ export default defineConfig({
     },
   },
   base: './',
+  define: {
+    // JSONForms and other libraries use process.env
+    'process.env': JSON.stringify({}),
+  },
   build: {
     outDir: 'build',
     sourcemap: true,