Navidrome Plugin Capabilities
This directory contains the Go interface definitions for Navidrome plugin capabilities. These interfaces are the source of truth for plugin development and are used to generate:
- Go PDK packages (
pdk/go/*/) - Type-safe wrappers for Go plugin developers - XTP YAML schemas (
*.yaml) - Schema files for non-Go plugin developers
For Go Plugin Developers
Go developers should use the generated PDK packages in plugins/pdk/go/. See the example plugins in plugins/examples/ for usage patterns.
For Non-Go Plugin Developers
If you're developing plugins in other languages (TypeScript, Rust, Python, C#, Zig, C++), you can use the XTP CLI to generate type-safe bindings from the YAML schema files in this directory.
Prerequisites
Install the XTP CLI:
# macOS
brew install dylibso/tap/xtp
# Other platforms - see https://docs.xtp.dylibso.com/docs/cli
curl https://static.dylibso.com/cli/install.sh | bash
Generating Plugin Scaffolding
Use the XTP CLI to generate plugin boilerplate from any capability schema:
# TypeScript
xtp plugin init --schema-file plugins/capabilities/metadata_agent.yaml \
--template typescript --path my-plugin
# Rust
xtp plugin init --schema-file plugins/capabilities/scrobbler.yaml \
--template rust --path my-plugin
# Python
xtp plugin init --schema-file plugins/capabilities/lifecycle.yaml \
--template python --path my-plugin
# C#
xtp plugin init --schema-file plugins/capabilities/scheduler_callback.yaml \
--template csharp --path my-plugin
# Go (alternative to using the PDK packages)
xtp plugin init --schema-file plugins/capabilities/websocket_callback.yaml \
--template go --path my-plugin
Available Capabilities
| Capability | Schema File | Description |
|---|---|---|
| Metadata Agent | metadata_agent.yaml |
Fetch artist biographies, album images, and similar artists |
| Scrobbler | scrobbler.yaml |
Report listening activity to external services |
| Lifecycle | lifecycle.yaml |
Plugin initialization callbacks |
| Scheduler Callback | scheduler_callback.yaml |
Scheduled task execution |
| WebSocket Callback | websocket_callback.yaml |
Real-time WebSocket message handling |
Building Your Plugin
After generating the scaffolding, implement the required functions and build your plugin as a WebAssembly module. The exact build process depends on your chosen language - see the Extism PDK documentation for language-specific guides.
Schema Generation
The YAML schemas are automatically generated from the Go interfaces using ndpgen:
go run ./plugins/cmd/ndpgen -schemas -input=./plugins/capabilities
Technical Note: XTP Schema Compatibility
The generated schemas include type: object on object schemas. While this is technically not valid according to the XTP JSON Schema specification, it is required as a workaround for XTP's code generator to properly resolve type information (especially for structs with empty properties). XTP tolerates this with a validation warning but generates correct code.