mirror of
https://github.com/navidrome/navidrome.git
synced 2026-03-04 06:35:52 +00:00
113 lines
3.6 KiB
Markdown
113 lines
3.6 KiB
Markdown
# Navidrome Plugin Examples
|
|
|
|
This folder contains example plugins for Navidrome that demonstrate how to build metadata agents using the plugin system.
|
|
|
|
## Building
|
|
|
|
### Prerequisites
|
|
|
|
- [TinyGo](https://tinygo.org/getting-started/install/) (recommended) or Go 1.23+ (for Go plugins)
|
|
- [extism-py](https://github.com/extism/python-pdk) (for Python plugins)
|
|
- [Extism CLI](https://extism.org/docs/install) (optional, for testing)
|
|
|
|
### Build all plugins
|
|
|
|
```bash
|
|
make all
|
|
```
|
|
|
|
This will compile all (Go) example plugins and place the `.wasm` files in this directory.
|
|
|
|
### Build a specific plugin
|
|
|
|
```bash
|
|
make minimal.wasm
|
|
make wikimedia.wasm
|
|
```
|
|
|
|
### Clean build artifacts
|
|
|
|
```bash
|
|
make clean
|
|
```
|
|
|
|
## Available Examples
|
|
|
|
| Plugin | Language | Description |
|
|
|-------------------------------------------------|----------|-------------------------------------------------------------------------|
|
|
| [minimal](minimal/) | Go | A minimal example showing the basic plugin structure |
|
|
| [wikimedia](wikimedia/) | Go | Fetches artist metadata from Wikidata, DBpedia, and Wikipedia |
|
|
| [crypto-ticker](crypto-ticker/) | Go | Real-time cryptocurrency prices from Coinbase using WebSocket |
|
|
| [discord-rich-presence](discord-rich-presence/) | Go | Discord Rich Presence integration using Scrobbler, WebSocket, Scheduler |
|
|
| [coverartarchive-py](coverartarchive-py/) | Python | Album cover art from Cover Art Archive (Python example) |
|
|
| [nowplaying-py](nowplaying-py/) | Python | Logs currently playing tracks using Scheduler and SubsonicAPI |
|
|
|
|
## Testing with Extism CLI
|
|
|
|
You can test any plugin using the Extism CLI:
|
|
|
|
```bash
|
|
# Test the manifest
|
|
extism call minimal.wasm nd_manifest --wasi
|
|
|
|
# Test with input
|
|
extism call minimal.wasm nd_get_artist_biography --wasi \
|
|
--input '{"id":"1","name":"The Beatles"}'
|
|
```
|
|
|
|
For plugins that make HTTP requests, use `--allow-host` to permit access:
|
|
|
|
```bash
|
|
extism call wikimedia.wasm nd_get_artist_biography --wasi \ 3s ▼
|
|
--input '{"id":"1","name":"Yussef Dayes"}' \
|
|
--allow-host "query.wikidata.org" --allow-host "en.wikipedia.org"
|
|
```
|
|
|
|
## Installation
|
|
|
|
Copy any `.wasm` file to your Navidrome plugins folder:
|
|
|
|
```bash
|
|
cp wikimedia.wasm /path/to/navidrome/plugins/
|
|
```
|
|
|
|
Then enable plugins in your `navidrome.toml`:
|
|
|
|
```toml
|
|
[Plugins]
|
|
Enabled = true
|
|
Folder = "/path/to/navidrome/plugins"
|
|
```
|
|
|
|
And add the plugin to your agents list:
|
|
|
|
```toml
|
|
Agents = "lastfm,spotify,wikimedia"
|
|
```
|
|
|
|
## Creating Your Own Plugin
|
|
|
|
The plugin system supports multiple languages. See the [minimal](minimal/) example for the simplest Go starting point,
|
|
[discord-rich-presence](discord-rich-presence/) for a more complete Go example with HTTP requests, or [coverartarchive-py](coverartarchive-py/)
|
|
for a Python example.
|
|
|
|
### Bootstrapping a New Plugin
|
|
Use the XTP CLI to bootstrap a new plugin from a schema:
|
|
|
|
```bash
|
|
xtp plugin init \
|
|
--schema-file plugins/schemas/metadata_agent.yaml \
|
|
--template go \
|
|
--path ./my-plugin \
|
|
--name my-plugin
|
|
```
|
|
|
|
See the [schemas README](../schemas/README.md) for more information about available schemas
|
|
and supported languages.
|
|
|
|
For the simplest starting point, look at [minimal](minimal/). For a more complete example
|
|
with HTTP requests, see [wikimedia](wikimedia/).
|
|
|
|
|
|
For full documentation, see the [Plugin System README](../README.md).
|