remote/navidrome
1
0
Fork 0
mirror of https://github.com/navidrome/navidrome.git synced 2026-10-08 10:27:08 +02:00
Code Issues Projects Releases Packages Wiki Activity
navidrome/plugins/examples/coverartarchive-py
History
Exact
Deluan Quintão 1072e9f7eb
 chore(plugins): document requiredHosts rules and deprecate pdk.NewHTTPRequest (#6129) 
* fix(plugins): align the Python HTTP example with the repo's host-call pattern

Bind http_send with raw memory offsets like nowplaying-py does, drop
guards for fields the host always sends, and document how plugins
without a PDK call host services and which built-in HTTP APIs are
disabled.

* docs(plugins): document the private-address rules for HTTP requiredHosts

Explain in the README and manifest schema that named hosts can't reach
private addresses while IP/CIDR entries and a bare "*" can.

* docs(plugins): document the private-address rules for requiredHosts

Explain in the README and manifest schema that named hosts can't reach
private addresses while IP/CIDR entries and a bare "*" can, for both
HTTP and WebSocket. Inline the single-use HTTP isHostAllowed wrapper.

* feat(plugins): derive Default for Rust host service structs

The ndpgen client.rs template now adds Default to the derive list of host
service structs, as the capability and shared types templates already do.
Plugin authors can now set only the fields they need, for example
HTTPRequest { method, url, ..Default::default() }. The webhook-rs and
discord-rich-presence-rs examples use this form now. The golden files and
the generated nd-pdk-host crate are updated to match.

* feat(plugins): deprecate pdk.NewHTTPRequest in the Go PDK

Navidrome no longer enables extism's http_request host function, so a
request built with pdk.NewHTTPRequest always fails. ndpgen now reads a small
deprecation table and writes a Deprecated: paragraph for the listed extism
functions, in both the WASM wrapper and the native stub. Linters and IDEs
now point plugin authors to host.HTTPSend. The PDK example tests used to
teach NewHTTPRequest. They now use host.HTTPSend and host.HTTPMock.

* docs(plugins): correct requiredHosts rules for websocket and private addresses

Two statements in the plugin docs did not match the code.

The WebSocket section claimed requiredHosts behaves like HTTP. It does not:
host_httpclient.go only consults the allowlist when the list is non-empty and
otherwise falls back to allowing public addresses, while host_websocket.go
always calls isHostInAllowlist, so an absent list blocks every connection.

The HTTP section claimed a named host can never reach a private address.
checkPrivateDial scans the whole requiredHosts list, so a named host does
reach a private address when the same list also holds a covering IP or CIDR.

Reworded both, plus the matching requiredHosts descriptions in
manifest-schema.json, and regenerated manifest_gen.go.
2026-09-12 13:59:46 -04:00
..
plugin chore(plugins): document requiredHosts rules and deprecate pdk.NewHTTPRequest (#6129) 2026-09-12 13:59:46 -04:00
Makefile Merge commit from fork 2026-09-12 13:38:08 -04:00
manifest.json feat(plugins): New Plugin System with multi-language PDK support (#4833) 2026-01-14 19:22:48 -05:00
README.md Merge commit from fork 2026-09-12 13:38:08 -04:00

README.md

Cover Art Archive Plugin (Python)

A Python example plugin that fetches album cover images from the Cover Art Archive API using the MusicBrainz Release MBID.

Features

  • Implements the nd_get_album_images method of the MetadataAgent plugin interface
  • Returns front cover images for a given release MBID
  • Returns not found if no MBID is provided or no images are found
  • Demonstrates Python plugin development for Navidrome

Prerequisites

  • extism-py - Python PDK compiler 
    curl -Ls https://raw.githubusercontent.com/extism/python-pdk/main/install.sh | bash

Note: extism-py requires Binaryen (wasm-merge, wasm-opt) to be installed.

Building

From the plugins/examples directory:

make coverartarchive-py.ndp

Or directly:

extism-py plugin/__init__.py -o plugin.wasm
zip -j coverartarchive-py.ndp manifest.json plugin.wasm

Installation

  1. Copy coverartarchive-py.ndp to your Navidrome plugins folder

  2. Enable plugins in navidrome.toml:

    [Plugins]
Enabled = true
Folder = "/path/to/plugins"

  3. Add to your agents list:

    Agents = "coverartarchive-py,spotify,lastfm"

Testing

The plugin makes HTTP requests through Navidrome's http_send host function, so it only runs inside Navidrome (the extism CLI can't provide that function). Install the .ndp as described above, then open an album that has a MusicBrainz ID and check the Navidrome logs.

How It Works

  1. Album Image Request (nd_get_album_images): Receives album metadata including the MusicBrainz Release MBID.

  2. API Query: Fetches cover art metadata from https://coverartarchive.org/release/{mbid}.

  3. Response: Returns the front cover image URL if found.

API Reference