mirror of
https://github.com/navidrome/navidrome.git
synced 2026-11-20 03:02:34 +03:00
* 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>
Navidrome Plugin Development Kit for Rust
This directory contains the Rust PDK crates for building Navidrome plugins.
Crate Structure
plugins/pdk/rust/
├── nd-pdk/ # Umbrella crate - use this as your dependency
├── nd-pdk-host/ # Host function wrappers (call Navidrome services)
└── nd-pdk-capabilities/ # Capability traits and types (generated)
Usage
Add the nd-pdk crate as a dependency in your plugin's Cargo.toml:
[package]
name = "my-plugin"
edition = "2021"
[lib]
crate-type = ["cdylib"]
[dependencies]
nd-pdk = { path = "../../pdk/rust/nd-pdk" }
extism-pdk = "1.2"
Implementing a Scrobbler (Required-All Pattern)
The Scrobbler capability requires all methods to be implemented:
use nd_pdk::scrobbler::{
Error, IsAuthorizedRequest,
NowPlayingRequest, ScrobbleRequest, Scrobbler,
};
// Register WASM exports for all Scrobbler methods
nd_pdk::register_scrobbler!(MyPlugin);
#[derive(Default)]
struct MyPlugin;
impl Scrobbler for MyPlugin {
fn is_authorized(&self, req: IsAuthorizedRequest) -> Result<bool, Error> {
Ok(true)
}
fn now_playing(&self, req: NowPlayingRequest) -> Result<(), Error> {
// Handle now playing notification
Ok(())
}
fn scrobble(&self, req: ScrobbleRequest) -> Result<(), Error> {
// Submit scrobble
Ok(())
}
}
Implementing Metadata Agent (Optional Pattern)
The MetadataAgent capability allows implementing individual methods:
use nd_pdk::metadata::{
ArtistBiographyProvider, GetArtistBiographyRequest, ArtistBiography, Error,
};
// Register only the methods you implement
nd_pdk::register_artist_biography!(MyPlugin);
#[derive(Default)]
struct MyPlugin;
impl ArtistBiographyProvider for MyPlugin {
fn get_artist_biography(&self, req: GetArtistBiographyRequest)
-> Result<ArtistBiography, Error>
{
// Return artist biography
Ok(ArtistBiography {
biography: "Artist bio text...".into(),
..Default::default()
})
}
}
Using Host Services
Access Navidrome services via the host module:
use nd_pdk::host::{artwork, scheduler, library};
// Get artwork URL for a track
let url = artwork::get_track_url("track-id", 300)?;
// Schedule a one-time callback
scheduler::schedule_one_time(60, "my-payload", "schedule-id")?;
// Get library information
let libs = library::get_all()?;
Available Capabilities
| Capability | Pattern | Description |
|---|---|---|
scrobbler |
Required-all | Submit listening history to external services |
metadata |
Optional | Provide artist/album metadata from external sources |
lifecycle |
Optional | Handle plugin initialization |
scheduler |
Optional | Receive scheduled callbacks |
websocket |
Optional | Handle WebSocket messages |
Building
Rust plugins must be compiled to WASM using the wasm32-wasip1 target:
cargo build --release --target wasm32-wasip1
The resulting .wasm file can be packaged into an .ndp plugin package.
Examples
See the example plugins for complete implementations:
- webhook-rs - Simple scrobbler using the PDK
- discord-rich-presence-rs - Complex plugin with multiple capabilities
- library-inspector-rs - Host service demonstration
Code Generation
The capability modules in nd-pdk-capabilities are auto-generated from the Go capability definitions. To regenerate after capability changes:
make gen
This generates both Go and Rust PDK code.