AudioMuse-AI Navidrome plugin: sonic similarity inside a self-hosted music server

Three features, and the fact that the engine is elsewhere

AudioMuse-AI-NV-Plugin is a Navidrome plugin that integrates core AudioMuse-AI features into the Navidrome frontend, and the list of integrated functionality is short: Instant Mix for song similarity, Radio for artist similarity, and Artist Info, which returns similar artists.

The important structural fact is in the family of repositories. This plugin is one of five related projects. AudioMuse-AI itself is the core application, and it runs Flask and Worker containers to actually run all the features. There is a Helm chart for it for Kubernetes installs. There is a separate plugin for Jellyfin. This repository is the Navidrome plugin. And AudioMuse-AI-MusicServer is an Open Subsonic-like music server with integrated sonic functionality.

So the analysis engine is not in this repository. The plugin's job is to intercept the relevant Navidrome requests and forward them to the AudioMuse-AI core, then hand the answer back to the frontend.

That split explains a number of things you will meet while setting it up. The plugin has to be told where the AudioMuse-AI API lives, because it is making HTTP calls to another service. If that service has authentication enabled, you have to create an API Token on the AudioMuse-AI core container and put it in the plugin configuration, and a 401 Unauthorized error in the Navidrome logs typically means that token is missing or wrong. And Navidrome must be able to reach the core container, so the host or IP in the plugin configuration has to be correct.

The primary language is Go, the licence is AGPL-3.0, the default branch is main, the last push was on 2026-09-19, and the recent releases are v10 from 2026-08-31, v9 from 2026-07-17 and v8 from 2026-04-27. The topic list includes onnx, llm, docker, kubernetes, k3s, mediaserver, smart-playlists, playlist and sonic-analysis, and the repository has no homepage of its own.

The three engines you can pick between in v10

The NEWS section records the change that came with v10, and it is the most substantive piece of configuration in the project.

From v10, different AudioMuse-AI functionality can be selected for the Instant Mix, chosen in the plugin configuration. The three options are named and mapped to their endpoints.

Similar Song is the default and is the historical behaviour, using GET /api/similar_tracks. Lyrics by Song uses POST /api/sem_grove/search, and it needs the SemGrove index, which is a lyrics plus audio analysis index, built in AudioMuse-AI. Hyperbolic Similarity uses POST /api/hyperbolic/similar in its standard mode, and it needs the hyperbolic projection built in AudioMuse-AI.

The requirements are the point. Two of the three engines are not free: they depend on an index or a projection existing in the AudioMuse-AI core, which means a build step on the other service before the plugin can use it. The default engine, the plain similar-tracks lookup, is the one that works against an unmodified core.

There is also a caveat about two settings that apply only to Similar Song. Eliminate Duplicates and Use Radius Similarity apply only to that engine, because the other two engines use the AudioMuse-AI default.

That kind of asymmetry is worth planning for. If you set a radius and then switch engine, the setting silently stops having any effect, and the only symptom is that results change. The readme does not warn you about it beyond stating which engine the options belong to.

The earlier milestone is also relevant to anyone on an older Navidrome. From v8, the Sonic Similarity API extension is supported on top of the previous one, with the API documented at the OpenSubsonic site and supported by a Navidrome pull request. And InstantMix support in Navidrome itself starts from v0.60.0, so the plugin is building on a feature the server only gained recently.

Installing the plugin, and the environment variables that matter

The readme is emphatic about one thing before the steps: before starting, have the last version of Navidrome, AudioMuse-AI-NV-plugin and the AudioMuse-AI core containers. If the versions are not aligned, some error could happen, and the same applies to future updates.

That is a real constraint and it means three version numbers to track rather than one.

The first piece is the Navidrome configuration. The environment variables ND_PLUGINS_ENABLED, ND_PLUGINS_AUTORELOAD and ND_AGENTS are the important ones, and with docker compose the readme gives this shape.

version: '3'
services:
  navidrome:
    image: deluan/navidrome:latest
    ports:
      - '4533:4533'
    environment:
      - ND_PLUGINS_ENABLED=true
      - ND_PLUGINS_AUTORELOAD=true
      - ND_AGENTS=audiomuseai,lastfm,deezer
      - ND_DEVARTISTINFOTIMETOLIVE=1s
    volumes:
      - ./data:/data
      - /path/to/music:/music:ro

ND_AGENTS is worth reading twice. It lists the metadata agents Navidrome will use, and the readme states that the order of ND_AGENTS is important because Navidrome will use the first listed agent supporting sonic similarity. Putting audiomuseai first is what makes this plugin the source of similarity data rather than the fallback.

ND_DEVARTISTINFOTIMETOLIVE=1s controls how long the artist info time to live is set to, which is what keeps similar-artist data fresh.

The second piece is the plugin file itself. You put audiomuseai.ndp in the Navidrome data plugins folder, default /data/plugins, and the file is attached to the release on the releases page rather than built from source. Then you restart Navidrome, go to UI, Plugins, enable AudioMuse-AI, and set the AudioMuse-AI API URL and the other configuration parameters.

One more case to handle: if AudioMuse-AI has multiple music servers configured, you need to configure the Server Name in the plugin to match the one in AudioMuse-AI.

The badge in the readme pins the media server support at Navidrome 0.64.0, which tells you which server version this plugin release is built against.

Testing it, and reading the logs when it fails

The readme gives a two-part test that is worth following exactly, because the failure modes are otherwise hard to localise.

First, in the AudioMuse-AI integrated UI, use the Similar Song functionality on a track. Second, in the Navidrome web UI, use InstantMix on the same track.

Both actions should generate similar requests in the AudioMuse-AI Flask logs. For the Navidrome request, you should also see plugin=audiomuseai on multiple lines of the Navidrome logs with no related errors. If both tests pass, supported third-party clients should work correctly, and any issue on a third-party client must be addressed on their side.

That last sentence sets a boundary that will save you time. The plugin is a server-side component, so if the web UI works and a mobile app does not, the problem is in the app's implementation of the API, not in the plugin.

The mobile app angle is the other half of this project. For a mobile app to use the functionality, it needs to implement the getSimilarSongs2 / getSimilarSongs and getArtistInfo API. The readme lists the front ends it has been tested against: the Navidrome integrated web frontend, Substreamer as an open-source iOS and Android frontend, Tempus as an open-source Android frontend, Symfonium as a closed-source Android frontend, Feishin as an open-source web frontend and Wavio as an open-source Android frontend. Other frontends could also work by using those APIs even.

Symfonium has an extra configuration step, enabling Use similar tracks for Radio Mix in its settings, and its further AudioMuse-AI features are implemented only using Jellyfin.

Two troubleshooting notes are worth keeping. Different frontends may return a different number of similar songs depending on their configuration, because the plugin does not enforce a default limit. And if requests do not appear at all in the AudioMuse-AI Flask logs, the issue is most likely network connectivity or container routing rather than anything in the plugin.

How the plugin is built, and the WebAssembly constraint

The repository layout is small and tells you the whole structure: a main.go, an audiomuse_api.go, a sonicsimilarity/ directory, a manifest.json, a go.mod and a Makefile, plus the usual LICENSE, README and CONTRIBUTING files.

The Makefile is the part that explains the packaging.

PLUGIN_NAME := audiomuseai
PACKAGE_NAME := audiomuseai

.PHONY: build package clean

build:
	tinygo build -o $(PLUGIN_NAME).wasm -target=wasip1 -scheduler=none -buildmode=c-shared .

package: build
	# Navidrome expects the wasm file in the package to be named `plugin.wasm`
	cp $(PLUGIN_NAME).wasm plugin.wasm
	zip -j $(PACKAGE_NAME).ndp manifest.json plugin.wasm

The build is TinyGo rather than standard Go, targeting wasip1 with the scheduler disabled and the c-shared build mode, which is how a Go program becomes a WebAssembly module that Navidrome can load. The package step then copies the output to plugin.wasm, because Navidrome expects that specific filename, and zips it with the manifest into an .ndp archive.

That last detail explains the .ndp file the installation instructions ask you to copy into /data/plugins. The .ndp is a zip containing manifest.json and plugin.wasm, and Navidrome's plugin system loads the WebAssembly module from it. The build rules clean up the temporary wasm output afterwards, and there is a clean target removing both the wasm file and the package.

The Go module shows the dependency is the Navidrome plugin development kit, github.com/navidrome/navidrome/plugins/pdk/go, pinned to a specific commit, with the Extism PDK and the usual test libraries as indirect dependencies. Go 1.25 is the language version.

The consequence of the WebAssembly approach is a real constraint on what the plugin can do. It is a sandboxed module loaded by Navidrome, not a native process, and it runs on the wasip1 target with no scheduler. Anything it needs from the host, including talking to the AudioMuse-AI core over HTTP, has to go through what the sandbox allows. That is also why the plugin cannot reach into your music library itself and must ask the core service for everything.

Editorial conclusion

AudioMuse-AI Navidrome plugin fits a self-hosted Navidrome operator who wants sonic discovery and can run the separate AudioMuse-AI core service, and it does not fit someone who wants the feature inside Navidrome alone, because the analysis engine lives in another container with its own indexes. Before deploying, check that your Navidrome, plugin and AudioMuse-AI versions are aligned, since the readme warns that mismatched versions can cause errors, and confirm the container network path between them, since missing requests in the AudioMuse-AI logs almost always mean connectivity rather than a plugin fault.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. NeptuneHub/AudioMuse-AI-NV-plugin on GitHub
4. README
5. Releases