🎧 Your Personal Streaming Service
Go airsonicmadsonicmedia-servermusicmusic-servernavidromeopensubsonicraspberry-piself-hostedstreamerstreaming-apistreaming-audiosubsonicsubsonic-server
feat(plugins): expose the song Matcher as a host service (#5643)
Deluan Quintãof580d3ea76ca
diff --git a/plugins/capabilities/lyrics.yaml b/plugins/capabilities/lyrics.yamlindex a64897509..7336124fc 100644--- a/plugins/capabilities/lyrics.yaml+++ b/plugins/capabilities/lyrics.yaml@@ -114,7 +114,8 @@ components:description: |-ArtistRef is the minimal information a plugin returns for Navidrome to match anartist against the library. It is a reference, not a full artist entity: it- carries only matching keys (name and optional internal/MusicBrainz IDs), never+ carries only matching keys (name and optional internal/MusicBrainz IDs) plus a+ few projection fields used when describing a track's participants, neverdescriptive data such as biographies or images.properties:id:@@ -126,5 +127,14 @@ components:mbid:type: stringdescription: MBID is the MusicBrainz ID for the artist.+ sortName:+ type: string+ description: SortName is the artist name used for sorting (if known).+ role:+ type: string+ description: Role is the participation category (e.g. "artist", "composer", "performer").+ subRole:+ type: string+ description: SubRole is a specialization within Role (e.g. the instrument for a performer).required:- namediff --git a/plugins/capabilities/metadata_agent.yaml b/plugins/capabilities/metadata_agent.yamlindex cae23eadc..6e528c7e7 100644--- a/plugins/capabilities/metadata_agent.yaml+++ b/plugins/capabilities/metadata_agent.yaml@@ -351,7 +351,8 @@ components:description: |-ArtistRef is the minimal information a plugin returns for Navidrome to match anartist against the library. It is a reference, not a full artist entity: it- carries only matching keys (name and optional internal/MusicBrainz IDs), never+ carries only matching keys (name and optional internal/MusicBrainz IDs) plus a+ few projection fields used when describing a track's participants, neverdescriptive data such as biographies or images.properties:id:@@ -363,6 +364,15 @@ components:mbid:type: stringdescription: MBID is the MusicBrainz ID for the artist.+ sortName:+ type: string+ description: SortName is the artist name used for sorting (if known).+ role:+ type: string+ description: Role is the participation category (e.g. "artist", "composer", "performer").+ subRole:+ type: string+ description: SubRole is a specialization within Role (e.g. the instrument for a performer).required:- nameSongRef:@@ -387,10 +397,16 @@ components:description: ISRC is the International Standard Recording Code for the song.artist:type: string- description: Artist is the artist name.+ description: |-+ Artist is the artist name.++ Deprecated: use Artists.artistMbid:type: string- description: ArtistMBID is the MusicBrainz artist ID.+ description: |-+ ArtistMBID is the MusicBrainz artist ID.++ Deprecated: use Artists.artists:type: arraydescription: Artists is the full artist list; when set, takes precedence over Artist/ArtistMBID for matching.@@ -405,6 +421,17 @@ components:duration:type: numberformat: float- description: Duration is the song duration in seconds.+ description: |-+ Duration is the song duration in seconds.++ Deprecated: use DurationMs, which carries millisecond precision. When+ DurationMs is non-zero it takes precedence; Duration is kept only for+ backwards compatibility with plugins that still send seconds.+ durationMs:+ type: integer+ format: int64+ description: |-+ DurationMs is the song duration in milliseconds. It supersedes Duration+ when non-zero.required:- namediff --git a/plugins/capabilities/scrobbler.yaml b/plugins/capabilities/scrobbler.yamlindex 07af8ec7a..2b862b964 100644--- a/plugins/capabilities/scrobbler.yaml+++ b/plugins/capabilities/scrobbler.yaml@@ -184,7 +184,8 @@ components:description: |-ArtistRef is the minimal information a plugin returns for Navidrome to match anartist against the library. It is a reference, not a full artist entity: it- carries only matching keys (name and optional internal/MusicBrainz IDs), never+ carries only matching keys (name and optional internal/MusicBrainz IDs) plus a+ few projection fields used when describing a track's participants, neverdescriptive data such as biographies or images.properties:id:@@ -196,5 +197,14 @@ components:mbid:type: stringdescription: MBID is the MusicBrainz ID for the artist.+ sortName:+ type: string+ description: SortName is the artist name used for sorting (if known).+ role:+ type: string+ description: Role is the participation category (e.g. "artist", "composer", "performer").+ subRole:+ type: string+ description: SubRole is a specialization within Role (e.g. the instrument for a performer).required:- namediff --git a/plugins/capabilities/sonic_similarity.yaml b/plugins/capabilities/sonic_similarity.yamlindex f0951fcec..a336fbce8 100644--- a/plugins/capabilities/sonic_similarity.yaml+++ b/plugins/capabilities/sonic_similarity.yaml@@ -61,7 +61,8 @@ components:description: |-ArtistRef is the minimal information a plugin returns for Navidrome to match anartist against the library. It is a reference, not a full artist entity: it- carries only matching keys (name and optional internal/MusicBrainz IDs), never+ carries only matching keys (name and optional internal/MusicBrainz IDs) plus a+ few projection fields used when describing a track's participants, neverdescriptive data such as biographies or images.properties:id:@@ -73,6 +74,15 @@ components:mbid:type: stringdescription: MBID is the MusicBrainz ID for the artist.+ sortName:+ type: string+ description: SortName is the artist name used for sorting (if known).+ role:+ type: string+ description: Role is the participation category (e.g. "artist", "composer", "performer").+ subRole:+ type: string+ description: SubRole is a specialization within Role (e.g. the instrument for a performer).required:- nameSongRef:@@ -97,10 +107,16 @@ components:description: ISRC is the International Standard Recording Code for the song.artist:type: string- description: Artist is the artist name.+ description: |-+ Artist is the artist name.++ Deprecated: use Artists.artistMbid:type: string- description: ArtistMBID is the MusicBrainz artist ID.+ description: |-+ ArtistMBID is the MusicBrainz artist ID.++ Deprecated: use Artists.artists:type: arraydescription: Artists is the full artist list; when set, takes precedence over Artist/ArtistMBID for matching.@@ -115,6 +131,17 @@ components:duration:type: numberformat: float- description: Duration is the song duration in seconds.+ description: |-+ Duration is the song duration in seconds.++ Deprecated: use DurationMs, which carries millisecond precision. When+ DurationMs is non-zero it takes precedence; Duration is kept only for+ backwards compatibility with plugins that still send seconds.+ durationMs:+ type: integer+ format: int64+ description: |-+ DurationMs is the song duration in milliseconds. It supersedes Duration+ when non-zero.required:- namediff --git a/plugins/cmd/ndpgen/internal/generator_test.go b/plugins/cmd/ndpgen/internal/generator_test.goindex d52d6dcbf..15b97e1ae 100644--- a/plugins/cmd/ndpgen/internal/generator_test.go+++ b/plugins/cmd/ndpgen/internal/generator_test.go@@ -287,6 +287,42 @@ var _ = Describe("Generator", func() {Expect(codeStr).To(ContainSubstring(`"encoding/json"`))Expect(codeStr).To(ContainSubstring(`extism "github.com/extism/go-sdk"`))})++ It("imports the shared types package when a method references types directly", func() {+ svc := Service{+ Name: "Matcher",+ Interface: "MatcherService",+ Methods: []Method{+ {+ Name: "MatchSongs",+ HasError: true,+ Params: []Param{NewParam("songs", "[]types.SongRef")},+ Returns: []Param{NewParam("results", "[]*types.Track")},+ },+ },+ }++ code, err := GenerateHost(svc, "host")+ Expect(err).NotTo(HaveOccurred())++ codeStr := string(code)+ Expect(codeStr).To(ContainSubstring(`"github.com/navidrome/navidrome/plugins/types"`))+ Expect(codeStr).To(ContainSubstring("Songs []types.SongRef"))+ })++ It("does not import the shared types package when no method references types", func() {+ svc := Service{+ Name: "Test",+ Interface: "TestService",+ Methods: []Method{+ {Name: "Method", Params: []Param{NewParam("count", "int32")}},+ },+ }++ code, err := GenerateHost(svc, "host")+ Expect(err).NotTo(HaveOccurred())+ Expect(string(code)).NotTo(ContainSubstring(`"github.com/navidrome/navidrome/plugins/types"`))+ })})Describe("toJSONName", func() {diff --git a/plugins/cmd/ndpgen/internal/parser.go b/plugins/cmd/ndpgen/internal/parser.goindex 4b832d22d..9f305efec 100644--- a/plugins/cmd/ndpgen/internal/parser.go+++ b/plugins/cmd/ndpgen/internal/parser.go@@ -85,19 +85,24 @@ func ParseDirectoryWithShared(dir string, shared map[string]StructDef) ([]Servicreturn nil, err}- // First pass: collect all type aliases from every file so that an alias- // declared in one file is visible when resolving types in a sibling file.+ // First pass: collect all struct definitions and type aliases from every file+ // so that a struct or alias declared in one file is visible when resolving+ // types in a sibling file.+ pkgStructMap := make(map[string]StructDef)pkgAliasMap := make(map[string]TypeAlias)for _, pf := range parsed {+ for _, s := range parseStructs(pf.file) {+ pkgStructMap[s.Name] = s+ }for _, a := range parseTypeAliases(pf.file) {pkgAliasMap[a.Name] = a}}- // Second pass: parse services using the package-level alias map.+ // Second pass: parse services using the package-level maps.var services []Servicefor _, pf := range parsed {- svcList, err := parseServiceFile(pf.file, pkgAliasMap, shared)+ svcList, err := parseServiceFile(pf.file, pkgStructMap, pkgAliasMap, shared)if err != nil {return nil, fmt.Errorf("parsing %s: %w", filepath.Base(pf.path), err)}@@ -484,15 +489,10 @@ func parseExport(name string, funcType *ast.FuncType, annotation map[string]stri}// parseServiceFile parses a single Go source file and extracts host services.-// pkgAliasMap is the package-wide alias map built from all files in the package.-func parseServiceFile(f *ast.File, pkgAliasMap map[string]TypeAlias, shared map[string]StructDef) ([]Service, error) {- // Collect all struct definitions in the file.- allStructs := parseStructs(f)- structMap := make(map[string]StructDef)- for _, s := range allStructs {- structMap[s.Name] = s- }-+// pkgStructMap and pkgAliasMap are the package-wide struct and alias maps built+// from all files in the package, so a host-service interface can reference types+// defined in a sibling file.+func parseServiceFile(f *ast.File, pkgStructMap map[string]StructDef, pkgAliasMap map[string]TypeAlias, shared map[string]StructDef) ([]Service, error) {var services []Servicefor _, decl := range f.Decls {@@ -569,9 +569,13 @@ func parseServiceFile(f *ast.File, pkgAliasMap map[string]TypeAlias, shared map[}service.SharedAliases = sharedAliases+ // Recursively collect all struct dependencies so types referenced only+ // transitively (e.g. a field type of a referenced struct) are attached.+ collectAllStructDependencies(referencedTypes, pkgStructMap)+// Attach referenced structs to the service (sorted for stable output)for _, typeName := range slices.Sorted(maps.Keys(referencedTypes)) {- if s, exists := structMap[typeName]; exists {+ if s, exists := pkgStructMap[typeName]; exists {service.Structs = append(service.Structs, s)}}diff --git a/plugins/cmd/ndpgen/internal/parser_test.go b/plugins/cmd/ndpgen/internal/parser_test.goindex 93d00f657..bfdb93db5 100644--- a/plugins/cmd/ndpgen/internal/parser_test.go+++ b/plugins/cmd/ndpgen/internal/parser_test.go@@ -213,6 +213,64 @@ type RegularInterface interface {Expect(services).To(BeEmpty())})+ It("should resolve structs defined in a sibling file of the same package", func() {+ // types.go defines Track and Artist — no host service here+ typesSrc := `package host++// Artist is a track participant.+type Artist struct {+ // ID is the artist identifier.+ ID string ` + "`json:\"id\"`" + `+ // Name is the artist name.+ Name string ` + "`json:\"name\"`" + `+}++// Track is a media file projection.+type Track struct {+ // ID is the track identifier.+ ID string ` + "`json:\"id\"`" + `+ // Title is the track title.+ Title string ` + "`json:\"title\"`" + `+ // Participants maps role to artists (transitive dependency test).+ Participants map[string][]Artist ` + "`json:\"participants\"`" + `+}+`+ // service.go defines the host service that references Track from types.go+ serviceSrc := `package host++import "context"++// MatcherService matches tracks.+//nd:hostservice name=Matcher permission=matcher+type MatcherService interface {+ // MatchTrack finds a matching track.+ //nd:hostfunc+ MatchTrack(ctx context.Context, t Track) (matched bool, err error)+}+`+ err := os.WriteFile(filepath.Join(tmpDir, "types.go"), []byte(typesSrc), 0600)+ Expect(err).NotTo(HaveOccurred())+ err = os.WriteFile(filepath.Join(tmpDir, "service.go"), []byte(serviceSrc), 0600)+ Expect(err).NotTo(HaveOccurred())++ services, err := ParseDirectory(tmpDir)+ Expect(err).NotTo(HaveOccurred())+ Expect(services).To(HaveLen(1))++ svc := services[0]+ Expect(svc.Name).To(Equal("Matcher"))+ Expect(svc.Methods).To(HaveLen(1))+ Expect(svc.Methods[0].Name).To(Equal("MatchTrack"))++ // Track must be resolved from the sibling file, not just the service file.+ // Artist must also be transitively resolved (Track.Participants references it).+ structNames := make([]string, len(svc.Structs))+ for i, s := range svc.Structs {+ structNames[i] = s.Name+ }+ Expect(structNames).To(ConsistOf("Track", "Artist"))+ })+It("returns an error when a shared-type alias cannot be resolved (no registry)", func() {fileA := `package hostdiff --git a/plugins/cmd/ndpgen/internal/templates/host.go.tmpl b/plugins/cmd/ndpgen/internal/templates/host.go.tmplindex 083f7577e..b1ac4dd36 100644--- a/plugins/cmd/ndpgen/internal/templates/host.go.tmpl+++ b/plugins/cmd/ndpgen/internal/templates/host.go.tmpl@@ -7,6 +7,10 @@ import ("encoding/json"extism "github.com/extism/go-sdk"+{{- if .Service.ImportsSharedTypes}}++ "github.com/navidrome/navidrome/plugins/types"+{{- end}}){{- /* Generate request/response types for all methods */ -}}diff --git a/plugins/host/matcher.go b/plugins/host/matcher.gonew file mode 100644index 000000000..678d3bfaa--- /dev/null+++ b/plugins/host/matcher.go@@ -0,0 +1,27 @@+package host++import (+ "context"++ "github.com/navidrome/navidrome/plugins/types"+)++// MatchOptions carries optional parameters for a match request.+type MatchOptions struct {+ // Username runs the match as that user (case-insensitive): their favourites and+ // ratings inform tiebreaking, and the returned tracks carry their annotations.+ Username string `json:"username,omitempty"`+}++// MatcherService resolves externally-obtained songs to local library tracks,+// reusing Navidrome's matching algorithm (ID > MBID > ISRC > fuzzy title).+//+//nd:hostservice name=Matcher permission=matcher+type MatcherService interface {+ // MatchSongs resolves each input song to its best-matching library track.+ // It returns one entry per input song, in the same order as the input; the+ // entry for an input song that had no match is empty (absent). Results are+ // limited to the libraries the plugin (and the scoped user, if any) can access.+ //nd:hostfunc+ MatchSongs(ctx context.Context, songs []types.SongRef, opts MatchOptions) (results []*types.Track, err error)+}diff --git a/plugins/host/matcher_gen.go b/plugins/host/matcher_gen.gonew file mode 100644index 000000000..1bcd0dc3b--- /dev/null+++ b/plugins/host/matcher_gen.go@@ -0,0 +1,91 @@+// Code generated by ndpgen. DO NOT EDIT.++package host++import (+ "context"+ "encoding/json"++ extism "github.com/extism/go-sdk"++ "github.com/navidrome/navidrome/plugins/types"+)++// MatcherMatchSongsRequest is the request type for Matcher.MatchSongs.+type MatcherMatchSongsRequest struct {+ Songs []types.SongRef `json:"songs"`+ Opts MatchOptions `json:"opts"`+}++// MatcherMatchSongsResponse is the response type for Matcher.MatchSongs.+type MatcherMatchSongsResponse struct {+ Results []*types.Track `json:"results,omitempty"`+ Error string `json:"error,omitempty"`+}++// RegisterMatcherHostFunctions registers Matcher service host functions.+// The returned host functions should be added to the plugin's configuration.+func RegisterMatcherHostFunctions(service MatcherService) []extism.HostFunction {+ return []extism.HostFunction{+ newMatcherMatchSongsHostFunction(service),+ }+}++func newMatcherMatchSongsHostFunction(service MatcherService) extism.HostFunction {+ return extism.NewHostFunctionWithStack(+ "matcher_matchsongs",+ func(ctx context.Context, p *extism.CurrentPlugin, stack []uint64) {+ // Read JSON request from plugin memory+ reqBytes, err := p.ReadBytes(stack[0])+ if err != nil {+ matcherWriteError(p, stack, err)+ return+ }+ var req MatcherMatchSongsRequest+ if err := json.Unmarshal(reqBytes, &req); err != nil {+ matcherWriteError(p, stack, err)+ return+ }++ // Call the service method+ results, svcErr := service.MatchSongs(ctx, req.Songs, req.Opts)+ if svcErr != nil {+ matcherWriteError(p, stack, svcErr)+ return+ }++ // Write JSON response to plugin memory+ resp := MatcherMatchSongsResponse{+ Results: results,+ }+ matcherWriteResponse(p, stack, resp)+ },+ []extism.ValueType{extism.ValueTypePTR},+ []extism.ValueType{extism.ValueTypePTR},+ )+}++// matcherWriteResponse writes a JSON response to plugin memory.+func matcherWriteResponse(p *extism.CurrentPlugin, stack []uint64, resp any) {+ respBytes, err := json.Marshal(resp)+ if err != nil {+ matcherWriteError(p, stack, err)+ return+ }+ respPtr, err := p.WriteBytes(respBytes)+ if err != nil {+ stack[0] = 0+ return+ }+ stack[0] = respPtr+}++// matcherWriteError writes an error response to plugin memory.+func matcherWriteError(p *extism.CurrentPlugin, stack []uint64, err error) {+ errResp := struct {+ Error string `json:"error"`+ }{Error: err.Error()}+ respBytes, _ := json.Marshal(errResp)+ respPtr, _ := p.WriteBytes(respBytes)+ stack[0] = respPtr+}diff --git a/plugins/host_matcher.go b/plugins/host_matcher.gonew file mode 100644index 000000000..9b65e7933--- /dev/null+++ b/plugins/host_matcher.go@@ -0,0 +1,194 @@+package plugins++import (+ "cmp"+ "context"+ "fmt"+ "maps"+ "slices"+ "time"++ "github.com/navidrome/navidrome/core/matcher"+ "github.com/navidrome/navidrome/model"+ "github.com/navidrome/navidrome/model/request"+ "github.com/navidrome/navidrome/plugins/host"+ "github.com/navidrome/navidrome/plugins/types"+ "github.com/navidrome/navidrome/utils/slice"+)++type matcherServiceImpl struct {+ ds model.DataStore+ hasFilesystemPerm bool+ users userAccess+ libs libraryAccess+}++func newMatcherService(ds model.DataStore, hasFilesystemPerm bool, users userAccess, libs libraryAccess) host.MatcherService {+ return &matcherServiceImpl{+ ds: ds,+ hasFilesystemPerm: hasFilesystemPerm,+ users: users,+ libs: libs,+ }+}++func (s *matcherServiceImpl) MatchSongs(ctx context.Context, songs []types.SongRef, opts host.MatchOptions) ([]*types.Track, error) {+ results := make([]*types.Track, len(songs))+ if len(songs) == 0 {+ return results, nil+ }++ // Fail closed when the plugin has no library scope, rather than matching nothing.+ if !s.libs.configured() {+ return nil, fmt.Errorf("matcher: no libraries configured for this plugin")+ }++ // Set the user context explicitly so the match never inherits the request user+ // of whatever invoked the plugin: a username scopes to that user (loading their+ // annotations and library access), and an unscoped match runs as admin so only+ // the plugin's own library scope constrains the results.+ scoped := opts.Username != ""+ if scoped {+ usr, err := s.users.resolve(ctx, s.ds, opts.Username)+ if err != nil {+ return nil, fmt.Errorf("matcher: %w", err)+ }+ ctx = request.WithUser(ctx, *usr)+ } else {+ ctx = adminContext(ctx)+ }++ agentSongs := slice.Map(songs, songRefToAgentSong)++ matched, err := matcher.New(s.ds).MatchSongsIndexed(ctx, agentSongs)+ if err != nil {+ return nil, err+ }+ for i, mf := range matched {+ // Drop tracks outside the plugin's library scope, leaving that index unmatched.+ if !s.libs.contains(mf.LibraryID) {+ continue+ }+ results[i] = s.toTrack(&mf, scoped)+ }+ return results, nil+}++// toTrack projects a MediaFile into the public Track DTO. Path needs filesystem+// permission; per-user annotations are only set for a scoped match.+func (s *matcherServiceImpl) toTrack(mf *model.MediaFile, scoped bool) *types.Track {+ t := &types.Track{+ ID: mf.ID,+ LibraryID: int32(mf.LibraryID),+ LibraryName: mf.LibraryName,+ Missing: mf.Missing,+ Title: mf.Title,+ Album: mf.Album,+ Artist: mf.Artist,+ AlbumArtist: mf.AlbumArtist,+ AlbumID: mf.AlbumID,+ SortTitle: mf.SortTitle,+ SortAlbumName: mf.SortAlbumName,+ SortArtistName: mf.SortArtistName,+ TrackNumber: int32(mf.TrackNumber),+ DiscNumber: int32(mf.DiscNumber),+ DiscSubtitle: mf.DiscSubtitle,+ Year: int32(mf.Year),+ Date: mf.Date,+ OriginalYear: int32(mf.OriginalYear),+ OriginalDate: mf.OriginalDate,+ ReleaseYear: int32(mf.ReleaseYear),+ ReleaseDate: mf.ReleaseDate,+ Size: mf.Size,+ Suffix: mf.Suffix,+ Duration: float64(mf.Duration),+ BitRate: int32(mf.BitRate),+ SampleRate: int32(mf.SampleRate),+ BitDepth: ptrInt32(mf.BitDepth),+ Channels: int32(mf.Channels),+ Codec: mf.Codec,+ Comment: mf.Comment,+ BPM: ptrInt32(mf.BPM),+ ExplicitStatus: mf.ExplicitStatus,+ CatalogNum: mf.CatalogNum,+ Compilation: mf.Compilation,+ HasCoverArt: mf.HasCoverArt,+ MbzRecordingID: mf.MbzRecordingID,+ MbzReleaseTrackID: mf.MbzReleaseTrackID,+ MbzAlbumID: mf.MbzAlbumID,+ MbzReleaseGroupID: mf.MbzReleaseGroupID,+ MbzAlbumType: mf.MbzAlbumType,+ MbzAlbumComment: mf.MbzAlbumComment,+ RGAlbumGain: mf.RGAlbumGain,+ RGAlbumPeak: mf.RGAlbumPeak,+ RGTrackGain: mf.RGTrackGain,+ RGTrackPeak: mf.RGTrackPeak,+ AverageRating: mf.AverageRating, // aggregate, not user-scoped+ BirthTime: unixOrZero(mf.BirthTime),+ CreatedAt: unixOrZero(mf.CreatedAt),+ UpdatedAt: unixOrZero(mf.UpdatedAt),+ }+ if s.hasFilesystemPerm {+ t.Path = mf.Path+ }+ if len(mf.Genres) > 0 {+ t.Genres = slice.Map(mf.Genres, func(g model.Genre) string { return g.Name })+ }+ if len(mf.Tags) > 0 {+ t.Tags = make(map[string][]string, len(mf.Tags))+ for name, values := range mf.Tags {+ t.Tags[string(name)] = values+ }+ }+ if len(mf.Participants) > 0 {+ // Flatten the role→artists map into a role-tagged list, in stable role order.+ roles := slices.SortedFunc(maps.Keys(mf.Participants), func(a, b model.Role) int {+ return cmp.Compare(a.String(), b.String())+ })+ for _, role := range roles {+ for _, p := range mf.Participants[role] {+ t.Participants = append(t.Participants, types.ArtistRef{+ ID: p.ID,+ Name: p.Name,+ MBID: p.MbzArtistID,+ SortName: p.SortArtistName,+ Role: role.String(),+ SubRole: p.SubRole,+ })+ }+ }+ }+ if scoped {+ t.Starred = mf.Starred+ t.StarredAt = unixPtr(mf.StarredAt)+ t.Rating = int32(mf.Rating)+ t.PlayCount = mf.PlayCount+ t.PlayDate = unixPtr(mf.PlayDate)+ }+ return t+}++func unixOrZero(t time.Time) int64 {+ if t.IsZero() {+ return 0+ }+ return t.Unix()+}++// unixPtr maps a nullable time to Unix seconds, keeping nil distinct from the epoch.+func unixPtr(t *time.Time) *int64 {+ if t == nil || t.IsZero() {+ return nil+ }+ return new(t.Unix())+}++// ptrInt32 narrows a nullable *int to *int32, keeping nil distinct from a real 0.+func ptrInt32(p *int) *int32 {+ if p == nil {+ return nil+ }+ return new(int32(*p))+}++var _ host.MatcherService = (*matcherServiceImpl)(nil)diff --git a/plugins/host_matcher_test.go b/plugins/host_matcher_test.gonew file mode 100644index 000000000..9d44ee581--- /dev/null+++ b/plugins/host_matcher_test.go@@ -0,0 +1,490 @@+//go:build !windows++package plugins++import (+ "context"+ "crypto/sha256"+ "encoding/hex"+ "encoding/json"+ "errors"+ "net/http"+ "os"+ "path/filepath"+ "time"++ "github.com/navidrome/navidrome/conf"+ "github.com/navidrome/navidrome/conf/configtest"+ "github.com/navidrome/navidrome/model"+ "github.com/navidrome/navidrome/model/request"+ "github.com/navidrome/navidrome/plugins/host"+ "github.com/navidrome/navidrome/plugins/types"+ "github.com/navidrome/navidrome/tests"+ . "github.com/onsi/ginkgo/v2"+ . "github.com/onsi/gomega"+)++var _ = Describe("MatcherService", Ordered, func() {+ BeforeEach(func() {+ DeferCleanup(configtest.SetupConfig())+ })++ // newConverter returns the service as its concrete type so converter unit+ // tests can call toTrack directly with a chosen filesystem-permission flag.+ newConverter := func(hasFilesystemPerm bool) *matcherServiceImpl {+ return newMatcherService(nil, hasFilesystemPerm, newUserAccess(nil, true), newLibraryAccess(nil, true)).(*matcherServiceImpl)+ }++ Describe("toTrack", func() {+ It("projects a MediaFile into a public Track", func() {+ bitDepth := 24+ bpm := 128+ rgGain := -7.5+ created := time.Unix(1700000000, 0)+ updated := time.Unix(1700000500, 0)+ birth := time.Unix(1699999000, 0)++ mf := &model.MediaFile{+ ID: "mf-1",+ LibraryID: 3,+ LibraryName: "Main",+ Path: "/music/song.flac",+ Title: "My Song",+ Album: "My Album",+ Artist: "My Artist",+ AlbumArtist: "My Artist",+ AlbumID: "al-1",+ SortTitle: "my song",+ TrackNumber: 4,+ DiscNumber: 1,+ Year: 2020,+ Size: 1234,+ Suffix: "flac",+ Duration: 210.5,+ BitRate: 1000,+ SampleRate: 44100,+ BitDepth: &bitDepth,+ Channels: 2,+ Codec: "flac",+ Genre: "Rock",+ BPM: &bpm,+ ExplicitStatus: "c",+ Compilation: true,+ HasCoverArt: true,+ MbzRecordingID: "rec-1",+ RGTrackGain: &rgGain,+ CreatedAt: created,+ UpdatedAt: updated,+ BirthTime: birth,+ Genres: model.Genres{{Name: "Rock"}, {Name: "Pop"}},+ Tags: model.Tags{model.TagName("isrc"): []string{"US-XXX-00"}},+ }+ mf.AverageRating = 4.2+ mf.Participants = model.Participants{}+ mf.Participants.Add(model.RoleArtist, model.Artist{+ ID: "ar-1", Name: "My Artist", SortArtistName: "artist, my", MbzArtistID: "mbz-ar-1",+ })+ mf.Participants.AddWithSubRole(model.RolePerformer, "violin", model.Artist{+ ID: "ar-2", Name: "A Fiddler",+ })++ track := newConverter(true).toTrack(mf, false)++ Expect(track.ID).To(Equal("mf-1"))+ Expect(track.LibraryID).To(Equal(int32(3)))+ Expect(track.LibraryName).To(Equal("Main"))+ Expect(track.Path).To(Equal("/music/song.flac"))+ Expect(track.Title).To(Equal("My Song"))+ Expect(track.Duration).To(Equal(210.5))+ Expect(track.BitDepth).To(HaveValue(Equal(int32(24))))+ Expect(track.BPM).To(HaveValue(Equal(int32(128))))+ Expect(track.RGTrackGain).To(HaveValue(Equal(-7.5)))+ Expect(track.Compilation).To(BeTrue())+ Expect(track.MbzRecordingID).To(Equal("rec-1"))+ Expect(track.Genres).To(Equal([]string{"Rock", "Pop"}))+ Expect(track.CreatedAt).To(Equal(int64(1700000000)))+ Expect(track.UpdatedAt).To(Equal(int64(1700000500)))+ Expect(track.BirthTime).To(Equal(int64(1699999000)))+ Expect(track.Tags).To(HaveKeyWithValue("isrc", []string{"US-XXX-00"}))+ // Flat, role-tagged, role-sorted.+ Expect(track.Participants).To(HaveLen(2))+ Expect(track.Participants[0]).To(Equal(types.ArtistRef{+ ID: "ar-1", Name: "My Artist", SortName: "artist, my", MBID: "mbz-ar-1", Role: "artist",+ }))+ Expect(track.Participants[1]).To(Equal(types.ArtistRef{+ ID: "ar-2", Name: "A Fiddler", Role: "performer", SubRole: "violin",+ }))+ // AverageRating is an aggregate, exposed even though the match is unscoped.+ Expect(track.AverageRating).To(Equal(4.2))+ })++ It("leaves nil-able numeric fields nil when absent", func() {+ mf := &model.MediaFile{ID: "mf-2", Title: "No Optionals"}+ track := newConverter(true).toTrack(mf, false)+ Expect(track.BitDepth).To(BeNil())+ Expect(track.BPM).To(BeNil())+ Expect(track.RGAlbumGain).To(BeNil())+ Expect(track.RGAlbumPeak).To(BeNil())+ Expect(track.RGTrackGain).To(BeNil())+ Expect(track.RGTrackPeak).To(BeNil())+ })++ It("preserves a real 0 ReplayGain value as non-nil", func() {+ zero := 0.0+ mf := &model.MediaFile{ID: "mf-3", Title: "Zero RG", RGTrackGain: &zero}+ track := newConverter(true).toTrack(mf, false)+ Expect(track.RGTrackGain).To(HaveValue(Equal(0.0)))+ Expect(track.RGAlbumGain).To(BeNil())+ })++ It("exposes Path only when the plugin has filesystem permission", func() {+ mf := &model.MediaFile{ID: "mf-4", Title: "With Path", Path: "/music/x.flac"}+ Expect(newConverter(true).toTrack(mf, false).Path).To(Equal("/music/x.flac"))+ Expect(newConverter(false).toTrack(mf, false).Path).To(BeEmpty())+ })+ })++ Describe("MatchSongs", func() {+ // The mock MediaFileRepo returns stored files (with annotations) verbatim,+ // ignoring QueryOptions and the context user. These tests therefore cover the+ // adapter's gating/access logic, not the SQL per-user join (a persistence-layer+ // concern).++ // allowAll returns a service permitted to match as any user across all+ // libraries.+ allowAll := func(ds model.DataStore) host.MatcherService {+ return newMatcherService(ds, false, newUserAccess(nil, true), newLibraryAccess(nil, true))+ }++ It("returns one entry per input song in order, with nil for no-match", func() {+ mediaFileRepo := tests.CreateMockMediaFileRepo()+ // First (ID) phase returns the match for input song 0 only.+ mediaFileRepo.SetData(model.MediaFiles{+ {ID: "mf-100", Title: "Hit", Artist: "Band"},+ })+ ds := &tests.MockDataStore{MockedMediaFile: mediaFileRepo}++ results, err := allowAll(ds).MatchSongs(GinkgoT().Context(), []types.SongRef{+ {ID: "mf-100", Name: "Hit", Artist: "Band"},+ {ID: "missing-id", Name: "Ghost", Artist: "Nobody"},+ }, host.MatchOptions{})++ Expect(err).ToNot(HaveOccurred())+ Expect(results).To(HaveLen(2))+ Expect(results[0]).ToNot(BeNil())+ Expect(results[0].ID).To(Equal("mf-100"))+ Expect(results[1]).To(BeNil())+ })++ It("returns an empty slice for empty input", func() {+ ds := &tests.MockDataStore{MockedMediaFile: tests.CreateMockMediaFileRepo()}+ results, err := allowAll(ds).MatchSongs(GinkgoT().Context(), nil, host.MatchOptions{})+ Expect(err).ToNot(HaveOccurred())+ Expect(results).To(BeEmpty())+ })++ Context("with a scoped user", func() {+ var ds *tests.MockDataStore+ var userRepo *tests.MockedUserRepo++ BeforeEach(func() {+ mediaFileRepo := tests.CreateMockMediaFileRepo()+ mf := model.MediaFile{ID: "mf-1", Title: "Hit", Artist: "Band", LibraryID: 1}+ mf.Starred = true+ mf.Rating = 5+ mediaFileRepo.SetData(model.MediaFiles{mf})++ userRepo = tests.CreateMockUserRepo()+ Expect(userRepo.Put(&model.User{ID: "u-alice", UserName: "alice"})).To(Succeed())++ ds = &tests.MockDataStore{MockedMediaFile: mediaFileRepo, MockedUser: userRepo}+ })++ input := []types.SongRef{{ID: "mf-1", Name: "Hit", Artist: "Band"}}++ It("does not expose annotations when no username is given", func() {+ svc := newMatcherService(ds, false, newUserAccess(nil, true), newLibraryAccess(nil, true))+ results, err := svc.MatchSongs(GinkgoT().Context(), input, host.MatchOptions{})+ Expect(err).ToNot(HaveOccurred())+ Expect(results[0]).ToNot(BeNil())+ Expect(results[0].Starred).To(BeFalse())+ Expect(results[0].Rating).To(BeZero())+ })++ It("exposes the user's annotations when an allowed username is given", func() {+ svc := newMatcherService(ds, false, newUserAccess([]string{"u-alice"}, false), newLibraryAccess(nil, true))+ results, err := svc.MatchSongs(GinkgoT().Context(), input, host.MatchOptions{Username: "alice"})+ Expect(err).ToNot(HaveOccurred())+ Expect(results[0]).ToNot(BeNil())+ Expect(results[0].Starred).To(BeTrue())+ Expect(results[0].Rating).To(Equal(int32(5)))+ })++ It("allows any username when allUsers is set", func() {+ svc := newMatcherService(ds, false, newUserAccess(nil, true), newLibraryAccess(nil, true))+ results, err := svc.MatchSongs(GinkgoT().Context(), input, host.MatchOptions{Username: "alice"})+ Expect(err).ToNot(HaveOccurred())+ Expect(results[0].Starred).To(BeTrue())+ })++ It("returns an error for an unknown username", func() {+ svc := newMatcherService(ds, false, newUserAccess(nil, true), newLibraryAccess(nil, true))+ _, err := svc.MatchSongs(GinkgoT().Context(), input, host.MatchOptions{Username: "ghost"})+ Expect(err).To(MatchError(ContainSubstring("not found")))+ })++ It("surfaces a backend error rather than masking it as not-found", func() {+ userRepo.Error = errors.New("db is locked")+ svc := newMatcherService(ds, false, newUserAccess(nil, true), newLibraryAccess(nil, true))+ _, err := svc.MatchSongs(GinkgoT().Context(), input, host.MatchOptions{Username: "alice"})+ Expect(err).To(MatchError(ContainSubstring("db is locked")))+ Expect(err.Error()).ToNot(ContainSubstring("not found"))+ })++ It("returns an error for a username the plugin is not allowed to use", func() {+ svc := newMatcherService(ds, false, newUserAccess([]string{"u-bob"}, false), newLibraryAccess(nil, true))+ _, err := svc.MatchSongs(GinkgoT().Context(), input, host.MatchOptions{Username: "alice"})+ Expect(err).To(MatchError(ContainSubstring("not allowed")))+ })++ It("rejects a username with the same error whether it exists, when the plugin has no user scope", func() {+ // A plugin with no user scope (the only state a matcher-only plugin can+ // be in) must not leak whether a username exists via the error text.+ svc := newMatcherService(ds, false, newUserAccess(nil, false), newLibraryAccess(nil, true))++ _, errExisting := svc.MatchSongs(GinkgoT().Context(), input, host.MatchOptions{Username: "alice"})+ _, errMissing := svc.MatchSongs(GinkgoT().Context(), input, host.MatchOptions{Username: "ghost"})++ Expect(errExisting).To(HaveOccurred())+ Expect(errExisting.Error()).To(Equal(errMissing.Error()))+ Expect(errExisting.Error()).ToNot(ContainSubstring("not found"))+ Expect(errExisting.Error()).To(ContainSubstring("not authorized to scope by user"))+ })++ It("does not inherit the caller's request user for an unscoped match", func() {+ // The plugin may be invoked while handling another user's request; an+ // unscoped match must run as admin, not as that inherited user.+ capturing := &ctxCapturingDataStore{MockDataStore: ds}+ svc := newMatcherService(capturing, false, newUserAccess(nil, true), newLibraryAccess(nil, true))++ callerCtx := request.WithUser(GinkgoT().Context(), model.User{ID: "u-caller", UserName: "caller"})+ _, err := svc.MatchSongs(callerCtx, input, host.MatchOptions{})+ Expect(err).ToNot(HaveOccurred())++ usr, ok := request.UserFrom(capturing.lastMediaFileCtx)+ Expect(ok).To(BeTrue())+ Expect(usr.IsAdmin).To(BeTrue())+ Expect(usr.ID).ToNot(Equal("u-caller"))+ })++ It("uses the requested user, overriding an inherited caller user", func() {+ capturing := &ctxCapturingDataStore{MockDataStore: ds}+ svc := newMatcherService(capturing, false, newUserAccess(nil, true), newLibraryAccess(nil, true))++ callerCtx := request.WithUser(GinkgoT().Context(), model.User{ID: "u-caller", UserName: "caller"})+ _, err := svc.MatchSongs(callerCtx, input, host.MatchOptions{Username: "alice"})+ Expect(err).ToNot(HaveOccurred())++ usr, ok := request.UserFrom(capturing.lastMediaFileCtx)+ Expect(ok).To(BeTrue())+ Expect(usr.ID).To(Equal("u-alice"))+ })+ })++ Context("with plugin library access", func() {+ var ds *tests.MockDataStore++ BeforeEach(func() {+ mediaFileRepo := tests.CreateMockMediaFileRepo()+ mediaFileRepo.SetData(model.MediaFiles{+ {ID: "mf-lib1", Title: "A", Artist: "Band", LibraryID: 1},+ {ID: "mf-lib2", Title: "B", Artist: "Band", LibraryID: 2},+ })+ ds = &tests.MockDataStore{MockedMediaFile: mediaFileRepo}+ })++ input := []types.SongRef{+ {ID: "mf-lib1", Name: "A", Artist: "Band"},+ {ID: "mf-lib2", Name: "B", Artist: "Band"},+ }++ It("drops matches from libraries the plugin cannot access", func() {+ svc := newMatcherService(ds, false, newUserAccess(nil, true), newLibraryAccess([]int{1}, false))+ results, err := svc.MatchSongs(GinkgoT().Context(), input, host.MatchOptions{})+ Expect(err).ToNot(HaveOccurred())+ Expect(results[0]).ToNot(BeNil())+ Expect(results[0].ID).To(Equal("mf-lib1"))+ Expect(results[1]).To(BeNil()) // library 2 not permitted+ })++ It("keeps all matches when allLibraries is set", func() {+ svc := newMatcherService(ds, false, newUserAccess(nil, true), newLibraryAccess(nil, true))+ results, err := svc.MatchSongs(GinkgoT().Context(), input, host.MatchOptions{})+ Expect(err).ToNot(HaveOccurred())+ Expect(results[0]).ToNot(BeNil())+ Expect(results[1]).ToNot(BeNil())+ })++ It("errors when the plugin has no library scope configured", func() {+ svc := newMatcherService(ds, false, newUserAccess(nil, true), newLibraryAccess(nil, false))+ _, err := svc.MatchSongs(GinkgoT().Context(), input, host.MatchOptions{})+ Expect(err).To(MatchError(ContainSubstring("no libraries configured")))+ })+ })+ })++ // Artist precedence for songRefToAgentSong is covered in metadata_agent_test.go;+ // here we cover the duration normalization the matcher path relies on.+ Describe("songRefToAgentSong duration", func() {+ It("prefers DurationMs over the deprecated seconds field", func() {+ song := songRefToAgentSong(types.SongRef{DurationMs: 247333, Duration: 99})+ Expect(song.Duration).To(Equal(uint32(247333)))+ })++ It("falls back to the seconds field when DurationMs is zero", func() {+ song := songRefToAgentSong(types.SongRef{Duration: 210.5})+ Expect(song.Duration).To(Equal(uint32(210500)))+ })++ It("clamps a negative seconds duration to zero instead of overflowing", func() {+ song := songRefToAgentSong(types.SongRef{Duration: -1})+ Expect(song.Duration).To(BeZero())+ })+ })+})++var _ = Describe("MatcherService Integration", Ordered, func() {+ var (+ manager *Manager+ tmpDir string+ )++ BeforeAll(func() {+ var err error+ tmpDir, err = os.MkdirTemp("", "matcher-integration-test-*")+ Expect(err).ToNot(HaveOccurred())++ srcPath := filepath.Join(testdataDir, "test-matcher"+PackageExtension)+ destPath := filepath.Join(tmpDir, "test-matcher"+PackageExtension)+ data, err := os.ReadFile(srcPath)+ Expect(err).ToNot(HaveOccurred())+ err = os.WriteFile(destPath, data, 0600)+ Expect(err).ToNot(HaveOccurred())++ hash := sha256.Sum256(data)+ hashHex := hex.EncodeToString(hash[:])++ DeferCleanup(configtest.SetupConfig())+ conf.Server.Plugins.Enabled = true+ conf.Server.Plugins.Folder = conf.NewDir(tmpDir)+ conf.Server.Plugins.AutoReload = false++ mockPluginRepo := tests.CreateMockPluginRepo()+ mockPluginRepo.Permitted = true+ // AllLibraries: the matcher requires a library scope.+ mockPluginRepo.SetData(model.Plugins{{+ ID: "test-matcher",+ Path: destPath,+ SHA256: hashHex,+ Enabled: true,+ AllUsers: true,+ AllLibraries: true,+ }})++ mediaFileRepo := tests.CreateMockMediaFileRepo()+ hit := model.MediaFile{ID: "mf-hit", Title: "Hit", Artist: "Band"}+ hit.Starred = true+ mediaFileRepo.SetData(model.MediaFiles{hit})++ userRepo := tests.CreateMockUserRepo()+ Expect(userRepo.Put(&model.User{ID: "u-alice", UserName: "alice"})).To(Succeed())++ dataStore := &tests.MockDataStore{+ MockedPlugin: mockPluginRepo,+ MockedMediaFile: mediaFileRepo,+ MockedUser: userRepo,+ }++ manager = &Manager{+ plugins: make(map[string]*plugin),+ ds: dataStore,+ subsonicRouter: http.NotFoundHandler(),+ }+ Expect(manager.Start(GinkgoT().Context())).To(Succeed())++ DeferCleanup(func() {+ _ = manager.Stop()+ _ = os.RemoveAll(tmpDir)+ })+ })++ It("loads the plugin with the matcher permission", func() {+ manager.mu.RLock()+ p, ok := manager.plugins["test-matcher"]+ manager.mu.RUnlock()+ Expect(ok).To(BeTrue())+ Expect(p.manifest.Permissions).ToNot(BeNil())+ Expect(p.manifest.Permissions.Matcher).ToNot(BeNil())+ })++ It("matches songs through the host boundary, preserving order and nils", func() {+ ctx := GinkgoT().Context()+ manager.mu.RLock()+ p := manager.plugins["test-matcher"]+ manager.mu.RUnlock()++ instance, err := p.instance(ctx)+ Expect(err).ToNot(HaveOccurred())+ defer instance.Close(ctx)++ type tIn struct {+ Songs []types.SongRef `json:"songs"`+ Username string `json:"username,omitempty"`+ }+ type tOut struct {+ MatchedIDs []string `json:"matched_ids"`+ Starred []bool `json:"starred"`+ Error *string `json:"error,omitempty"`+ }++ call := func(in tIn) tOut {+ inputBytes, err := json.Marshal(in)+ Expect(err).ToNot(HaveOccurred())+ _, outputBytes, err := instance.Call("nd_test_matcher", inputBytes)+ Expect(err).ToNot(HaveOccurred())+ var out tOut+ Expect(json.Unmarshal(outputBytes, &out)).To(Succeed())+ Expect(out.Error).To(BeNil())+ return out+ }++ songs := []types.SongRef{+ {ID: "mf-hit", Name: "Hit", Artist: "Band"},+ {ID: "nope", Name: "Ghost", Artist: "Nobody"},+ }++ By("matching without a user, preserving order and nils")+ out := call(tIn{Songs: songs})+ Expect(out.MatchedIDs).To(HaveLen(2))+ Expect(out.MatchedIDs[0]).To(Equal("mf-hit"))+ Expect(out.MatchedIDs[1]).To(BeEmpty())+ Expect(out.Starred[0]).To(BeFalse()) // no user scope → no annotations++ By("matching as a user, exposing that user's annotations across the boundary")+ scoped := call(tIn{Songs: songs, Username: "alice"})+ Expect(scoped.MatchedIDs[0]).To(Equal("mf-hit"))+ Expect(scoped.Starred[0]).To(BeTrue())+ })+})++// ctxCapturingDataStore records the context passed to MediaFile so tests can assert+// which user the matcher resolved before querying the library.+type ctxCapturingDataStore struct {+ *tests.MockDataStore+ lastMediaFileCtx context.Context+}++func (d *ctxCapturingDataStore) MediaFile(ctx context.Context) model.MediaFileRepository {+ d.lastMediaFileCtx = ctx+ return d.MockDataStore.MediaFile(ctx)+}diff --git a/plugins/host_subsonicapi.go b/plugins/host_subsonicapi.goindex 01a33c039..dba58d795 100644--- a/plugins/host_subsonicapi.go+++ b/plugins/host_subsonicapi.go@@ -26,27 +26,19 @@ const subsonicAPIVersion = "1.16.1"// URL Format: Only the path and query parameters are used - host/protocol are ignored.// Automatic Parameters: The service adds 'c' (client), 'v' (version), and optionally 'f' (format).type subsonicAPIServiceImpl struct {- pluginID string- router SubsonicRouter- ds model.DataStore- allowedUserIDs []string // User IDs this plugin can access (from DB configuration)- allUsers bool // If true, plugin can access all users- userIDMap map[string]struct{}+ pluginID string+ router SubsonicRouter+ ds model.DataStore+ users userAccess // users this plugin may act as (from DB configuration)}// newSubsonicAPIService creates a new SubsonicAPIService for a plugin.-func newSubsonicAPIService(pluginID string, router SubsonicRouter, ds model.DataStore, allowedUserIDs []string, allUsers bool) host.SubsonicAPIService {- userIDMap := make(map[string]struct{})- for _, id := range allowedUserIDs {- userIDMap[id] = struct{}{}- }+func newSubsonicAPIService(pluginID string, router SubsonicRouter, ds model.DataStore, users userAccess) host.SubsonicAPIService {return &subsonicAPIServiceImpl{- pluginID: pluginID,- router: router,- ds: ds,- allowedUserIDs: allowedUserIDs,- allUsers: allUsers,- userIDMap: userIDMap,+ pluginID: pluginID,+ router: router,+ ds: ds,+ users: users,}}@@ -136,12 +128,12 @@ func (s *subsonicAPIServiceImpl) CallRaw(ctx context.Context, uri string) (strinfunc (s *subsonicAPIServiceImpl) checkPermissions(ctx context.Context, username string) error {// If allUsers is true, allow any user- if s.allUsers {+ if s.users.allUsers {return nil}// Must have at least one allowed user ID configured- if len(s.allowedUserIDs) == 0 {+ if len(s.users.userIDSet) == 0 {return fmt.Errorf("no users configured for plugin %s", s.pluginID)}@@ -155,7 +147,7 @@ func (s *subsonicAPIServiceImpl) checkPermissions(ctx context.Context, username}// Check if the user's ID is in the allowed list- if _, ok := s.userIDMap[usr.ID]; !ok {+ if !s.users.allows(usr.ID) {return fmt.Errorf("user %s is not authorized for this plugin", username)}diff --git a/plugins/host_subsonicapi_test.go b/plugins/host_subsonicapi_test.goindex 6f7ff4dd3..c3d9ffe8a 100644--- a/plugins/host_subsonicapi_test.go+++ b/plugins/host_subsonicapi_test.go@@ -267,7 +267,7 @@ var _ = Describe("SubsonicAPIService", func() {Context("with specific user IDs allowed", func() {It("blocks users not in the allowed list", func() {// allowedUserIDs contains "user2", but testuser is "user1"- service := newSubsonicAPIService("test-plugin", router, dataStore, []string{"user2"}, false)+ service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess([]string{"user2"}, false))ctx := GinkgoT().Context()_, err := service.Call(ctx, "/ping?u=testuser")@@ -277,7 +277,7 @@ var _ = Describe("SubsonicAPIService", func() {It("allows users in the allowed list", func() {// allowedUserIDs contains "user2" which is "alloweduser"- service := newSubsonicAPIService("test-plugin", router, dataStore, []string{"user2"}, false)+ service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess([]string{"user2"}, false))ctx := GinkgoT().Context()response, err := service.Call(ctx, "/ping?u=alloweduser")@@ -287,7 +287,7 @@ var _ = Describe("SubsonicAPIService", func() {It("blocks admin users when not in allowed list", func() {// allowedUserIDs only contains "user1" (testuser), not "admin1"- service := newSubsonicAPIService("test-plugin", router, dataStore, []string{"user1"}, false)+ service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess([]string{"user1"}, false))ctx := GinkgoT().Context()_, err := service.Call(ctx, "/ping?u=adminuser")@@ -297,7 +297,7 @@ var _ = Describe("SubsonicAPIService", func() {It("allows admin users when in allowed list", func() {// allowedUserIDs contains "admin1"- service := newSubsonicAPIService("test-plugin", router, dataStore, []string{"admin1"}, false)+ service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess([]string{"admin1"}, false))ctx := GinkgoT().Context()response, err := service.Call(ctx, "/ping?u=adminuser")@@ -308,7 +308,7 @@ var _ = Describe("SubsonicAPIService", func() {Context("with allUsers=true", func() {It("allows all users regardless of allowed list", func() {- service := newSubsonicAPIService("test-plugin", router, dataStore, nil, true)+ service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess(nil, true))ctx := GinkgoT().Context()response, err := service.Call(ctx, "/ping?u=testuser")@@ -317,7 +317,7 @@ var _ = Describe("SubsonicAPIService", func() {})It("allows admin users when allUsers is true", func() {- service := newSubsonicAPIService("test-plugin", router, dataStore, nil, true)+ service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess(nil, true))ctx := GinkgoT().Context()response, err := service.Call(ctx, "/ping?u=adminuser")@@ -328,7 +328,7 @@ var _ = Describe("SubsonicAPIService", func() {Context("with no users configured", func() {It("returns error when no users are configured", func() {- service := newSubsonicAPIService("test-plugin", router, dataStore, nil, false)+ service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess(nil, false))ctx := GinkgoT().Context()_, err := service.Call(ctx, "/ping?u=testuser")@@ -337,7 +337,7 @@ var _ = Describe("SubsonicAPIService", func() {})It("returns error for empty user list", func() {- service := newSubsonicAPIService("test-plugin", router, dataStore, []string{}, false)+ service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess([]string{}, false))ctx := GinkgoT().Context()_, err := service.Call(ctx, "/ping?u=testuser")@@ -349,7 +349,7 @@ var _ = Describe("SubsonicAPIService", func() {Describe("URL Handling", func() {It("returns error for missing username parameter", func() {- service := newSubsonicAPIService("test-plugin", router, dataStore, nil, true)+ service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess(nil, true))ctx := GinkgoT().Context()_, err := service.Call(ctx, "/ping")@@ -358,7 +358,7 @@ var _ = Describe("SubsonicAPIService", func() {})It("returns error for invalid URL", func() {- service := newSubsonicAPIService("test-plugin", router, dataStore, nil, true)+ service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess(nil, true))ctx := GinkgoT().Context()_, err := service.Call(ctx, "://invalid")@@ -367,7 +367,7 @@ var _ = Describe("SubsonicAPIService", func() {})It("extracts endpoint from path correctly", func() {- service := newSubsonicAPIService("test-plugin", router, dataStore, []string{"user1"}, false)+ service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess([]string{"user1"}, false))ctx := GinkgoT().Context()_, err := service.Call(ctx, "/rest/ping.view?u=testuser")@@ -380,7 +380,7 @@ var _ = Describe("SubsonicAPIService", func() {Describe("CallRaw", func() {It("returns binary data and content-type", func() {- service := newSubsonicAPIService("test-plugin", router, dataStore, nil, true)+ service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess(nil, true))ctx := GinkgoT().Context()contentType, data, err := service.CallRaw(ctx, "/getCoverArt?u=testuser&id=al-1")@@ -390,7 +390,7 @@ var _ = Describe("SubsonicAPIService", func() {})It("does not set f=json parameter", func() {- service := newSubsonicAPIService("test-plugin", router, dataStore, nil, true)+ service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess(nil, true))ctx := GinkgoT().Context()_, _, err := service.CallRaw(ctx, "/getCoverArt?u=testuser&id=al-1")@@ -402,7 +402,7 @@ var _ = Describe("SubsonicAPIService", func() {})It("enforces permission checks", func() {- service := newSubsonicAPIService("test-plugin", router, dataStore, []string{"user2"}, false)+ service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess([]string{"user2"}, false))ctx := GinkgoT().Context()_, _, err := service.CallRaw(ctx, "/getCoverArt?u=testuser&id=al-1")@@ -411,7 +411,7 @@ var _ = Describe("SubsonicAPIService", func() {})It("returns error when username is missing", func() {- service := newSubsonicAPIService("test-plugin", router, dataStore, nil, true)+ service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess(nil, true))ctx := GinkgoT().Context()_, _, err := service.CallRaw(ctx, "/getCoverArt")@@ -420,7 +420,7 @@ var _ = Describe("SubsonicAPIService", func() {})It("returns error when router is nil", func() {- service := newSubsonicAPIService("test-plugin", nil, dataStore, nil, true)+ service := newSubsonicAPIService("test-plugin", nil, dataStore, newUserAccess(nil, true))ctx := GinkgoT().Context()_, _, err := service.CallRaw(ctx, "/getCoverArt?u=testuser")@@ -429,7 +429,7 @@ var _ = Describe("SubsonicAPIService", func() {})It("returns error for invalid URL", func() {- service := newSubsonicAPIService("test-plugin", router, dataStore, nil, true)+ service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess(nil, true))ctx := GinkgoT().Context()_, _, err := service.CallRaw(ctx, "://invalid")@@ -440,7 +440,7 @@ var _ = Describe("SubsonicAPIService", func() {Describe("Router Availability", func() {It("returns error when router is nil", func() {- service := newSubsonicAPIService("test-plugin", nil, dataStore, nil, true)+ service := newSubsonicAPIService("test-plugin", nil, dataStore, newUserAccess(nil, true))ctx := GinkgoT().Context()_, err := service.Call(ctx, "/ping?u=testuser")diff --git a/plugins/manager_loader.go b/plugins/manager_loader.goindex 115c6c2b0..604fba3a7 100644--- a/plugins/manager_loader.go+++ b/plugins/manager_loader.go@@ -52,7 +52,7 @@ var hostServices = []hostServiceEntry{name: "SubsonicAPI",hasPermission: func(p *Permissions) bool { return p != nil && p.Subsonicapi != nil },create: func(ctx *serviceContext) ([]extism.HostFunction, io.Closer) {- service := newSubsonicAPIService(ctx.pluginName, ctx.manager.subsonicRouter, ctx.manager.ds, ctx.allowedUsers, ctx.allUsers)+ service := newSubsonicAPIService(ctx.pluginName, ctx.manager.subsonicRouter, ctx.manager.ds, newUserAccess(ctx.allowedUsers, ctx.allUsers))return host.RegisterSubsonicAPIHostFunctions(service), nil},},@@ -119,6 +119,19 @@ var hostServices = []hostServiceEntry{return host.RegisterUsersHostFunctions(service), nil},},+ {+ name: "Matcher",+ hasPermission: func(p *Permissions) bool { return p != nil && p.Matcher != nil },+ create: func(ctx *serviceContext) ([]extism.HostFunction, io.Closer) {+ hasFilesystemPerm := ctx.permissions.Library != nil && ctx.permissions.Library.Filesystem+ service := newMatcherService(+ ctx.manager.ds, hasFilesystemPerm,+ newUserAccess(ctx.allowedUsers, ctx.allUsers),+ newLibraryAccess(ctx.allowedLibraries, ctx.allLibraries),+ )+ return host.RegisterMatcherHostFunctions(service), nil+ },+ },{name: "HTTP",hasPermission: func(p *Permissions) bool { return p != nil && p.Http != nil },diff --git a/plugins/manager_plugin.go b/plugins/manager_plugin.goindex 1d4a8c301..f0c7c56d5 100644--- a/plugins/manager_plugin.go+++ b/plugins/manager_plugin.go@@ -4,9 +4,11 @@ import ("context""crypto/rand""errors"+ "fmt""io"extism "github.com/extism/go-sdk"+ "github.com/navidrome/navidrome/model""github.com/tetratelabs/wazero")@@ -75,3 +77,58 @@ func (a libraryAccess) contains(libID int) bool {_, ok := a.libraryIDSet[libID]return ok}++// configured reports whether the plugin has any library scope (all, or specific).+func (a libraryAccess) configured() bool {+ return a.allLibraries || len(a.libraryIDSet) > 0+}++// userAccess captures the set of users a plugin is permitted to act as,+// precomputed at load time for O(1) lookup.+type userAccess struct {+ allUsers bool+ userIDSet map[string]struct{}+}++func newUserAccess(allowedUserIDs []string, allUsers bool) userAccess {+ set := make(map[string]struct{}, len(allowedUserIDs))+ for _, id := range allowedUserIDs {+ set[id] = struct{}{}+ }+ return userAccess{allUsers: allUsers, userIDSet: set}+}++// allows reports whether the plugin may act as the given user ID.+func (a userAccess) allows(userID string) bool {+ if a.allUsers {+ return true+ }+ _, ok := a.userIDSet[userID]+ return ok+}++// resolve looks up a user by username and authorizes it against this access set,+// distinguishing an absent user from a backend failure.+//+// When the plugin has no user scope at all, it rejects before the lookup with a+// single fixed error, so a caller cannot tell a real account from a missing one by+// the error text (username enumeration).+func (a userAccess) resolve(ctx context.Context, ds model.DataStore, username string) (*model.User, error) {+ if !a.allUsers && len(a.userIDSet) == 0 {+ return nil, fmt.Errorf("plugin is not authorized to scope by user")+ }+ usr, err := ds.User(ctx).FindByUsername(username)+ if err != nil {+ if errors.Is(err, model.ErrNotFound) {+ return nil, fmt.Errorf("user %q not found", username)+ }+ return nil, fmt.Errorf("looking up user %q: %w", username, err)+ }+ if usr == nil { // defensive: a conforming repo returns ErrNotFound, not (nil, nil)+ return nil, fmt.Errorf("user %q not found", username)+ }+ if !a.allows(usr.ID) {+ return nil, fmt.Errorf("plugin is not allowed to act as user %q", username)+ }+ return usr, nil+}diff --git a/plugins/manifest-schema.json b/plugins/manifest-schema.jsonindex c15a3bf3d..29e5d1fc7 100644--- a/plugins/manifest-schema.json+++ b/plugins/manifest-schema.json@@ -113,6 +113,9 @@},"taskqueue": {"$ref": "#/$defs/TaskQueuePermission"+ },+ "matcher": {+ "$ref": "#/$defs/MatcherPermission"}}},@@ -254,6 +257,17 @@"description": "Explanation for why users access is needed"}}+ },+ "MatcherPermission": {+ "type": "object",+ "description": "Matcher service permissions for resolving external songs to local library tracks",+ "additionalProperties": false,+ "properties": {+ "reason": {+ "type": "string",+ "description": "Explanation for why matcher access is needed"+ }+ }}}}diff --git a/plugins/manifest.go b/plugins/manifest.goindex 990272855..6bd0e8049 100644--- a/plugins/manifest.go+++ b/plugins/manifest.go@@ -59,6 +59,14 @@ func (m *Manifest) Validate() error {}}+ // Matcher returns library content, so it requires the library permission (which+ // is what exposes a library scope for configuration).+ if m.Permissions != nil && m.Permissions.Matcher != nil {+ if m.Permissions.Library == nil {+ return fmt.Errorf("'matcher' permission requires 'library' permission to be declared")+ }+ }+// Validate config schema if presentif m.Config != nil && m.Config.Schema != nil {if err := validateConfigSchema(m.Config.Schema); err != nil {diff --git a/plugins/manifest_gen.go b/plugins/manifest_gen.goindex efe93e05f..3599eafc4 100644--- a/plugins/manifest_gen.go+++ b/plugins/manifest_gen.go@@ -158,6 +158,12 @@ func (j *Manifest) UnmarshalJSON(value []byte) error {return nil}+// Matcher service permissions for resolving external songs to local library tracks+type MatcherPermission struct {+ // Explanation for why matcher access is needed+ Reason *string `json:"reason,omitempty" yaml:"reason,omitempty" mapstructure:"reason,omitempty"`+}+// Permissions required by the plugintype Permissions struct {// Artwork corresponds to the JSON schema field "artwork".@@ -175,6 +181,9 @@ type Permissions struct {// Library corresponds to the JSON schema field "library".Library *LibraryPermission `json:"library,omitempty" yaml:"library,omitempty" mapstructure:"library,omitempty"`+ // Matcher corresponds to the JSON schema field "matcher".+ Matcher *MatcherPermission `json:"matcher,omitempty" yaml:"matcher,omitempty" mapstructure:"matcher,omitempty"`+// Scheduler corresponds to the JSON schema field "scheduler".Scheduler *SchedulerPermission `json:"scheduler,omitempty" yaml:"scheduler,omitempty" mapstructure:"scheduler,omitempty"`diff --git a/plugins/manifest_test.go b/plugins/manifest_test.goindex cae043fc7..2a8b0dcfa 100644--- a/plugins/manifest_test.go+++ b/plugins/manifest_test.go@@ -261,6 +261,37 @@ var _ = Describe("Manifest", func() {Expect(err.Error()).To(ContainSubstring("subsonicapi"))})+ It("validates manifest with matcher and library permissions", func() {+ m := &Manifest{+ Name: "Test",+ Author: "Author",+ Version: "1.0.0",+ Permissions: &Permissions{+ Matcher: &MatcherPermission{},+ Library: &LibraryPermission{},+ },+ }++ err := m.Validate()+ Expect(err).ToNot(HaveOccurred())+ })++ It("returns error when matcher without library permission", func() {+ m := &Manifest{+ Name: "Test",+ Author: "Author",+ Version: "1.0.0",+ Permissions: &Permissions{+ Matcher: &MatcherPermission{},+ },+ }++ err := m.Validate()+ Expect(err).To(HaveOccurred())+ Expect(err.Error()).To(ContainSubstring("matcher"))+ Expect(err.Error()).To(ContainSubstring("library"))+ })+It("validates manifest without subsonicapi", func() {m := &Manifest{Name: "Test",diff --git a/plugins/metadata_agent.go b/plugins/metadata_agent.goindex fa3e0082e..e5d6d43fc 100644--- a/plugins/metadata_agent.go+++ b/plugins/metadata_agent.go@@ -250,7 +250,7 @@ func songRefToAgentSong(s types.SongRef) agents.Song {Artists: artists,Album: s.Album,AlbumMBID: s.AlbumMBID,- Duration: uint32(s.Duration * 1000),+ Duration: s.DurationInMs(),}}diff --git a/plugins/pdk/go/host/doc.go b/plugins/pdk/go/host/doc.goindex 5781a04c1..ff2c2a07f 100644--- a/plugins/pdk/go/host/doc.go+++ b/plugins/pdk/go/host/doc.go@@ -41,6 +41,7 @@ The following host services are available:- HTTP: provides outbound HTTP request capabilities for plugins.- KVStore: provides persistent key-value storage for plugins.- Library: provides access to music library metadata for plugins.+ - Matcher: resolves externally-obtained songs to local library tracks,- Scheduler: provides task scheduling capabilities for plugins.- SubsonicAPI: provides access to Navidrome's Subsonic API from plugins.- Task: provides persistent task queues for plugins.diff --git a/plugins/pdk/go/host/nd_host_matcher.go b/plugins/pdk/go/host/nd_host_matcher.gonew file mode 100644index 000000000..b32ac6f9d--- /dev/null+++ b/plugins/pdk/go/host/nd_host_matcher.go@@ -0,0 +1,77 @@+// Code generated by ndpgen. DO NOT EDIT.+//+// This file contains client wrappers for the Matcher host service.+// It is intended for use in Navidrome plugins built with TinyGo.+//+//go:build wasip1++package host++import (+ "encoding/json"+ "errors"++ "github.com/navidrome/navidrome/plugins/pdk/go/types"++ "github.com/navidrome/navidrome/plugins/pdk/go/pdk"+)++// MatchOptions represents the MatchOptions data structure.+// MatchOptions carries optional parameters for a match request.+type MatchOptions struct {+ Username string `json:"username"`+}++// matcher_matchsongs is the host function provided by Navidrome.+//+//go:wasmimport extism:host/user matcher_matchsongs+func matcher_matchsongs(uint64) uint64++type matcherMatchSongsRequest struct {+ Songs []types.SongRef `json:"songs"`+ Opts MatchOptions `json:"opts"`+}++type matcherMatchSongsResponse struct {+ Results []*types.Track `json:"results,omitempty"`+ Error string `json:"error,omitempty"`+}++// MatcherMatchSongs calls the matcher_matchsongs host function.+// MatchSongs resolves each input song to its best-matching library track.+// It returns one entry per input song, in the same order as the input; the+// entry for an input song that had no match is empty (absent). Results are+// limited to the libraries the plugin (and the scoped user, if any) can access.+func MatcherMatchSongs(songs []types.SongRef, opts MatchOptions) ([]*types.Track, error) {+ // Marshal request to JSON+ req := matcherMatchSongsRequest{+ Songs: songs,+ Opts: opts,+ }+ reqBytes, err := json.Marshal(req)+ if err != nil {+ return nil, err+ }+ reqMem := pdk.AllocateBytes(reqBytes)+ defer reqMem.Free()++ // Call the host function+ responsePtr := matcher_matchsongs(reqMem.Offset())++ // Read the response from memory+ responseMem := pdk.FindMemory(responsePtr)+ responseBytes := responseMem.ReadBytes()++ // Parse the response+ var response matcherMatchSongsResponse+ if err := json.Unmarshal(responseBytes, &response); err != nil {+ return nil, err+ }++ // Convert Error field to Go error+ if response.Error != "" {+ return nil, errors.New(response.Error)+ }++ return response.Results, nil+}diff --git a/plugins/pdk/go/host/nd_host_matcher_stub.go b/plugins/pdk/go/host/nd_host_matcher_stub.gonew file mode 100644index 000000000..07b34bb82--- /dev/null+++ b/plugins/pdk/go/host/nd_host_matcher_stub.go@@ -0,0 +1,44 @@+// Code generated by ndpgen. DO NOT EDIT.+//+// This file contains mock implementations for non-WASM builds.+// These mocks allow IDE support, compilation, and unit testing on non-WASM platforms.+// Plugin authors can use the exported mock instances to set expectations in tests.+//+//go:build !wasip1++package host++import (+ "github.com/navidrome/navidrome/plugins/pdk/go/types"+ "github.com/stretchr/testify/mock"+)++// MatchOptions represents the MatchOptions data structure.+// MatchOptions carries optional parameters for a match request.+type MatchOptions struct {+ Username string `json:"username"`+}++// mockMatcherService is the mock implementation for testing.+type mockMatcherService struct {+ mock.Mock+}++// MatcherMock is the auto-instantiated mock instance for testing.+// Use this to set expectations: host.MatcherMock.On("MethodName", args...).Return(values...)+var MatcherMock = &mockMatcherService{}++// MatchSongs is the mock method for MatcherMatchSongs.+func (m *mockMatcherService) MatchSongs(songs []types.SongRef, opts MatchOptions) ([]*types.Track, error) {+ args := m.Called(songs, opts)+ return args.Get(0).([]*types.Track), args.Error(1)+}++// MatcherMatchSongs delegates to the mock instance.+// MatchSongs resolves each input song to its best-matching library track.+// It returns one entry per input song, in the same order as the input; the+// entry for an input song that had no match is empty (absent). Results are+// limited to the libraries the plugin (and the scoped user, if any) can access.+func MatcherMatchSongs(songs []types.SongRef, opts MatchOptions) ([]*types.Track, error) {+ return MatcherMock.MatchSongs(songs, opts)+}diff --git a/plugins/pdk/go/types/types.go b/plugins/pdk/go/types/types.goindex 856be90e1..4d4cdedd2 100644--- a/plugins/pdk/go/types/types.go+++ b/plugins/pdk/go/types/types.go@@ -8,7 +8,8 @@ package types// ArtistRef is the minimal information a plugin returns for Navidrome to match an// artist against the library. It is a reference, not a full artist entity: it-// carries only matching keys (name and optional internal/MusicBrainz IDs), never+// carries only matching keys (name and optional internal/MusicBrainz IDs) plus a+// few projection fields used when describing a track's participants, never// descriptive data such as biographies or images.type ArtistRef struct {// ID is the internal Navidrome artist ID (if known).@@ -17,6 +18,12 @@ type ArtistRef struct {Name string `json:"name"`// MBID is the MusicBrainz ID for the artist.MBID string `json:"mbid,omitempty"`+ // SortName is the artist name used for sorting (if known).+ SortName string `json:"sortName,omitempty"`+ // Role is the participation category (e.g. "artist", "composer", "performer").+ Role string `json:"role,omitempty"`+ // SubRole is a specialization within Role (e.g. the instrument for a performer).+ SubRole string `json:"subRole,omitempty"`}// SongRef is the minimal information exchanged between a plugin and Navidrome to@@ -34,8 +41,12 @@ type SongRef struct {// ISRC is the International Standard Recording Code for the song.ISRC string `json:"isrc,omitempty"`// Artist is the artist name.+ //+ // Deprecated: use Artists.Artist string `json:"artist,omitempty"`// ArtistMBID is the MusicBrainz artist ID.+ //+ // Deprecated: use Artists.ArtistMBID string `json:"artistMbid,omitempty"`// Artists is the full artist list; when set, takes precedence over Artist/ArtistMBID for matching.Artists []ArtistRef `json:"artists,omitempty"`@@ -44,5 +55,94 @@ type SongRef struct {// AlbumMBID is the MusicBrainz release ID.AlbumMBID string `json:"albumMbid,omitempty"`// Duration is the song duration in seconds.+ //+ // Deprecated: use DurationMs, which carries millisecond precision. When+ // DurationMs is non-zero it takes precedence; Duration is kept only for+ // backwards compatibility with plugins that still send seconds.Duration float32 `json:"duration,omitempty"`+ // DurationMs is the song duration in milliseconds. It supersedes Duration+ // when non-zero.+ DurationMs uint32 `json:"durationMs,omitempty"`+}++// Track is a stable, public projection of a library media file for plugin consumption.+// It is a sane subset of the internal model.MediaFile, intended for reuse across host+// services and capabilities. Timestamps are Unix epoch seconds.+//+// Unlike SongRef, which is an abstract recording reference carrying only matching keys,+// Track is a concrete library entity: it identifies a specific media file that exists+// (or once existed) in the library and exposes its full descriptive metadata.+type Track struct {+ // Identity & location+ ID string `json:"id"`+ LibraryID int32 `json:"libraryId"`+ LibraryName string `json:"libraryName,omitempty"`+ Path string `json:"path,omitempty"`+ Missing bool `json:"missing"`+ // Core metadata+ Title string `json:"title"`+ Album string `json:"album"`+ Artist string `json:"artist"`+ AlbumArtist string `json:"albumArtist,omitempty"`+ AlbumID string `json:"albumId,omitempty"`+ SortTitle string `json:"sortTitle,omitempty"`+ SortAlbumName string `json:"sortAlbumName,omitempty"`+ SortArtistName string `json:"sortArtistName,omitempty"`+ // Track / disc / dates+ TrackNumber int32 `json:"trackNumber"`+ DiscNumber int32 `json:"discNumber"`+ DiscSubtitle string `json:"discSubtitle,omitempty"`+ Year int32 `json:"year"`+ Date string `json:"date,omitempty"`+ OriginalYear int32 `json:"originalYear"`+ OriginalDate string `json:"originalDate,omitempty"`+ ReleaseYear int32 `json:"releaseYear"`+ ReleaseDate string `json:"releaseDate,omitempty"`+ // Audio / file+ Size int64 `json:"size"`+ Suffix string `json:"suffix,omitempty"`+ Duration float64 `json:"duration"`+ BitRate int32 `json:"bitRate"`+ SampleRate int32 `json:"sampleRate"`+ BitDepth *int32 `json:"bitDepth,omitempty"`+ Channels int32 `json:"channels"`+ Codec string `json:"codec,omitempty"`+ // Descriptive+ Genres []string `json:"genres,omitempty"`+ Comment string `json:"comment,omitempty"`+ BPM *int32 `json:"bpm,omitempty"`+ ExplicitStatus string `json:"explicitStatus,omitempty"`+ CatalogNum string `json:"catalogNum,omitempty"`+ Compilation bool `json:"compilation"`+ HasCoverArt bool `json:"hasCoverArt"`+ // MusicBrainz+ MbzRecordingID string `json:"mbzRecordingId,omitempty"`+ MbzReleaseTrackID string `json:"mbzReleaseTrackId,omitempty"`+ MbzAlbumID string `json:"mbzAlbumId,omitempty"`+ MbzReleaseGroupID string `json:"mbzReleaseGroupId,omitempty"`+ MbzAlbumType string `json:"mbzAlbumType,omitempty"`+ MbzAlbumComment string `json:"mbzAlbumComment,omitempty"`+ // ReplayGain — nil means no data; 0 is a valid measured value, so these+ // must stay pointers to distinguish "absent" from "0".+ RGAlbumGain *float64 `json:"rgAlbumGain,omitempty"`+ RGAlbumPeak *float64 `json:"rgAlbumPeak,omitempty"`+ RGTrackGain *float64 `json:"rgTrackGain,omitempty"`+ RGTrackPeak *float64 `json:"rgTrackPeak,omitempty"`+ // Timestamps (Unix epoch seconds)+ BirthTime int64 `json:"birthTime"`+ CreatedAt int64 `json:"createdAt"`+ UpdatedAt int64 `json:"updatedAt"`+ // AverageRating is the track's mean rating across all users (always set; 0 when unrated).+ AverageRating float64 `json:"averageRating"`+ // Per-user annotations, set only for a user-scoped match. Timestamps are Unix+ // seconds; a nil pointer means "no value".+ Starred bool `json:"starred,omitempty"`+ StarredAt *int64 `json:"starredAt,omitempty"`+ Rating int32 `json:"rating,omitempty"`+ PlayCount int64 `json:"playCount,omitempty"`+ PlayDate *int64 `json:"playDate,omitempty"`+ // Composite+ Tags map[string][]string `json:"tags,omitempty"`+ // Participants lists the track's artists across all roles, each tagged with its Role.+ Participants []ArtistRef `json:"participants,omitempty"`}diff --git a/plugins/pdk/rust/nd-pdk-host/src/lib.rs b/plugins/pdk/rust/nd-pdk-host/src/lib.rsindex 3a31bc489..cc1fdc190 100644--- a/plugins/pdk/rust/nd-pdk-host/src/lib.rs+++ b/plugins/pdk/rust/nd-pdk-host/src/lib.rs@@ -38,6 +38,7 @@//! - [`http`] - provides outbound HTTP request capabilities for plugins.//! - [`kvstore`] - provides persistent key-value storage for plugins.//! - [`library`] - provides access to music library metadata for plugins.+//! - [`matcher`] - resolves externally-obtained songs to local library tracks,//! - [`scheduler`] - provides task scheduling capabilities for plugins.//! - [`subsonicapi`] - provides access to Navidrome's Subsonic API from plugins.//! - [`task`] - provides persistent task queues for plugins.@@ -86,6 +87,13 @@ pub mod library {pub use super::nd_host_library::*;}+#[doc(hidden)]+mod nd_host_matcher;+/// resolves externally-obtained songs to local library tracks,+pub mod matcher {+ pub use super::nd_host_matcher::*;+}+#[doc(hidden)]mod nd_host_scheduler;/// provides task scheduling capabilities for plugins.diff --git a/plugins/pdk/rust/nd-pdk-host/src/nd_host_matcher.rs b/plugins/pdk/rust/nd-pdk-host/src/nd_host_matcher.rsnew file mode 100644index 000000000..be2819257--- /dev/null+++ b/plugins/pdk/rust/nd-pdk-host/src/nd_host_matcher.rs@@ -0,0 +1,65 @@+// Code generated by ndpgen. DO NOT EDIT.+//+// This file contains client wrappers for the Matcher host service.+// It is intended for use in Navidrome plugins built with extism-pdk.++use extism_pdk::*;+use serde::{Deserialize, Serialize};++/// MatchOptions carries optional parameters for a match request.+#[derive(Debug, Clone, Serialize, Deserialize)]+#[serde(rename_all = "camelCase")]+pub struct MatchOptions {+ #[serde(default)]+ pub username: String,+}++#[derive(Debug, Clone, Serialize)]+#[serde(rename_all = "camelCase")]+struct MatcherMatchSongsRequest {+ songs: Vec<nd_pdk_types::SongRef>,+ opts: MatchOptions,+}++#[derive(Debug, Clone, Deserialize)]+#[serde(rename_all = "camelCase")]+struct MatcherMatchSongsResponse {+ #[serde(default)]+ results: Vec<Option<nd_pdk_types::Track>>,+ #[serde(default)]+ error: Option<String>,+}++#[host_fn]+extern "ExtismHost" {+ fn matcher_matchsongs(input: Json<MatcherMatchSongsRequest>) -> Json<MatcherMatchSongsResponse>;+}++/// MatchSongs resolves each input song to its best-matching library track.+/// It returns one entry per input song, in the same order as the input; the+/// entry for an input song that had no match is empty (absent). Results are+/// limited to the libraries the plugin (and the scoped user, if any) can access.+///+/// # Arguments+/// * `songs` - Vec<nd_pdk_types::SongRef> parameter.+/// * `opts` - MatchOptions parameter.+///+/// # Returns+/// The results value.+///+/// # Errors+/// Returns an error if the host function call fails.+pub fn match_songs(songs: Vec<nd_pdk_types::SongRef>, opts: MatchOptions) -> Result<Vec<Option<nd_pdk_types::Track>>, Error> {+ let response = unsafe {+ matcher_matchsongs(Json(MatcherMatchSongsRequest {+ songs: songs,+ opts: opts,+ }))?+ };++ if let Some(err) = response.0.error {+ return Err(Error::msg(err));+ }++ Ok(response.0.results)+}diff --git a/plugins/pdk/rust/nd-pdk-types/src/lib.rs b/plugins/pdk/rust/nd-pdk-types/src/lib.rsindex 9b40c4d56..fa1a87048 100644--- a/plugins/pdk/rust/nd-pdk-types/src/lib.rs+++ b/plugins/pdk/rust/nd-pdk-types/src/lib.rs@@ -3,6 +3,7 @@//! Navidrome shared plugin data types.use serde::{Deserialize, Serialize};+use std::collections::HashMap;// Helper functions for skip_serializing_if with numeric types#[allow(dead_code)]@@ -19,7 +20,8 @@ fn is_zero_f32(value: &f32) -> bool { *value == 0.0 }fn is_zero_f64(value: &f64) -> bool { *value == 0.0 }/// ArtistRef is the minimal information a plugin returns for Navidrome to match an/// artist against the library. It is a reference, not a full artist entity: it-/// carries only matching keys (name and optional internal/MusicBrainz IDs), never+/// carries only matching keys (name and optional internal/MusicBrainz IDs) plus a+/// few projection fields used when describing a track's participants, never/// descriptive data such as biographies or images.#[derive(Debug, Clone, Default, Serialize, Deserialize)]#[serde(rename_all = "camelCase")]@@ -33,6 +35,15 @@ pub struct ArtistRef {/// MBID is the MusicBrainz ID for the artist.#[serde(default, skip_serializing_if = "String::is_empty")]pub mbid: String,+ /// SortName is the artist name used for sorting (if known).+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub sort_name: String,+ /// Role is the participation category (e.g. "artist", "composer", "performer").+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub role: String,+ /// SubRole is a specialization within Role (e.g. the instrument for a performer).+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub sub_role: String,}/// SongRef is the minimal information exchanged between a plugin and Navidrome to/// match a song. It is used both as input (a song Navidrome already has) and as@@ -55,9 +66,13 @@ pub struct SongRef {#[serde(default, skip_serializing_if = "String::is_empty")]pub isrc: String,/// Artist is the artist name.+ ///+ /// Deprecated: use Artists.#[serde(default, skip_serializing_if = "String::is_empty")]pub artist: String,/// ArtistMBID is the MusicBrainz artist ID.+ ///+ /// Deprecated: use Artists.#[serde(default, skip_serializing_if = "String::is_empty")]pub artist_mbid: String,/// Artists is the full artist list; when set, takes precedence over Artist/ArtistMBID for matching.@@ -70,6 +85,155 @@ pub struct SongRef {#[serde(default, skip_serializing_if = "String::is_empty")]pub album_mbid: String,/// Duration is the song duration in seconds.+ ///+ /// Deprecated: use DurationMs, which carries millisecond precision. When+ /// DurationMs is non-zero it takes precedence; Duration is kept only for+ /// backwards compatibility with plugins that still send seconds.#[serde(default, skip_serializing_if = "is_zero_f32")]pub duration: f32,+ /// DurationMs is the song duration in milliseconds. It supersedes Duration+ /// when non-zero.+ #[serde(default, skip_serializing_if = "is_zero_u32")]+ pub duration_ms: u32,+}+/// Track is a stable, public projection of a library media file for plugin consumption.+/// It is a sane subset of the internal model.MediaFile, intended for reuse across host+/// services and capabilities. Timestamps are Unix epoch seconds.+///+/// Unlike SongRef, which is an abstract recording reference carrying only matching keys,+/// Track is a concrete library entity: it identifies a specific media file that exists+/// (or once existed) in the library and exposes its full descriptive metadata.+#[derive(Debug, Clone, Default, Serialize, Deserialize)]+#[serde(rename_all = "camelCase")]+pub struct Track {+ /// Identity & location+ #[serde(default)]+ pub id: String,+ #[serde(default)]+ pub library_id: i32,+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub library_name: String,+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub path: String,+ #[serde(default)]+ pub missing: bool,+ /// Core metadata+ #[serde(default)]+ pub title: String,+ #[serde(default)]+ pub album: String,+ #[serde(default)]+ pub artist: String,+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub album_artist: String,+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub album_id: String,+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub sort_title: String,+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub sort_album_name: String,+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub sort_artist_name: String,+ /// Track / disc / dates+ #[serde(default)]+ pub track_number: i32,+ #[serde(default)]+ pub disc_number: i32,+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub disc_subtitle: String,+ #[serde(default)]+ pub year: i32,+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub date: String,+ #[serde(default)]+ pub original_year: i32,+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub original_date: String,+ #[serde(default)]+ pub release_year: i32,+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub release_date: String,+ /// Audio / file+ #[serde(default)]+ pub size: i64,+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub suffix: String,+ #[serde(default)]+ pub duration: f64,+ #[serde(default)]+ pub bit_rate: i32,+ #[serde(default)]+ pub sample_rate: i32,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub bit_depth: Option<i32>,+ #[serde(default)]+ pub channels: i32,+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub codec: String,+ /// Descriptive+ #[serde(default, skip_serializing_if = "Vec::is_empty")]+ pub genres: Vec<String>,+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub comment: String,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub bpm: Option<i32>,+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub explicit_status: String,+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub catalog_num: String,+ #[serde(default)]+ pub compilation: bool,+ #[serde(default)]+ pub has_cover_art: bool,+ /// MusicBrainz+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub mbz_recording_id: String,+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub mbz_release_track_id: String,+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub mbz_album_id: String,+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub mbz_release_group_id: String,+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub mbz_album_type: String,+ #[serde(default, skip_serializing_if = "String::is_empty")]+ pub mbz_album_comment: String,+ /// ReplayGain — nil means no data; 0 is a valid measured value, so these+ /// must stay pointers to distinguish "absent" from "0".+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub rg_album_gain: Option<f64>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub rg_album_peak: Option<f64>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub rg_track_gain: Option<f64>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub rg_track_peak: Option<f64>,+ /// Timestamps (Unix epoch seconds)+ #[serde(default)]+ pub birth_time: i64,+ #[serde(default)]+ pub created_at: i64,+ #[serde(default)]+ pub updated_at: i64,+ /// AverageRating is the track's mean rating across all users (always set; 0 when unrated).+ #[serde(default)]+ pub average_rating: f64,+ /// Per-user annotations, set only for a user-scoped match. Timestamps are Unix+ /// seconds; a nil pointer means "no value".+ #[serde(default, skip_serializing_if = "std::ops::Not::not")]+ pub starred: bool,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub starred_at: Option<i64>,+ #[serde(default, skip_serializing_if = "is_zero_i32")]+ pub rating: i32,+ #[serde(default, skip_serializing_if = "is_zero_i64")]+ pub play_count: i64,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub play_date: Option<i64>,+ /// Composite+ #[serde(default, skip_serializing_if = "HashMap::is_empty")]+ pub tags: std::collections::HashMap<String, Vec<String>>,+ /// Participants lists the track's artists across all roles, each tagged with its Role.+ #[serde(default, skip_serializing_if = "Vec::is_empty")]+ pub participants: Vec<ArtistRef>,}diff --git a/plugins/sonic_similarity_adapter.go b/plugins/sonic_similarity_adapter.goindex 2d48b28f0..a4f7d73f8 100644--- a/plugins/sonic_similarity_adapter.go+++ b/plugins/sonic_similarity_adapter.go@@ -71,10 +71,10 @@ func mediaFileToSongRef(mf *model.MediaFile) types.SongRef {ArtistMBID: mf.MbzArtistID,Album: mf.Album,AlbumMBID: mf.MbzAlbumID,- Duration: mf.Duration,}+ ref.SetDuration(mf.Duration)for _, p := range mf.Participants[model.RoleArtist] {- ref.Artists = append(ref.Artists, capabilities.ArtistRef{ID: p.ID, Name: p.Name, MBID: p.MbzArtistID})+ ref.Artists = append(ref.Artists, types.ArtistRef{ID: p.ID, Name: p.Name, MBID: p.MbzArtistID, SortName: p.SortArtistName, Role: model.RoleArtist.String()})}if isrcs := mf.Tags.Values(model.TagISRC); len(isrcs) > 0 {ref.ISRC = isrcs[0]diff --git a/plugins/sonic_similarity_adapter_test.go b/plugins/sonic_similarity_adapter_test.goindex 52079732b..cb08b9acd 100644--- a/plugins/sonic_similarity_adapter_test.go+++ b/plugins/sonic_similarity_adapter_test.go@@ -122,8 +122,8 @@ var _ = Describe("mediaFileToSongRef multi-artist", func() {}}ref := mediaFileToSongRef(mf)Expect(ref.Artists).To(Equal([]capabilities.ArtistRef{- {ID: "ar-drake", Name: "Drake", MBID: "m-drake"},- {ID: "ar-future", Name: "Future", MBID: "m-future"},+ {ID: "ar-drake", Name: "Drake", MBID: "m-drake", Role: "artist"},+ {ID: "ar-future", Name: "Future", MBID: "m-future", Role: "artist"},}))})It("leaves Artists nil when the track has no role=artist participants", func() {diff --git a/plugins/testdata/test-matcher/go.mod b/plugins/testdata/test-matcher/go.modnew file mode 100644index 000000000..7abbc93c6--- /dev/null+++ b/plugins/testdata/test-matcher/go.mod@@ -0,0 +1,16 @@+module test-matcher++go 1.25++require github.com/navidrome/navidrome/plugins/pdk/go v0.0.0++require (+ github.com/davecgh/go-spew v1.1.1 // indirect+ github.com/extism/go-pdk v1.1.3 // indirect+ github.com/pmezard/go-difflib v1.0.0 // indirect+ github.com/stretchr/objx v0.5.2 // indirect+ github.com/stretchr/testify v1.11.1 // indirect+ gopkg.in/yaml.v3 v3.0.1 // indirect+)++replace github.com/navidrome/navidrome/plugins/pdk/go => ../../pdk/godiff --git a/plugins/testdata/test-matcher/go.sum b/plugins/testdata/test-matcher/go.sumnew file mode 100644index 000000000..af880eb51--- /dev/null+++ b/plugins/testdata/test-matcher/go.sum@@ -0,0 +1,14 @@+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=+github.com/extism/go-pdk v1.1.3 h1:hfViMPWrqjN6u67cIYRALZTZLk/enSPpNKa+rZ9X2SQ=+github.com/extism/go-pdk v1.1.3/go.mod h1:Gz+LIU/YCKnKXhgge8yo5Yu1F/lbv7KtKFkiCSzW/P4=+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=+github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=diff --git a/plugins/testdata/test-matcher/main.go b/plugins/testdata/test-matcher/main.gonew file mode 100644index 000000000..80d650b7b--- /dev/null+++ b/plugins/testdata/test-matcher/main.go@@ -0,0 +1,56 @@+// Test Matcher plugin for Navidrome plugin system integration tests.+// Build with: tinygo build -o ../test-matcher.wasm -target wasip1 -buildmode=c-shared .+package main++import (+ "github.com/navidrome/navidrome/plugins/pdk/go/host"+ "github.com/navidrome/navidrome/plugins/pdk/go/pdk"+ "github.com/navidrome/navidrome/plugins/pdk/go/types"+)++// TestMatcherInput is the input for the nd_test_matcher callback.+type TestMatcherInput struct {+ Songs []types.SongRef `json:"songs"`+ Username string `json:"username,omitempty"`+}++// TestMatcherOutput is the output from the nd_test_matcher callback.+// MatchedIDs and Starred are aligned to the input: an empty string at index i+// means no match; Starred[i] reflects the matched track's starred flag.+type TestMatcherOutput struct {+ MatchedIDs []string `json:"matched_ids"`+ Starred []bool `json:"starred"`+ Error *string `json:"error,omitempty"`+}++// nd_test_matcher forwards the input song list to the host matcher and returns matched track IDs.+//+//go:wasmexport nd_test_matcher+func ndTestMatcher() int32 {+ var input TestMatcherInput+ if err := pdk.InputJSON(&input); err != nil {+ errStr := err.Error()+ pdk.OutputJSON(TestMatcherOutput{Error: &errStr})+ return 0+ }++ results, err := host.MatcherMatchSongs(input.Songs, host.MatchOptions{Username: input.Username})+ if err != nil {+ errStr := err.Error()+ pdk.OutputJSON(TestMatcherOutput{Error: &errStr})+ return 0+ }++ ids := make([]string, len(results))+ starred := make([]bool, len(results))+ for i, t := range results {+ if t != nil {+ ids[i] = t.ID+ starred[i] = t.Starred+ }+ }+ pdk.OutputJSON(TestMatcherOutput{MatchedIDs: ids, Starred: starred})+ return 0+}++func main() {}diff --git a/plugins/testdata/test-matcher/manifest.json b/plugins/testdata/test-matcher/manifest.jsonnew file mode 100644index 000000000..26be5c577--- /dev/null+++ b/plugins/testdata/test-matcher/manifest.json@@ -0,0 +1,14 @@+{+ "name": "Test Matcher Plugin",+ "author": "Navidrome Test",+ "version": "1.0.0",+ "description": "A test plugin for Matcher integration testing",+ "permissions": {+ "matcher": {+ "reason": "For testing matcher operations"+ },+ "library": {+ "reason": "Matching returns library tracks"+ }+ }+}diff --git a/plugins/types/track.go b/plugins/types/track.gonew file mode 100644index 000000000..9b63c0f26--- /dev/null+++ b/plugins/types/track.go@@ -0,0 +1,93 @@+package types++// Track is a stable, public projection of a library media file for plugin consumption.+// It is a sane subset of the internal model.MediaFile, intended for reuse across host+// services and capabilities. Timestamps are Unix epoch seconds.+//+// Unlike SongRef, which is an abstract recording reference carrying only matching keys,+// Track is a concrete library entity: it identifies a specific media file that exists+// (or once existed) in the library and exposes its full descriptive metadata.+type Track struct {+ // Identity & location+ ID string `json:"id"`+ LibraryID int32 `json:"libraryId"`+ LibraryName string `json:"libraryName,omitempty"`+ Path string `json:"path,omitempty"`+ Missing bool `json:"missing"`++ // Core metadata+ Title string `json:"title"`+ Album string `json:"album"`+ Artist string `json:"artist"`+ AlbumArtist string `json:"albumArtist,omitempty"`+ AlbumID string `json:"albumId,omitempty"`+ SortTitle string `json:"sortTitle,omitempty"`+ SortAlbumName string `json:"sortAlbumName,omitempty"`+ SortArtistName string `json:"sortArtistName,omitempty"`++ // Track / disc / dates+ TrackNumber int32 `json:"trackNumber"`+ DiscNumber int32 `json:"discNumber"`+ DiscSubtitle string `json:"discSubtitle,omitempty"`+ Year int32 `json:"year"`+ Date string `json:"date,omitempty"`+ OriginalYear int32 `json:"originalYear"`+ OriginalDate string `json:"originalDate,omitempty"`+ ReleaseYear int32 `json:"releaseYear"`+ ReleaseDate string `json:"releaseDate,omitempty"`++ // Audio / file+ Size int64 `json:"size"`+ Suffix string `json:"suffix,omitempty"`+ Duration float64 `json:"duration"`+ BitRate int32 `json:"bitRate"`+ SampleRate int32 `json:"sampleRate"`+ BitDepth *int32 `json:"bitDepth,omitempty"`+ Channels int32 `json:"channels"`+ Codec string `json:"codec,omitempty"`++ // Descriptive+ Genres []string `json:"genres,omitempty"`+ Comment string `json:"comment,omitempty"`+ BPM *int32 `json:"bpm,omitempty"`+ ExplicitStatus string `json:"explicitStatus,omitempty"`+ CatalogNum string `json:"catalogNum,omitempty"`+ Compilation bool `json:"compilation"`+ HasCoverArt bool `json:"hasCoverArt"`++ // MusicBrainz+ MbzRecordingID string `json:"mbzRecordingId,omitempty"`+ MbzReleaseTrackID string `json:"mbzReleaseTrackId,omitempty"`+ MbzAlbumID string `json:"mbzAlbumId,omitempty"`+ MbzReleaseGroupID string `json:"mbzReleaseGroupId,omitempty"`+ MbzAlbumType string `json:"mbzAlbumType,omitempty"`+ MbzAlbumComment string `json:"mbzAlbumComment,omitempty"`++ // ReplayGain — nil means no data; 0 is a valid measured value, so these+ // must stay pointers to distinguish "absent" from "0".+ RGAlbumGain *float64 `json:"rgAlbumGain,omitempty"`+ RGAlbumPeak *float64 `json:"rgAlbumPeak,omitempty"`+ RGTrackGain *float64 `json:"rgTrackGain,omitempty"`+ RGTrackPeak *float64 `json:"rgTrackPeak,omitempty"`++ // Timestamps (Unix epoch seconds)+ BirthTime int64 `json:"birthTime"`+ CreatedAt int64 `json:"createdAt"`+ UpdatedAt int64 `json:"updatedAt"`++ // AverageRating is the track's mean rating across all users (always set; 0 when unrated).+ AverageRating float64 `json:"averageRating"`++ // Per-user annotations, set only for a user-scoped match. Timestamps are Unix+ // seconds; a nil pointer means "no value".+ Starred bool `json:"starred,omitempty"`+ StarredAt *int64 `json:"starredAt,omitempty"`+ Rating int32 `json:"rating,omitempty"`+ PlayCount int64 `json:"playCount,omitempty"`+ PlayDate *int64 `json:"playDate,omitempty"`++ // Composite+ Tags map[string][]string `json:"tags,omitempty"`+ // Participants lists the track's artists across all roles, each tagged with its Role.+ Participants []ArtistRef `json:"participants,omitempty"`+}diff --git a/plugins/types/types.go b/plugins/types/types.goindex eaccf3469..71928a924 100644--- a/plugins/types/types.go+++ b/plugins/types/types.go@@ -2,7 +2,8 @@ package types// ArtistRef is the minimal information a plugin returns for Navidrome to match an// artist against the library. It is a reference, not a full artist entity: it-// carries only matching keys (name and optional internal/MusicBrainz IDs), never+// carries only matching keys (name and optional internal/MusicBrainz IDs) plus a+// few projection fields used when describing a track's participants, never// descriptive data such as biographies or images.type ArtistRef struct {// ID is the internal Navidrome artist ID (if known).@@ -11,6 +12,12 @@ type ArtistRef struct {Name string `json:"name"`// MBID is the MusicBrainz ID for the artist.MBID string `json:"mbid,omitempty"`+ // SortName is the artist name used for sorting (if known).+ SortName string `json:"sortName,omitempty"`+ // Role is the participation category (e.g. "artist", "composer", "performer").+ Role string `json:"role,omitempty"`+ // SubRole is a specialization within Role (e.g. the instrument for a performer).+ SubRole string `json:"subRole,omitempty"`}// SongRef is the minimal information exchanged between a plugin and Navidrome to@@ -28,8 +35,12 @@ type SongRef struct {// ISRC is the International Standard Recording Code for the song.ISRC string `json:"isrc,omitempty"`// Artist is the artist name.+ //+ // Deprecated: use Artists.Artist string `json:"artist,omitempty"`// ArtistMBID is the MusicBrainz artist ID.+ //+ // Deprecated: use Artists.ArtistMBID string `json:"artistMbid,omitempty"`// Artists is the full artist list; when set, takes precedence over Artist/ArtistMBID for matching.Artists []ArtistRef `json:"artists,omitempty"`@@ -38,5 +49,39 @@ type SongRef struct {// AlbumMBID is the MusicBrainz release ID.AlbumMBID string `json:"albumMbid,omitempty"`// Duration is the song duration in seconds.+ //+ // Deprecated: use DurationMs, which carries millisecond precision. When+ // DurationMs is non-zero it takes precedence; Duration is kept only for+ // backwards compatibility with plugins that still send seconds.Duration float32 `json:"duration,omitempty"`+ // DurationMs is the song duration in milliseconds. It supersedes Duration+ // when non-zero.+ DurationMs uint32 `json:"durationMs,omitempty"`+}++// DurationInMs returns the song duration in milliseconds, preferring the+// millisecond-precision DurationMs and falling back to the deprecated+// seconds-based Duration. It returns 0 when neither is set, and clamps a+// negative seconds value to 0 to avoid an unsigned-conversion wraparound.+func (s SongRef) DurationInMs() uint32 {+ if s.DurationMs != 0 {+ return s.DurationMs+ }+ if s.Duration < 0 {+ return 0+ }+ return uint32(s.Duration * 1000)+}++// SetDuration sets the song duration from a value in seconds, populating both the+// millisecond-precision DurationMs and the deprecated seconds-based Duration so+// that plugins reading either field see a consistent value. Use this when+// building a SongRef to send to a plugin.+func (s *SongRef) SetDuration(seconds float32) {+ s.Duration = seconds+ if seconds < 0 {+ s.DurationMs = 0+ return+ }+ s.DurationMs = uint32(seconds * 1000)}diff --git a/plugins/types/types_suite_test.go b/plugins/types/types_suite_test.gonew file mode 100644index 000000000..9c058ec4f--- /dev/null+++ b/plugins/types/types_suite_test.go@@ -0,0 +1,17 @@+package types_test++import (+ "testing"++ "github.com/navidrome/navidrome/log"+ "github.com/navidrome/navidrome/tests"+ . "github.com/onsi/ginkgo/v2"+ . "github.com/onsi/gomega"+)++func TestTypes(t *testing.T) {+ tests.Init(t, false)+ log.SetLevel(log.LevelFatal)+ RegisterFailHandler(Fail)+ RunSpecs(t, "Plugins Types Suite")+}diff --git a/plugins/types/types_test.go b/plugins/types/types_test.gonew file mode 100644index 000000000..ae6d40a25--- /dev/null+++ b/plugins/types/types_test.go@@ -0,0 +1,50 @@+package types_test++import (+ "github.com/navidrome/navidrome/plugins/types"+ . "github.com/onsi/ginkgo/v2"+ . "github.com/onsi/gomega"+)++var _ = Describe("SongRef", func() {+ Describe("DurationInMs", func() {+ It("returns DurationMs when set", func() {+ s := types.SongRef{DurationMs: 247333, Duration: 247.5}+ Expect(s.DurationInMs()).To(Equal(uint32(247333)))+ })++ It("falls back to Duration (seconds) when DurationMs is zero", func() {+ s := types.SongRef{Duration: 247.5}+ Expect(s.DurationInMs()).To(Equal(uint32(247500)))+ })++ It("returns 0 when neither is set", func() {+ Expect(types.SongRef{}.DurationInMs()).To(BeZero())+ })++ It("clamps a negative seconds value to 0 instead of overflowing", func() {+ Expect(types.SongRef{Duration: -1}.DurationInMs()).To(BeZero())+ })+ })++ Describe("SetDuration", func() {+ It("populates both DurationMs and the deprecated Duration from seconds", func() {+ var s types.SongRef+ s.SetDuration(247.333)+ Expect(s.Duration).To(BeNumerically("~", 247.333, 0.001))+ Expect(s.DurationMs).To(Equal(uint32(247333)))+ })++ It("keeps DurationInMs consistent with what was set", func() {+ var s types.SongRef+ s.SetDuration(60)+ Expect(s.DurationInMs()).To(Equal(uint32(60000)))+ })++ It("clamps a negative duration to a zero DurationMs", func() {+ var s types.SongRef+ s.SetDuration(-1)+ Expect(s.DurationMs).To(BeZero())+ })+ })+})