Skip to content

🎧 Your Personal Streaming Service

1.9 KB
Raw Blame

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