2026-03-03 11:48:39 -09:00
|
|
|
version: v1-draft
|
|
|
|
|
exports:
|
|
|
|
|
nd_lyrics_get_lyrics:
|
|
|
|
|
input:
|
|
|
|
|
$ref: '#/components/schemas/GetLyricsRequest'
|
|
|
|
|
contentType: application/json
|
|
|
|
|
output:
|
|
|
|
|
$ref: '#/components/schemas/GetLyricsResponse'
|
|
|
|
|
contentType: application/json
|
|
|
|
|
components:
|
|
|
|
|
schemas:
|
|
|
|
|
ArtistRef:
|
|
|
|
|
description: ArtistRef is a reference to an artist with name and optional MBID.
|
|
|
|
|
properties:
|
|
|
|
|
id:
|
|
|
|
|
type: string
|
|
|
|
|
description: ID is the internal Navidrome artist ID (if known).
|
|
|
|
|
name:
|
|
|
|
|
type: string
|
|
|
|
|
description: Name is the artist name.
|
|
|
|
|
mbid:
|
|
|
|
|
type: string
|
|
|
|
|
description: MBID is the MusicBrainz ID for the artist.
|
|
|
|
|
required:
|
|
|
|
|
- name
|
|
|
|
|
GetLyricsRequest:
|
|
|
|
|
description: GetLyricsRequest contains the track information for lyrics lookup.
|
|
|
|
|
properties:
|
|
|
|
|
track:
|
|
|
|
|
$ref: '#/components/schemas/TrackInfo'
|
|
|
|
|
required:
|
|
|
|
|
- track
|
|
|
|
|
GetLyricsResponse:
|
|
|
|
|
description: GetLyricsResponse contains the lyrics returned by the plugin.
|
|
|
|
|
properties:
|
|
|
|
|
lyrics:
|
|
|
|
|
type: array
|
|
|
|
|
items:
|
|
|
|
|
$ref: '#/components/schemas/LyricsText'
|
|
|
|
|
required:
|
|
|
|
|
- lyrics
|
|
|
|
|
LyricsText:
|
|
|
|
|
description: |-
|
|
|
|
|
LyricsText represents a single set of lyrics in raw text format.
|
|
|
|
|
Text can be plain text or LRC format — Navidrome will parse it.
|
|
|
|
|
properties:
|
|
|
|
|
lang:
|
|
|
|
|
type: string
|
|
|
|
|
text:
|
|
|
|
|
type: string
|
|
|
|
|
required:
|
|
|
|
|
- text
|
|
|
|
|
TrackInfo:
|
|
|
|
|
description: TrackInfo contains track metadata.
|
|
|
|
|
properties:
|
|
|
|
|
id:
|
|
|
|
|
type: string
|
|
|
|
|
description: ID is the internal Navidrome track ID.
|
|
|
|
|
title:
|
|
|
|
|
type: string
|
|
|
|
|
description: Title is the track title.
|
|
|
|
|
album:
|
|
|
|
|
type: string
|
|
|
|
|
description: Album is the album name.
|
|
|
|
|
artist:
|
|
|
|
|
type: string
|
|
|
|
|
description: Artist is the formatted artist name for display (e.g., "Artist1 • Artist2").
|
|
|
|
|
albumArtist:
|
|
|
|
|
type: string
|
|
|
|
|
description: AlbumArtist is the formatted album artist name for display.
|
|
|
|
|
artists:
|
|
|
|
|
type: array
|
|
|
|
|
description: Artists is the list of track artists.
|
|
|
|
|
items:
|
|
|
|
|
$ref: '#/components/schemas/ArtistRef'
|
|
|
|
|
albumArtists:
|
|
|
|
|
type: array
|
|
|
|
|
description: AlbumArtists is the list of album artists.
|
|
|
|
|
items:
|
|
|
|
|
$ref: '#/components/schemas/ArtistRef'
|
|
|
|
|
duration:
|
|
|
|
|
type: number
|
|
|
|
|
format: float
|
|
|
|
|
description: Duration is the track duration in seconds.
|
|
|
|
|
trackNumber:
|
|
|
|
|
type: integer
|
|
|
|
|
format: int32
|
|
|
|
|
description: TrackNumber is the track number on the album.
|
|
|
|
|
discNumber:
|
|
|
|
|
type: integer
|
|
|
|
|
format: int32
|
|
|
|
|
description: DiscNumber is the disc number.
|
|
|
|
|
mbzRecordingId:
|
|
|
|
|
type: string
|
|
|
|
|
description: MBZRecordingID is the MusicBrainz recording ID.
|
|
|
|
|
mbzAlbumId:
|
|
|
|
|
type: string
|
|
|
|
|
description: MBZAlbumID is the MusicBrainz album/release ID.
|
|
|
|
|
mbzReleaseGroupId:
|
|
|
|
|
type: string
|
|
|
|
|
description: MBZReleaseGroupID is the MusicBrainz release group ID.
|
|
|
|
|
mbzReleaseTrackId:
|
|
|
|
|
type: string
|
|
|
|
|
description: MBZReleaseTrackID is the MusicBrainz release track ID.
|
feat(subsonic): add sonicSimilarity extension as plugin capability (#5419)
* feat(plugins): add sonicSimilarity capability types
Defines the SonicSimilarity plugin capability interface with
GetSonicSimilarTracks and FindSonicPath methods, along with
their request/response types.
* feat(sonic): add core sonic similarity service
Implements the Sonic service with HasProvider, GetSonicSimilarTracks,
and FindSonicPath, delegating to the PluginLoader and using the
Matcher for index-preserving library resolution.
* test(sonic): add sonic service unit tests
Covers HasProvider, GetSonicSimilarTracks, and FindSonicPath with
mock plugin loader and provider, verifying error propagation and
successful match resolution via the library matcher.
* feat(matcher): add MatchSongsToLibraryMap for index-preserving matching
Adds a new method alongside MatchSongsToLibrary that returns a
map[int]MediaFile keyed by input song index rather than a flat slice,
enabling callers to correlate similarity scores back to the original
position in the results.
* fix(sonic): check provider availability before MediaFile lookup
Avoids unnecessary DB call when no plugin is available, and ensures
the correct error path is tested.
* feat(plugins): add sonic similarity adapter
Adds SonicSimilarityAdapter implementing sonic.Provider, bridging the
plugin system to the core sonic service via Extism plugin functions.
Reuses existing songRefsToAgentSongs helper for SongRef conversion.
* feat(plugins): add LoadSonicSimilarity to plugin manager
Adds Manager.LoadSonicSimilarity method following the pattern of
LoadLyricsProvider, enabling the core sonic service to load a
SonicSimilarityAdapter from a named plugin.
* feat(subsonic): add sonicMatch response type
Add SonicMatch struct with Entry and Similarity fields, and a SonicMatches slice to the Subsonic response struct. These types support the OpenSubsonic sonicSimilarity extension for returning similarity-scored track results.
* feat(subsonic): add getSonicSimilarTracks and findSonicPath handlers
Add two new Subsonic API handlers for the sonicSimilarity OpenSubsonic extension: GetSonicSimilarTracks returns similarity-scored tracks similar to a given song, and FindSonicPath returns a path of tracks connecting two songs. Both handlers delegate to the sonic core service and map results to SonicMatch response types.
* feat(subsonic): advertise sonicSimilarity extension when plugin available
Update GetOpenSubsonicExtensions to conditionally include the sonicSimilarity extension only when a sonic similarity plugin provider is available. The nil guard ensures backward compatibility with tests that pass nil for the sonic field. Also update the existing test to pass the new nil parameter.
* feat(subsonic): wire sonic similarity service into router
Add the sonic.Sonic service to the Router struct and New() constructor, register the getSonicSimilarTracks and findSonicPath routes, and wire sonic.New and its PluginLoader binding into the Wire dependency injection graph. Update all existing test call sites to pass the new nil parameter. Regenerate wire_gen.go.
* fix(e2e): add sonic parameter to subsonic.New call in e2e tests
* test(subsonic): add sonicSimilarity extension advertisement tests
Restructures the GetOpenSubsonicExtensions test into two contexts: one verifying the baseline 5 extensions are returned when no sonic similarity plugin is configured, and one verifying that the sonicSimilarity extension is advertised (making 6 total) when a plugin loader reports an available provider. Adds a mockSonicPluginLoader to satisfy the sonic.PluginLoader interface without requiring a real plugin.
* feat(subsonic): add nil guard and e2e tests for sonic similarity endpoints
Handlers return ErrorDataNotFound when no sonic service is configured,
preventing nil panics. E2e tests verify both endpoints return proper
error responses when no plugin is available.
* fix(subsonic): return HTTP 404 when no sonic similarity plugin available
Endpoints are always registered but return 404 when no provider is
available, rather than a subsonic error code 70.
* refactor: clean up sonic similarity code after review
Extract shared helpers to reduce duplication across the sonic similarity
implementation: loadAllMatches in matcher consolidates the 4-phase
matching pipeline, songRefToAgentSong eliminates per-iteration slice
allocation in the adapter, sonicMatchResponse deduplicates response
building in handlers, and a package-level constant replaces raw
capability name strings in core/sonic.
* fix empty response shapes
Signed-off-by: Deluan <deluan@navidrome.org>
* test(plugins): add testdata plugin and e2e tests for sonic similarity
Add a test-sonic-similarity WASM plugin that implements both
GetSonicSimilarTracks and FindSonicPath via the generated sonicsimilarity
PDK. The plugin returns deterministic test data with decreasing similarity
scores and supports error injection via config. Adapter tests verify the
full round-trip through the WASM plugin including error handling. Also
includes regenerated PDK code from make gen.
* docs: update README to include new capabilities and usage examples for plugins
Signed-off-by: Deluan <deluan@navidrome.org>
* test(e2e): enhance sonic similarity tests with additional scenarios and mock provider
Signed-off-by: Deluan <deluan@navidrome.org>
* fix: address PR review feedback for sonic similarity
Fix incorrect field names in README documentation ({from, to} →
{startSong, endSong}) and remove unnecessary XML serialization test
from e2e suite since OpenSubsonic endpoints only use JSON.
* refactor: rename Matcher methods for conciseness
Rename MatchSongsToLibrary to MatchSongs and MatchSongsToLibraryMap to
MatchSongsIndexed. The Matcher receiver already establishes the "to
library" context, making that suffix redundant, and "Indexed" better
describes the intent (preserving input ordering) than "Map" which
describes the data structure.
* refactor: standardize variable naming for media files in sonic path methods
Signed-off-by: Deluan <deluan@navidrome.org>
* refactor: simplify plugin loading by introducing adapter constructors
Signed-off-by: Deluan <deluan@navidrome.org>
---------
Signed-off-by: Deluan <deluan@navidrome.org>
2026-04-27 13:50:09 -08:00
|
|
|
libraryId:
|
|
|
|
|
type: integer
|
|
|
|
|
format: int32
|
|
|
|
|
description: |-
|
|
|
|
|
LibraryID is the ID of the library the track belongs to.
|
|
|
|
|
Only included if the plugin has library permission with filesystem access for the track's library.
|
2026-04-12 06:27:58 -08:00
|
|
|
path:
|
|
|
|
|
type: string
|
|
|
|
|
description: |-
|
|
|
|
|
Path is the full path to the track file, relative to the library root.
|
|
|
|
|
Only included if the plugin has library permission with filesystem access for the track's library.
|
2026-03-03 11:48:39 -09:00
|
|
|
required:
|
|
|
|
|
- id
|
|
|
|
|
- title
|
|
|
|
|
- album
|
|
|
|
|
- artist
|
|
|
|
|
- albumArtist
|
|
|
|
|
- artists
|
|
|
|
|
- albumArtists
|
|
|
|
|
- duration
|
|
|
|
|
- trackNumber
|
|
|
|
|
- discNumber
|