Documentation

• 1: Navidrome Overview
• 2: Installation
• 2.1: Windows Install
• 2.2: Installing with Docker
• 2.3: Linux Install
• 2.4: Installing with Podman
• 2.5: macOS Install
• 2.6: FreeBSD Install
• 2.7: Community Maintained Packages
• 2.8: Managed Hosting
• 2.9: Build from sources
• 3: Getting Started
• 3.1: Externalized Authentication Quick Start
• 4: Usage
• 4.1: Configuration
• 4.1.1: Navidrome Configuration Options
• 4.1.2: Using custom tags with Navidrome
• 4.1.3: Customizing Persistent IDs in Navidrome
• 4.2: Features
• 4.2.1: How to Use Smart Playlists in Navidrome (Beta)
• 4.2.2: Multi-Library Support
• 4.2.3: Jukebox mode
• 4.2.4: Sharing
• 4.2.5: Scrobbling
• 4.2.6: Plugins
• 4.2.7: Jellyfin API (Experimental)
• 4.3: Library Management
• 4.3.1: Tagging Guidelines
• 4.3.2: Artwork location resolution
• 4.3.3: Missing Files
• 4.3.4: Exclude Content From Library
• 4.4: Integration
• 4.4.1: External Integrations (A.K.A. Agents)
• 4.4.2: AudioMuse-AI
• 4.4.3: Externalized Authentication
• 4.4.4: Monitoring Navidrome
• 4.5: Administration
• 4.5.1: Automated Backup
• 4.5.2: Command-Line Interface (CLI)
• 4.5.2.1: navidrome artwork
• 4.5.2.2: navidrome backup
• 4.5.2.3: navidrome doctor
• 4.5.2.4: navidrome inspect
• 4.5.2.5: navidrome missing
• 4.5.2.6: navidrome plugin
• 4.5.2.7: navidrome pls
• 4.5.2.8: navidrome scan
• 4.5.2.9: navidrome search
• 4.5.2.10: navidrome service
• 4.5.2.11: navidrome user
• 4.5.3: Security Considerations
• 4.5.4: Anonymous Data Collection
• 5: Developers
• 5.1: Development Environment
• 5.2: Creating New Themes
• 5.3: Translations
• 5.4: Adding Client Apps to the Catalog
• 5.5: Navidrome API v1
• 5.6: Subsonic API Compatibility
• 6: Google Summer of Code 2021
• 7: FAQ

1 - Navidrome Overview

Navidrome can be used as a standalone server, that allows you to browse and listen to your music collection using a web browser.

It can also work as a lightweight Subsonic-API compatible server, that can be used with any Subsonic compatible client.

Features

• Very low resource usage. Runs well even on simple Raspberry Pi Zero and old hardware setups
• Handles very large music collections
• Streams virtually any audio format available
• Reads and uses all your beautifully curated metadata
• Great support for compilations (Various Artists albums) and box sets (multi-disc albums)
• Multi-user, each user has their own play counts, playlists, favorites, etc..
• Multi-library support with user-specific access controls to separate different music collections
• Multi-platform, runs on macOS, Linux and Windows. Docker images are also provided
• Ready to use, official, Raspberry Pi binaries and Docker images available
• Automatically monitors your library for changes, importing new files and reloading new metadata
• Themeable, modern and responsive Web interface based on Material UI and React-Admin
• Compatible with all Subsonic/Madsonic/Airsonic clients. See below for a list of tested clients
• Transcoding on the fly. Can be set per user/player. Opus encoding is supported
• Translated to 34 languages (and counting)
• Full support for playlists, with option to auto-import .m3u files and to keep them in sync
• Smart/dynamic playlists (similar to iTunes). More info here
• Scrobbling to Last.fm, ListenBrainz and Maloja (via custom ListenBrainz URL)
• Sharing public links to albums/songs/playlists
• Externalized authentication to use your own authentication service instead of Navidrome’s built-in one
• Jukebox mode allows playing music on an audio device attached to the server, and control from a client

Features supported by the Subsonic API

• Tag-based browsing/searching
• Simulated browsing by folders (see note below)
• Playlists
• Bookmarks (for Audiobooks)
• Starred (favourites) Artists/Albums/Tracks
• 5-Star Rating for Artists/Albums/Tracks
• Transcoding and Downsampling
• Get/Save Play Queue (to continue listening in a different device)
• Last.fm and ListenBrainz scrobbling
• Artist Bio from Last.fm
• Artist Images from Last.fm, Spotify and Deezer
• Album images and description from Last.fm
• Lyrics (from embedded tags and external files)
• Internet Radios
• Jukebox mode
• Shares

Apps

Navidrome features a modern, responsive Web UI built with Material UI and React. Beyond the built-in web interface, Navidrome is compatible with a wide ecosystem of Subsonic and OpenSubsonic clients across all major platforms, including mobile apps for iOS and Android, desktop applications for Windows, macOS, and Linux, as well as specialized clients for Android TV, CarPlay, and Android Auto.

Whether you prefer streaming on the go, listening to your library from your desktop, or casting to your home entertainment system, there’s a client app tailored to your needs. Browse our comprehensive client apps directory to find the perfect player for your setup!

Road map

This project is in active development. Expect a more polished experience and new features/releases on a frequent basis. Some upcoming features planned:

• New UI, including a Smart playlists editor
• Plugins

2 - Installation

Download

Visit our releases page in GitHub and download the latest version for your platform. There are builds available for Linux (Intel and ARM, 32 and 64 bits), Windows (Intel 32 and 64 bits) and macOS (Intel 64 bits).

For ARM-Based systems (ex: Raspberry Pi), check which ARM build is the correct one for your platform using cat /proc/cpuinfo.

Remember to install ffmpeg in your system, a requirement for Navidrome to work properly. If your OS does not provide a package for ffmpeg, you may find the latest static build for your platform here: https://johnvansickle.com/ffmpeg/.

Setup

After downloading the Navidrome binary, follow the appropriate setup instructions for your platform:

2.1 - Windows Install

MSI Install

Download and install the latest Navidrome MSI for the correct version of Windows (most likely AMD64). The installer will prompt for basic configuration options (port, directories etc). These can be left as default or customised to your setup. The service will be installed and started automatically, once the installer has completed you can go to [http://127.0.0.1:4533] (or whichever port you chose) in a browser and setup the first user. The navidrome.ini configuration file will be located in the installation folder (default: C:\Program Files\Navidrome).

Further modification can be made by changing the navidrome.ini file after installation and restarting the service.

Manual Installation

Since Navidrome needs to be run from the command line, it is suggested to use a service wrapper to make it into a service as it does not make sense to have a terminal window open whenever you want to use Navidrome. The examples below are for Shawl, NSSM and WinSW.

Using Shawl

Prebuilt binaries are available on the releases page of Shawl. It’s portable, so you can simply download it and put it anywhere without going through an installer. Otherwise if you have Rust installed, you can run cargo install shawl.

Here’s how you create the service with Shawl, then start it. Note that this has to be run from an administrator command prompt.

shawl add --name Navidrome -- "C:\Services\navidrome\navidrome.exe" -c "C:\Services\navidrome\navidrome.toml"
sc start Navidrome

Using NSSM

No installation is required for NSSM. Just grab the latest release from their download page and install the Navidrome service from an administrator command prompt using NSSM:

nssm install Navidrome

This opens a window where you can set the properties of the service; most notably, the path to the executable, the user account on which to run the service, the output files (stout and sterr) and file rotation. More information about the configurable options can be found here.

You can also bypass the GUI and install the service from the command line only. Below is an example:

nssm install Navidrome "C:\Services\navidrome\navidrome.exe"
nssm set Navidrome AppDirectory "C:\Services\navidrome\"
nssm set Navidrome DisplayName Navidrome
# The username and password of the user account under which the service will run.
nssm set Navidrome ObjectName "username" "password"
nssm set Navidrome AppStdout "C:\Services\navidrome\navidrome.log"
nssm set Navidrome AppStderr "C:\Services\navidrome\navidrome.log"
nssm set Navidrome AppRotateFiles 1
nssm set Navidrome AppRotateSeconds 86400
nssm set Navidrome AppRotateBytes 10240

# Start the service
sc start Navidrome

Using WinSW

To use WinSW, download the WinSW binary from their download page. WinSW also requires a configuration file (more details about the WinSW configuration file here) to be able to manage an application.

A basic example (where both Navidrome and the WinSW configuration file are in the same directory) for Navidrome is down below:

<service>
  <id>Navidrome</id>
  <name>Navidrome</name>
  <description>Modern Music Server and Streamer compatible with Subsonic/Airsonic</description>
  <executable>C:\Services\navidrome\navidrome.exe</executable>
  <arguments>-c navidrome.toml</arguments>
  <log mode="roll-by-size"></log>
</service>

Save this in a file named navidrome.xml. Then, run these commands from an administrator command prompt to install the service, start it and check its status:

winsw install navidrome.xml
winsw start navidrome.xml
winsw status navidrome.xml

Verify that the service has started as expected by navigating to http://localhost:4533, by checking the Services Management Console or by checking the log file that the service wrapper created.

2.2 - Installing with Docker

Docker images are available for the linux/amd64, linux/arm/v6, linux/arm/v7 and linux/arm64 platforms. They include everything needed to run Navidrome.

Using docker-compose :

Create a docker-compose.yml file with the following content (or add the navidrome service below to your existing file):

services:
  navidrome:
    image: deluan/navidrome:latest
    user: 1000:1000 # must own the data folder and be able to read music folder(s). See Permissions below
    ports:
      - "4533:4533"
    restart: unless-stopped
    environment:
      # Optional: put your config options customization here. Examples:
      # ND_LOGLEVEL: debug
    volumes:
      - "/path/to/data:/data"
      - "/path/to/your/music/folder:/music:ro"

Start it with docker-compose up -d. Note that the environment variables above are just an example and are not required. The values in the example are already the defaults

Using docker command line tool:

$ docker run -d \
   --name navidrome \
   --restart=unless-stopped \
   --user $(id -u):$(id -g) \
   -v /path/to/music:/music \
   -v /path/to/data:/data \
   -p 4533:4533 \
   -e ND_LOGLEVEL=info \
   deluan/navidrome:latest

Permissions

The configurations above are examples. The IDs in them will not always match your machine, so adjust them before you start the container.

Navidrome needs:

• read and write access to /data, where it creates its database and cache
• read access to /music

Both must be granted to the UID:GID you put in the user directive. Run id -u and id -g to see the IDs of your own account, and ls -n /path/to/your/music/folder to see which IDs own your music. Whatever numbers you pick, use the same ones in the user directive and in the commands below.

The two folders fail in different ways, so the logs tell you which one is wrong.

The data folder is not writable

Navidrome cannot create its database, and the container stops at startup:

level=error msg="Error applying PRAGMA optimize" error="unable to open database file: no such file or directory"
panic: runtime error: invalid memory address or nil pointer dereference

Create the data folder and give it to the same user you run the container as:

mkdir -p /path/to/data
sudo chown -R $(id -u):$(id -g) /path/to/data

The music folder is not readable

Navidrome starts and the web interface works, but your library stays empty. The logs show:

level=error msg="Error starting watcher" error="open /music: permission denied" lib=/music/...
level=warning msg="Scanner: Target folder does not exist." error="open .: permission denied" path=.

The folder does exist, despite what the second message says. The container user just cannot open it. Give that user read and execute access, either by changing the owner:

sudo chown -R $(id -u):$(id -g) /path/to/your/music/folder

or, if other programs also use the folder, by opening it for reading:

sudo chmod -R a+rX /path/to/your/music/folder

Two things people often try that do not work:

• PUID and PGID have no effect. Those variables are a linuxserver.io convention. Navidrome’s image ignores them. Use the user directive instead.
• Removing the user directive is not a fix. The container then runs as root, which can write anywhere, so the error goes away. Do not do this in production. Fix the folder ownership instead.

Customization

• The user argument should reflect the UID:GID that owns the data folder and can read the music library. See Permissions above.
• Remember to change the volumes paths to point to your local paths. /data is where Navidrome will store its DB and cache, /music is where your music files are stored. For multi-library setups, you may need to mount additional volumes for each library.
• Configuration options can be customized with environment variables as needed. For docker-compose just add them to the environment section or the yml file. For docker cli use the -e parameter. Ex: -e ND_SESSIONTIMEOUT=24h.
• If you want to use a configuration file with Navidrome running in Docker, you can create a navidrome.toml config file in the /data folder and set the option ND_CONFIGFILE=/data/navidrome.toml.
• If you use the Jellyfin API and want clients to find the server on your network, you must use host networking. See Docker setup for auto-discovery.

2.3 - Linux Install

Install Navidrome Using Pre-built Binary

To install Navidrome on a Linux system using a .deb file, you can follow a streamlined process that leverages the convenience of Debian package management. This method simplifies the installation by eliminating the need to manually download and extract binaries.

Before you begin, ensure that your system is up to date and that you have ffmpeg installed, as it is a requirement for Navidrome to function properly.

sudo apt update
sudo apt upgrade

Download the .deb File

1. Visit the Navidrome Releases Page: Go to the Navidrome releases page on GitHub to find the latest .deb package suitable for your system architecture (e.g., amd64 for 64-bit systems).

2. Download the .deb File: Use wget or your browser to download the .deb file. Replace navidrome_0.XX.X_linux_amd64.deb with the actual file name from the releases page.

wget https://github.com/navidrome/navidrome/releases/download/v0.XX.X/navidrome_0.XX.X_linux_amd64.deb

Install and Configure

There are two ways to install the package, apt and dpkg. apt is the usual method because it will automatically determine dependencies and install them (ffmpeg).

Using apt:

sudo apt install ./navidrome_0.XX.X_linux_amd64.deb

Using dpkg:

Install the package and then resolve the dependencies:

sudo dpkg -i ./navidrome_0.XX.X_amd64.deb
sudo apt install -f

Configuration File: After installation, Navidrome MUST be configured to run. The default path for the configuration file is /etc/navidrome/navidrome.toml. Create and edit the file using nano directly.

sudo nano /etc/navidrome/navidrome.toml

Add/update the following line to specify your music library path:

MusicFolder = "/path/to/your/music/library"

If the MusicFolder is not set, that the default music path is /opt/navidrome/music and it will be running as user navidrome.

Note: This becomes your default library. You can add additional libraries through the web interface after installation. See the Multi-Library documentation for more details.

For additional configuration options see the configuration options page.

Start the Navidrome Service: Use systemctl to start the Navidrome service and set it to run on startup.

sudo systemctl enable --now navidrome

Check Service Status: Verify that Navidrome is running correctly.

sudo systemctl status navidrome
sudo journalctl -u navidrome -f

If everything is set up correctly, Navidrome will be accessible via web browser: http://localhost:4533.

Migrate from manual installation to .deb Pre-built package

Migrating from a manually installed Navidrome instance to the new pre-built .deb package version can streamline updates and maintenance. This guide will walk you through the process of migrating your existing Navidrome setup on Linux to the .deb package version, specifically from the 0.54.1 release.

Before starting the migration, ensure you have:

• Backup: Always back up your current Navidrome configuration and music library. This includes the navidrome.toml configuration file and any other custom settings you may have.
• System Update: Make sure your system is up to date.

sudo apt update
sudo apt upgrade

Remove Existing Program

First, stop the currently running Navidrome service to prevent any conflicts during the installation of the new package.

sudo systemctl stop navidrome.service

Navigate to the directory where your self-built Navidrome is located and remove the files. Be cautious not to delete your configuration or music library.

sudo rm -rf /opt/navidrome

Installation

The machine is now clean and ready for installation. Follow the regular Linux installation instructions above. Just be sure to place the config file and database in appropriate locations (/etc/navidrome/navidrome.toml).

Additional Considerations

• Permissions: Ensure that the user navidrome which is used by the program has the necessary permissions to access your music library.
• Environment Variables: If you had any custom environment variables set in your previous setup, make sure to configure them in the new setup as well.

Manual installation on Linux

Navidrome can also be installed using a self-built binary. In order to do so, first ensure your system is up to date and install ffmpeg.

sudo apt update
sudo apt upgrade
sudo apt install vim ffmpeg

Create Directory Structure

Create a directory to store the Navidrome executable and a working directory with the proper permissions.

sudo install -d -o <user> -g <group> /opt/navidrome
sudo install -d -o <user> -g <group> /var/lib/navidrome

Get Navidrome

Download the latest release from the releases page, extract the contents to the executable directory, and set the permissions for the files. (Replace the URL below with the one from the releases page):

wget https://github.com/navidrome/navidrome/releases/download/v0.XX.X/navidrome_0.XX.X_linux_amd64.tar.gz -O Navidrome.tar.gz
sudo tar -xvzf Navidrome.tar.gz -C /opt/navidrome/
sudo chmod +x /opt/navidrome/navidrome
sudo chown -R <user>:<group> /opt/navidrome

Create Configuration File

In the directory /etc/navidrome create a new file named navidrome.toml with the following settings.

MusicFolder = "<library_path>"

For additional configuration options see the configuration options page.

Create a systemd Unit

Create a new file under /etc/systemd/system/ named navidrome.service with the following data. Make sure you replace <user> and <group> with the user and group you want to run Navidrome under. If you use the backup feature, you will also need to add the backup path to the systemd allow-list for Navidrome as shown in the Backup usage documentation.

[Unit]
Description=Navidrome Music Server and Streamer compatible with Subsonic/Airsonic
After=remote-fs.target network.target
AssertPathExists=/var/lib/navidrome

[Install]
WantedBy=multi-user.target

[Service]
User=<user>
Group=<group>
Type=simple
ExecStart=/opt/navidrome/navidrome --configfile "/etc/navidrome/navidrome.toml"
WorkingDirectory=/var/lib/navidrome
TimeoutStopSec=20
KillMode=process
Restart=on-failure

# See https://www.freedesktop.org/software/systemd/man/systemd.exec.html
DevicePolicy=closed
NoNewPrivileges=yes
PrivateTmp=yes
PrivateUsers=yes
ProtectControlGroups=yes
ProtectKernelModules=yes
ProtectKernelTunables=yes
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
RestrictNamespaces=yes
RestrictRealtime=yes
SystemCallFilter=~@clock @debug @module @mount @obsolete @reboot @setuid @swap
ReadWritePaths=/var/lib/navidrome

# You can uncomment the following line if you're not using the jukebox This
# will prevent navidrome from accessing any real (physical) devices
#PrivateDevices=yes

# You can change the following line to `strict` instead of `full` if you don't
# want navidrome to be able to write anything on your filesystem outside of
# /var/lib/navidrome.
ProtectSystem=full

# You can uncomment the following line if you don't have any media in /home/*.
# This will prevent navidrome from ever reading/writing anything there.
#ProtectHome=true

# You can customize some Navidrome config options by setting environment variables here. Ex:
#Environment=ND_BASEURL="/navidrome"

Start the Navidrome Service

Reload the service daemon, start the newly create service, and verify it has started correctly.

sudo systemctl daemon-reload
sudo systemctl start navidrome.service
sudo systemctl status navidrome.service

If the service has started correctly verify you can access http://localhost:4533.

Start Navidrome on Startup

sudo systemctl enable navidrome.service

2.4 - Installing with Podman

Container images are available for the linux/amd64, linux/arm/v7 and linux/arm64 platforms. They include everything needed to run Navidrome.

Using Podman Quadlet :

Podman is created to run as both rootful (root user), and rootless (non-root user) modes. Quadlet is a generator tool embeded directly into Podman that translate your *.container files into systemd service. So you can enable/disable it to auto load at each session, like normal systemd service.

Put navidrome.container in /etc/containers/systemd/ for root user, OR $HOME/.config/containers/systemd/ for running as normal non-root user. Create a navidrome.container file with the following content:

[Unit]
Description=Quadlet-Navidrome

[Container]
Environment=ND_DEFAULTDOWNSAMPLINGFORMAT=opus ND_AGENTS=lastfm
Image=deluan/navidrome:latest
Pull=always
UserNS=keep-id
PublishPort=4533:4533 #1st number is published port, can be change or set yourself
Volume=/path/to/data:/data:z
Volume=/path/to/your/music/folder:/music:ro,z

[Service]
Restart=on-failure
TimeoutStartSec=30

Quadlets strictly require systemd to run. After creating navidrome.container, starting container as normal systemd service Root user: # systemctl start navidrome.container --now

Non-root user: systemctl --user start navidrome --now

Checking if container could be loaded or not: podman ps . It should shown you in NAME systemd-navidrome

Using podman command line tool:

You can run this command once to check if container image could be loaded normally or not at 1st

$ podman run --rm -d \
        --name systemd-navidrome \
        --replace \
        --userns=keep-id \
        -p 4533:4533 \
        -v /path/to/data:/data:z \
        -v /path/to/your/music/folder:/music:ro,z \
        --env ND_DEFAULTDOWNSAMPLINGFORMAT=opus \
        --env ND_AGENTS=lastfm \
        deluan/navidrome:latest

Customization

• Environment var in Podman Quadlet can be set multiple vars in one line, separate by whitespace. But --env in podman must be set one by one.
• Remember to change the volumes paths to point to your local paths. /data is where Navidrome will store its DB and cache, /music is where your music files are stored. For multi-library setups, you may need to mount additional volumes for each library.
• Configuration options can be customized with environment variables as needed. For docker-compose just add them to the environment section or the yml file. For docker cli use the -e parameter. Ex: -e ND_SESSIONTIMEOUT=24h.
• If you want to use a configuration file with Navidrome running in Podman, you can create a navidrome.toml config file in the /data folder and set single option ND_CONFIGFILE=/data/navidrome.toml in environment var.

2.5 - macOS Install

You can start Navidrome by double-clicking the binary, or by running it in a terminal. However, it then stops when you close the terminal window, and it does not start again when the Mac restarts.

To run Navidrome in the background, install it as a service with the navidrome service command. The service starts when the Mac starts, even before anyone logs in, and macOS restarts it if it crashes.

Get Navidrome

Create a folder for Navidrome, and make your user its owner:

sudo mkdir -p /opt/navidrome
sudo chown "$(whoami):staff" /opt/navidrome

Download the latest release from the release page. Use darwin_arm64 for a Mac with Apple silicon, or darwin_amd64 for a Mac with an Intel processor. Then extract it. This command assumes that the file is in your Downloads folder. Replace the file name with the name of the file that you downloaded:

tar -xzf ~/Downloads/navidrome_0.64.2_darwin_arm64.tar.gz -C /opt/navidrome

"navidrome" is damaged and can't be opened. You should move it to the Bin.

xattr -d com.apple.quarantine /opt/navidrome/navidrome

Create the configuration file

Create the data folder. Navidrome keeps its database and its log files there, so make it private:

mkdir -m 700 /opt/navidrome/data

Create the file /opt/navidrome/navidrome.toml, and set at least these two options:

MusicFolder = "/Users/Shared/Music"
DataFolder = "/opt/navidrome/data"

See Access to protected folders before you choose the music folder. See the configuration options for all other options.

The configuration file can contain passwords and API keys, so make it private too:

chmod 600 /opt/navidrome/navidrome.toml

Install the service

Install the service and start it:

sudo /opt/navidrome/navidrome service install --user "$(whoami)" -c /opt/navidrome/navidrome.toml
sudo /opt/navidrome/navidrome service start

Then open http://localhost:4533 and create the first admin user.

The service is a system service. Its definition is in /Library/LaunchDaemons/navidrome.plist.

Manage the service

All the service commands need sudo:

Without sudo, service status shows Stopped, even when Navidrome runs.

To apply changes to the configuration file, stop the service and start it again. If you change DataFolder or LogFile, uninstall the service and install it again instead, because the log location is set when you install the service.

service uninstall removes only the service. Your configuration file, data folder and music stay.

Navidrome writes its log to /opt/navidrome/data/navidrome.err.log. The file navidrome.out.log next to it stays empty. To use a different file, create its folder, and set the LogFile option.

Update Navidrome

Stop the service, extract the new release over the old binary, and start the service again. Use the name and location of the file that you downloaded:

sudo /opt/navidrome/navidrome service stop
tar -xzf ~/Downloads/navidrome_0.64.2_darwin_arm64.tar.gz -C /opt/navidrome

# Only if you downloaded the file with a browser: remove the quarantine flag again
xattr -d com.apple.quarantine /opt/navidrome/navidrome

sudo /opt/navidrome/navidrome service start

If your music is in a protected folder, you must give access again after each update. See the next section.

Access to protected folders

Correct file permissions are not always sufficient. macOS has a second, independent privacy system. It blocks some folders even when the file permissions permit access. The service gets no permissions from your terminal, so this problem is common.

These are the most common blocked folders:

• ~/Desktop, ~/Documents and ~/Downloads
• ~/Music/Music, the Apple Music library folder
• External drives and network shares in /Volumes

These folders are not blocked:

• ~/Music itself, but not the Music subfolder in it
• /Users/Shared
• /opt

The simplest solution is to keep your music in a folder that macOS does not block, for example /Users/Shared/Music. Then you do not need any of the steps below.

Symptoms

When macOS blocks your music folder, Navidrome does not report a clear error. The first time Navidrome reads the folder, macOS shows a permission dialog, and the scan waits for your answer. The web UI still works, but the library stays empty. If nobody is logged in, for example after the Mac restarts, nobody can answer the dialog.

When access is refused, the log contains a line like this, which gives the wrong reason:

level=warning msg="Scanner: Target folder does not exist." error="open .: operation not permitted" path=.

The folder does exist. The permission is the real cause.

How to give access

Two methods are possible:

1. Answer the dialog. Click Allow when the dialog appears. macOS then adds an entry under System Settings > Privacy & Security > Files & Folders. You can switch it on and off there later.
2. Give Full Disk Access. Use this method if you did not see the dialog, or if you closed it:
   • Open System Settings > Privacy & Security > Full Disk Access.
   • Click +, then press Cmd+Shift+G and enter /opt/navidrome.
   • Select the navidrome binary and set the switch to on.
   • Stop the service and start it again.

2.6 - FreeBSD Install

The following steps have been tested on FreeBSD 12 and 13. They should work on all versions 11.4 and above as well as other supported versions. All prerequisites will be automatically installed when using a package or if building from ports. Throughout these instructions the commands will have placeholders for the user (<user>) and group (<group>) you want to run Navidrome under and the music folder path (<library_path>). If you are using an existing media library ensure the user has permissions to the media library.

Install Using Package

Use the package tool (pkg) to install Navidrome from a binary package.

pkg install navidrome

Follow any on screen instructions to complete your installation.

Build & Install Using Ports

Instead of using a binary package you can build from source. Before you start, make sure your local ports tree is up to date. Refer to the FreeBSD Handbook on the recommended way to fetch or update your ports tree.

Switch to the port directory for Navidrome and run make install.

cd /usr/ports/multimedia/navidrome
make install

The build process could take several minutes depending on the speed of your computer. Follow any on screen instructions to complete your installation.

Start the Navidrome Service

Start the service and verify it has started correctly.

service navidrome onestart
service navidrome onestatus

Navidrome is configured to listen on 127.0.0.1 on port 4533. The <library_path> is preset to ${PREFIX}/share/navidrome/music If the service has started correctly, verify you can access http://localhost:4533.

To run Navidrome at system startup, enable the service in /etc/rc.conf:

sysrc navidrome_enable="YES"

Customizing your Installation

The defaults provided out of the box by the port and package are sufficient to get your started. You can customize these settings if required by using a combonation of /etc/rc.conf and the Navidrome configuration file.

Run as a Different User

Navidrome will run as the www user. If you need to change it to something else use /etc/rc.conf to set a user and group. You can easily adjust this using the sysrc tool:

sysrc navidrome_user="<user>"
sysrc navidrome_group="<group>"

Configuration File Location

A default configuration file will be installed under /usr/local/etc/navidrome named config.toml. This can be changed by setting a new path in /etc/rc.conf. You can easily adjust this using the sysrc tool:

sysrc navidrome_config="/path/to/new/config_file.toml"

Make sure the user Navidrome is running as has permission to read the file.

For additional configuration options see the configuration options page.

Data Folder

The data folder is located under /var/db/navidrome. The prefered way to change this is by using /etc/rc.conf You can easily adjust this using the sysrc tool:

sysrc navidrome_datafolder="/path/to/new/folder"

Make sure the user Navidrome is running as has permission to read and write to the folder contents.

2.7 - Community Maintained Packages

Even though the Navidrome project does not provide any pre-packaged installation for specific platforms, there are some packages created and maintained by the community, that can simplify the setup on some systems.

Here is the list of packages for various OSes/Distributions, provided by Repology:

More packages available, with links to download/install instructions:

If you create, or know of, other Navidrome packages that are publicly available, please add to the list above.

2.8 - Managed Hosting

The following providers offer managed hosting for Navidrome. This can be a good option if you don’t want to manage your own server.

PikaPods

Offers 1-click deployments for Navidrome with $5 free welcome credit. EU and US regions available. Includes daily backups and regular app updates.

Zenith

Offers 1-click deployments for Navidrome.

Get started with Navidrome on Zenith →

2.9 - Build from sources

If you can’t find a pre-built binary for your platform, you should open an issue in the project’s GitHub page.

If you don’t want to wait, you can try to build the binary yourself, with the following steps.

First, you will need to install Go 1.26+ and Node 24. The setup is very strict, and the steps below only work with these versions (enforced in the Makefile). Make sure to add $GOPATH/bin to your PATH as described in the official Go site

After the prerequisites above are installed, clone Navidrome’s repository and build it:

$ git clone https://github.com/navidrome/navidrome
$ cd navidrome
$ make setup        # Install build dependencies
$ make build        # Build UI and server, generates a single executable

On FreeBSD you have to use gmake:

$ git clone https://github.com/navidrome/navidrome
$ cd navidrome
$ gmake setup        # Install build dependencies
$ gmake build        # Build UI and server, generates a single executable

This will generate the navidrome executable binary in the project’s root folder.

NOTE: Remember to install ffmpeg in your system, a requirement for Navidrome to work properly. You may find the latest static build for your platform here: https://johnvansickle.com/ffmpeg/

3 - Getting Started

This guide walks you through your first session with Navidrome, from verifying your installation to playing your first song.

Before You Begin

Make sure you’ve completed the installation for your platform. Verify these items before proceeding:

Step 1: Verify Navidrome is Running

Before creating your admin user, confirm Navidrome started successfully.

Check the logs for a successful startup message:

• Docker
• Linux (systemd)
• Windows
• macOS

docker logs navidrome

sudo journalctl -u navidrome -f

cat /opt/navidrome/navidrome.log

What success looks like: You should see log entries showing Navidrome starting up and beginning to scan your music folder. Look for messages like:

Creating DB Schema
Scanner: Starting scan
Navidrome server is ready!

If you see errors about missing folders or permission denied, see Troubleshooting below.

Step 2: Create Your Admin User

Open your browser and navigate to http://localhost:4533 (or your custom address/port).

You should see the admin user creation screen:

Fill in your desired username and password, confirm the password, and click “Create Admin”.

What success looks like: After clicking the button, you’ll be logged in and see the Navidrome interface. The sidebar will show menu items like “Albums”, “Artists”, “Playlists”, etc.

Step 3: Wait for Your Music to Appear

Navidrome scans your music folder in the background. This takes time — the duration depends on your library size:

What success looks like: Albums and artists will gradually appear in the interface. You can monitor progress in the logs — look for messages showing files being processed.

Step 4: Play Your First Song

Once some music appears:

1. Click on “Albums” in the sidebar
2. Click on any album cover
3. Click the play button on any track

Congratulations! You’re now streaming your own music with Navidrome. 🎉

Troubleshooting

Music Not Appearing

Check scan progress in the logs. If you see ongoing scan activity, just wait — large libraries take time.

Verify your music folder path:

• Ensure the path in your configuration matches where your music files actually are
• Check that paths are case-sensitive on Linux/macOS
• For Docker: verify your volume mount is correct (e.g., -v /path/to/music:/music:ro)

Check file formats. Navidrome supports MP3, FLAC, AAC, OGG, OPUS, WMA, APE, WavPack, and more. Files must have proper audio metadata (tags) to appear correctly.

Permission Problems

The Navidrome process must have read access to your music folder.

• Docker
• Linux
• Windows
• macOS

user: 1000:1000  # Should match: ls -n /path/to/music

sudo chown -R $(id -u):$(id -g) /path/to/data  # must match the `user` directive

# Check current permissions
ls -la /path/to/music

# If needed, ensure the navidrome user can read:
sudo chmod -R o+rX /path/to/music
# Or add the navidrome user to the appropriate group

# Check permissions
ls -la /path/to/music

# Grant read access if needed
chmod -R o+rX /path/to/music

Cannot Access Navidrome in Browser

1. Verify the service is running (see Step 1 above)
2. Check you’re using the correct URL:
   • Default: http://localhost:4533
   • If accessing remotely, use your server’s IP address
   • If you configured a custom port, use that instead
3. Check firewall settings — port 4533 (or your custom port) must be open
4. For Docker: ensure the port mapping is correct (-p 4533:4533)

Playlists Not Importing

Navidrome imports .m3u playlists from your music folder, but only after an admin user exists. If playlists aren’t appearing:

1. Make sure you’ve created the admin user first
2. Update the playlist file timestamps to trigger reimport:

   touch /path/to/music/*.m3u
   

3. Wait for the next scan cycle, or trigger a manual scan from the UI

Platform-Specific Tips

• Docker
• Linux
• Windows
• macOS

Next Steps

Now that Navidrome is running, explore these features:

• Multi-Library Support: Organize multiple music collections (audiobooks, family libraries) with separate access controls
• Externalized Authentication: Integrate with your homelab SSO or external auth system
• Configuration Options: Customize scanning, transcoding, and more
• Client Apps: Connect mobile apps, desktop players, and more

Still having trouble? Check the full documentation or reach out to the community for help.

3.1 - Externalized Authentication Quick Start

What is externalized authentication

Externalized authentication allows you to use an external system to handle authentication for Navidrome. Instead of managing user credentials in Navidrome itself, the responsibility is delegated to an external authentication service.

The external system comprises a reverse proxy (nginx, Caddy, Traefik, etc.) and an authentication service (Authelia, Authentik, or any other authentication service that works with your reverse proxy).

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│    User     │ --> │   Reverse   │ --> │  Navidrome  │
│   Browser   │     │    Proxy    │     │    Server   │
└─────────────┘     └─────────────┘     └─────────────┘
                          │
                          V
                    Authentication
                        Service

Navidrome supports a header-based mechanism to retrieve data about the authenticated user from the reverse proxy.

This approach is usually called “reverse proxy authentication”, and offers several benefits:

• Increased flexibility: Leverage authentication methods not supported by Navidrome (LDAP, OAuth, 2FA, etc.)
• Single Sign-On (SSO): Users can login once and access multiple services
• Centralized user management: Manage all your users in one place

How It Works

1. Your reverse proxy authenticates the user
2. The proxy adds a header with the username (e.g., Remote-User: john) to the request, then forwards it to Navidrome
3. Navidrome checks that the request comes from a trusted IP (using ExtAuth.TrustedSources, more on that below)
4. If trusted, Navidrome uses the username from the header to identify the user
5. If the user doesn’t exist in Navidrome’s database, a new account is created automatically

Quick Start

Here’s the basic process for setting up externalized authentication:

1. Configure your reverse proxy with authentication. The integration depend on the proxy and authentication service.
2. Configure the reverse proxy to pass the username to Navidrome via an HTTP header. It should additionally be configured to prevent clients from setting the header themselves.
3. Configure Navidrome to trust your reverse proxy as authentication source.
4. (Optional) Configure the reverse proxy to allow unauthenticated requests on specific paths. This is only needed for some Navidrome features.
5. Test the setup

Basic Navidrome Configuration

By default, externalized authentication is disabled. To enable it:

1. Set the ExtAuth.TrustedSources option to tell Navidrome which IP address to trust.
2. Optionally customize the ExtAuth.UserHeader option if your proxy uses a different header than the default Remote-User

In your Navidrome configuration:

## IP address of your reverse proxy (CIDR notation)
ND_EXTAUTH_TRUSTEDSOURCES=192.168.1.10/32
## Optional: Change the header if needed (this is the default)
ND_EXTAUTH_USERHEADER=Remote-User

Special Value for UNIX Sockets

If you’re using UNIX sockets (with the Address option), use @ in your ExtAuth.TrustedSources option to accept the authentication header of requests from the socket:

ND_ADDRESS=/var/run/navidrome.sock
ND_EXTAUTH_TRUSTEDSOURCES=@

User Management

When using externalized authentication:

• The first user authenticated through the proxy will be granted admin privileges (just like the first user in a fresh installation)
• New users are created automatically with random passwords

You can also consider setting EnableUserEditing=false to prevent users from changing their Navidrome passwords (since they’re managed by your auth service):

# Disable password editing in Navidrome
ND_ENABLEUSEREDITING=false

Reverse Proxy Integration

The integration depends on your chosen reverse proxy and authentication service, so you should first get familiar with their documentation.

Some Navidrome features also require specific configuration of your reverse proxy:

• Public Shares: If you plan to use Navidrome’s sharing feature (for creating public links to your library), you need to configure your reverse proxy to bypass authentication for URLs starting with /share/, allowing unauthenticated access to the public shares.
• Subsonic Clients: For a basic setup, you can let Navidrome handle the Subsonic authentication by configuring your reverse proxy to bypass authentication for URLs starting with /rest/. Your users will have to set a password in Navidrome and use it with their Subsonic client (note that this is incompatible with EnableUserEditing=false).

We give some example configurations for popular reverse proxies. You can adapt these to your specific setup. Note that the examples might get outdated, you should always double-check the official documentation of your reverse proxy and authentication service.

Example: Caddy with Authentik

This example shows Navidrome behind Caddy with Authentik for authentication.

example.com {
   # Remove any client-supplied user header
   request_header -Remote-User

   # Authentik output endpoint
   reverse_proxy /outpost.goauthentik.io/* http://authentik:9000

   # Protect everything except share and subsonic endpoints
   @protected not path /share/* /rest/*
   forward_auth @protected http://authentik:9000 {
      uri /outpost.goauthentik.io/auth/caddy
      copy_headers X-Authentik-Username>Remote-User
   }

   # Forward everything to Navidrome
   reverse_proxy navidrome:4533
}

Example: Traefik with Authelia

This example uses Traefik with Authelia for authentication, using Docker Compose.

services:
  authelia:
    image: authelia/authelia:4.38.8
    labels:
      # Login page
      traefik.http.routers.authelia.rule: Host(`auth.example.com`)
      traefik.http.routers.authelia.entrypoints: https

      # Authentication middleware
      traefik.http.middlewares.authelia.forwardauth.address: http://authelia:9091/api/verify?rd=https://auth.example.com/
      traefik.http.middlewares.authelia.forwardauth.authResponseHeaders: Remote-User

      # Security middleware for the entrypoints
      traefik.http.middlewares.drop-untrusted-auth-headers.headers.customrequestheaders.Remote-User:

  navidrome:
    image: deluan/navidrome:0.52.0
    labels:
      # Main Navidrome access with web authentication
      traefik.http.routers.navidrome.rule: Host(`music.example.com`)
      traefik.http.routers.navidrome.entrypoints: https
      traefik.http.routers.navidrome.middlewares: drop-untrusted-auth-headers@docker,authelia@docker

      # Authentication bypass for share and subsonic endpoints
      traefik.http.routers.navidrome-public.rule: Host(`music.example.com`) && (PathPrefix(`/share/`) || PathPrefix(`/rest/`))
      traefik.http.routers.navidrome-public.entrypoints: https
      traefik.http.routers.navidrome-public.middlewares: drop-untrusted-auth-headers@docker
    environment:
      # Trust all IPs in Docker network - use more specific IP if possible
      ND_EXTAUTH_TRUSTEDSOURCES: 0.0.0.0/0

Security Considerations

Make sure to check the Security Considerations page for important security information.

Key security points:

• Never run Navidrome as root
• Properly secure UNIX sockets if used
• Be careful with dynamic IP addresses in Docker environments
• Ensure that your reverse proxy is properly configured to remove the authentication header if set by clients (some, but not all, do it by default; some do it by default only for specific header names)

Troubleshooting

Common issues and solutions:

1. Authentication not working

   • Check that your reverse proxy IP is in the ExtAuth.TrustedSources option and in CIDR format: X.X.X.X/32
   • Verify the correct that header is being sent by the reverse proxy (Remote-User by default)
   • Check the proxy logs to confirm that the authentication is successful

2. New users not being created

   • Ensure that the header contains the correct username
   • Check the Navidrome logs for any errors

3. Subsonic clients can’t connect

   • Verify your proxy configuration for the /rest/* endpoint
   • Check if your client supports the authentication method you’re using

4. Shared links not working

   • Make sure your proxy allows unauthenticated access to /share/* URLs

FAQ

Q: Can I use this with my existing OAuth provider?
A: Yes, as long as your reverse proxy can integrate with your OAuth provider and pass the username to Navidrome.

Q: What if I want to switch back to Navidrome’s authentication?
A: Remove or comment out the ExtAuth.TrustedSources configuration.

Q: Can I mix authentication methods?
A: Yes, Navidrome will fall back to standard authentication if the reverse proxy header is not present or the request’s source not trusted.

See Also

• Security Considerations for Navidrome
• Configuration Options for all available settings
• Externalized Authentication for the detailed documentation of the feature
• Caddy Forward Auth documentation
• Traefik ForwardAuth middleware

4 - Usage

4.1 - Configuration

4.1.1 - Navidrome Configuration Options

Navidrome allows some customization using environment variables, loading from a configuration file or using command line arguments.

When the same option is set using multiple methods, Navidrome uses the following order of precedence (highest to lowest): environment variables, command line arguments, configuration file.

Configuration File

Navidrome tries to load the configuration from a navidrome.toml file in the current working directory, if it exists. You can create this file and put any of the configuration options below in it. Example of a configuration file (select your OS):

• Example:
• Unix-based systems
• Windows
• macOS

# This is just an example! Please see available options to customize Navidrome for your needs at

# https://www.navidrome.org/docs/usage/configuration/options/#available-options

LogLevel = 'DEBUG'
Scanner.Schedule = '@every 24h'
TranscodingCacheSize = '150MiB'
MusicFolder = '/mnt/music'

# This is just an example! Please see available options to customize Navidrome for your needs at

# https://www.navidrome.org/docs/usage/configuration/options/#available-options

LogLevel = 'DEBUG'
Scanner.Schedule = '@every 24h'
TranscodingCacheSize = '150MiB'

# IMPORTANT: Use single quotes for paths in Windows

MusicFolder = 'C:\Users\JohnDoe\Music'

# Set this to the path of your ffmpeg executable

FFmpegPath = 'C:\Program Files\ffmpeg\bin\ffmpeg.exe'

# This is just an example! Please see available options to customize Navidrome for your needs at

# https://www.navidrome.org/docs/usage/configuration/options/#available-options

LogLevel = 'DEBUG'
Scanner.Schedule = '@every 24h'
TranscodingCacheSize = '150MiB'
MusicFolder = '/Users/JohnDoe/Music'

# This is the default path for Homebrew installed ffmpeg

FFmpegPath = '/opt/homebrew/bin/ffmpeg'

You can also specify a different path for the configuration file, using the -c/--configfile option. Navidrome can load the configuration from toml, json, yml and ini files.

The example below assume you have created a navidrome.toml file in your home directory:

• Example:
• Unix-based systems
• Windows
• macOS

$ navidrome --configfile "/home/johndoe/navidrome.toml"

C:\> navidrome --configfile "c:\User\JohnDoe\navidrome.toml"

$ navidrome --configfile "/User/JohnDoe/navidrome.toml"

Command Line Arguments

You can set most of the config options below passing arguments to navidrome executable.

The example below shows how to set the MusicFolder using the command line, assuming you have your music library under your home directory:

• Example:
• Unix-based systems
• Windows
• macOS

$ navidrome --musicfolder "/mnt/music"

C:\> navidrome --musicfolder "c:\User\JohnDoe\Music"

$ navidrome --musicfolder "/User/JohnDoe/Music"

Please note that command line arguments must be all lowercase. For a list of all available command line options, just call navidrome --help.

For command and workflow examples (scan, inspect, backups, users, service management), see the CLI reference.

Environment Variables

Any configuration option can be set as an environment variable, just add a the prefix ND_ and make it all uppercase. Ex: ND_LOGLEVEL=debug. See below for all available options

Available Options

Basic configuration

Advanced configuration

Notes

• Durations are specified as a number and a unit suffix, such as “24h”, “30s” or “1h10m”. Valid time units are “s”, “m”, “h”.
• Sizes are specified as a number and an optional unit suffix, such as “1GB” or “150 MiB”. Default unit is bytes. Note: “1KB” == “1000”, “1KiB” == “1024”
• Transcoding can be required in some situations. For example: trying to play a WMA file in a webbrowser, will only work for natively supported formats by the browser you are using. (so playing that with Mozilla Firefox on Linux, will not work. Mozilla even has their own guide about audio codecs).

4.1.2 - Using custom tags with Navidrome

Overview

As all tags imported are stored and indexed in the database, to improve performance and reduce storage requirements, Navidrome only imports a predefined set of tags. The complete list of default tags imported are listed here.

However, Navidrome supports importing and using custom tags from your music files. Custom tags allow you to extend the metadata beyond the default supported tags. This functionality can be configured via the configuration file.

Configuring custom tags

Custom tags are defined under the Tags configuration section. A custom tag configuration accepts the following properties:

• Aliases: A list of all alternative names that can found in your music files, but should be considered the same tag. Ex: album artist, albumartist. This is a required field.
• Type: Specifies the type of data stored in the tag. It can be used to validate or transform values. Supported types are int,float, date, uuid. If not specified, the tag will be treated as a string.
• MaxLength: The length limit for the tag value. Default is 1024 characters.
• Album: A boolean flag indicating whether this tag applies to an album as well. Default is false. If set to true, the tag will be considered when generating the PID for an album.
• Split: Tags are always considered multivalued, but you can specify a list of delimiters used to split a tag value into multiple entries.
• Ignore: A boolean flag indicating whether this tag should be ignored. Default is false. Useful for disabling tags that are imported by default. See example below.

Note that tags are case-insensitive, so you don’t need to specify all possible case variations in the Aliases list.

Example configuration

Below is an example of how to set up custom tag options in your configuration file.

Tags.MyCustomTag.Aliases = ["mycustomtag", "customtag"]
Tags.MyCustomTag.MaxLength = 50
Tags.MyCustomTag.Album = false
Tags.MyCustomTag.Split = ["; ", " / "]

In this example, the custom tag mycustomtag is configured with two aliases, a type of string (default), and a maximum length of 50 characters. Additionally, it sets the splitting delimiters so that if a tag value contains ; or / it will be split into multiple values.

Common use cases

Here are some common use cases for custom tags.

Adding a new tag for disambiguation

By default, Navidrome uses MusicBrainz IDs to identify albums and tracks. However, if your music library is tagged with information from other DBs, like Discogs, you can add custom tags to store the Discogs IDs.

Example:

Tags.discogs_release_id.Aliases = ['discogs_release_id']
Tags.discogs_release_id.Album = true
PID.Album = 'discogs_release_id|albumartistid,album,albumversion,releasedate'

See the PID configuration for more information on how to configure album disambiguation.

Disabling tags

Any custom tag found in your music files, but not defined with the Tags configuration option will be ignored by Navidrome. If you need to disable a tag that is already imported by default, you can do so by explicitly setting its Ignore flag to true.

Example: disabling the subtitle tag

Tags.Subtitle.Ignore = true

Changing separators

The preferable way to have multivalued tags is to use your tag editor and add multiple values for the same tag. However, if your library is already tagged with multiple values separated by a known delimiter, you can configure Navidrome to split the tag value by that delimiter into multiple entries. Just keep in mind that this can have unwanted side effects if the delimiter is used in other contexts. (Ex: using '/' as an artist delimiter can break artists like AC/DC, '&' as a delimiter can break artists like Simon & Garfunkel)

Example: Splitting the artist tag by \ and ;

Tags.Artist.Split = ['\', '; ']

If you want to disable splitting for a tag, you can set the Split option to an empty list.

Tags.Genre.Split = []

Artist splitting

By default, Navidrome will split the artist tag value by various common separators to identify multiple artists. The default Tags.Artist.Split value is:

Tags.Artist.Split = [" / ", " feat. ", " feat ", " ft. ", " ft ", "; "]

Because the slash separator is " / " (with surrounding spaces) rather than a bare /, a name like AC/DC is left intact by default. Note that "; " only requires a trailing space, so a value like Foo; Bar is still split.

To customize the separators, override this option. Be careful when adding a bare / (without spaces): it will split names like AC/DC. See Scanner.ArtistSplitExceptions to protect specific names from being split.

Note that the separators are case insensitive, so both FEAT. and feat. will be recognized by default.

Separating Writer and Composer tags

By default, Navidrome maps both composer and writer tag values to a single (multi-valued) composer field in its database. If you want to keep these as separate metadata fields, you can define custom tags for each one:

Tags.Composer.Aliases = ['composer', 'tcom', 'composer', '©wrt', 'wm/composer', 'imus']
Tags.Writer.Aliases = ['writer', 'txxx:writer', 'iwri']

This will allow you to filter or sort by writer in Smart Playlists.

Adding tags for custom filtering/sorting in Smart Playlists

If you want to create a Smart Playlist that filters or sorts by a custom tag, you can define the tag in the configuration file, then use it in the Smart Playlist as a regular field.

4.1.3 - Customizing Persistent IDs in Navidrome

Persistent IDs in Navidrome

Persistent IDs (PIDs) are configurable identifiers introduced to provide stable references for Tracks and Albums in Navidrome, significantly improving how media is managed and identified.

Overview of Persistent IDs

Persistent IDs are unique, user-configurable identifiers for tracks and albums, enabling Navidrome to accurately detect and manage moved or re-tagged files, and disambiguate albums with identical names or duplicated entries.

Key Features

• Configurable and Flexible: Users can define their PID structure using various tags, including musicbrainz_trackid, albumid, discnumber, tracknumber, title, folder, albumartistid, catalognum, Discogs IDs, or even custom tags
• Accurate File Detection: Navidrome recognizes moved or re-tagged files, preventing duplication or mismatches.
• Album Disambiguation: Easily differentiate albums with identical names through custom tags like albumversion (e.g., Deluxe Editions).

Default Configuration

The default configuration prioritizes MusicBrainz IDs (MBIDs) when available:

PID.Track = "musicbrainz_trackid|albumid,discnumber,tracknumber,title"
PID.Album = "musicbrainz_albumid|albumartistid,album,albumversion,releasedate"

• Track PID:

  • Uses musicbrainz_trackid if available.
  • Otherwise, combines albumid, discnumber, tracknumber, and title. (albumid is derived from PID.Album.)

• Album PID:

  • Uses musicbrainz_albumid if available.
  • Otherwise, combines albumartistid, album, albumversion, and releasedate.

Customizing PIDs

You can create custom PID configurations to meet specific needs, such as:

• Grouping albums by folder:

  PID.Album = "folder"
  

• Using Discogs or custom IDs for albums:

  Tags.discogs_release_id.Aliases = ['DISCOGS_RELEASE_ID']
  PID.Album = 'discogs_release_id|albumartistid,album,albumversion,releasedate'
  

• Using the pre-0.55.0 (pre-BFR) behaviour:

  PID.Album = "album_legacy"
  PID.Track = "track_legacy"
  

  This will use the old ID generation method, which is based on the file path for tracks and name+releaseDate for albums.

Handling File Moves and Retagging

When files are moved, Navidrome uses PIDs to accurately identify and reconnect these files on the next scan:

• First, Navidrome attempts to match a missing file with new ones based on exact tags.
• If exact tags do not match, Navidrome checks for a matching PID.
• Finally, if no PID match is found, it attempts to match the file based on the original file path, excluding the file extension (ex: /artist/album/01-track.mp3 → /artist/album/01-track.flac).

This ensures minimal disruption to playlists, ratings, and play counts when managing your media library.

You can also retag your files, and Navidrome will automatically update the PIDs based on the new tags.

Artist IDs

Currently, Artist PIDs rely solely on the artist name due to limitations in TagLib/Picard regarding MBIDs for composer and other roles, potentially causing duplicate entries. For this reason they are not configurable. Future enhancements are planned to address this.

Troubleshooting and Support

If issues arise when enabling or configuring PIDs:

• Review Navidrome logs.
• Validate your configuration file.

4.2 - Features

4.2.1 - How to Use Smart Playlists in Navidrome (Beta)

Smart Playlists in Navidrome offer a dynamic way to organize and enjoy your music collection. They are created using JSON objects stored in files with a .nsp extension. These playlists are automatically updated based on specified criteria, providing a personalized and evolving music experience.

Creating Smart Playlists

To create a Smart Playlist, you need to define a JSON object with specific fields and operators that describe the criteria for selecting tracks. The JSON object is stored in a .nsp file Here are some examples to get you started:

Example 1: Recently Played Tracks

This playlist includes tracks played in the last 30 days, sorted by the most recently played.

{
  "name": "Recently Played",
  "comment": "Recently played tracks",
  "all": [{ "inTheLast": { "lastPlayed": 30 } }],
  "sort": "lastPlayed",
  "order": "desc",
  "limit": 100
}

Example 2: 80’s Top Songs

This playlist features top-rated songs from the 1980s.

{
  "all": [
    { "any": [{ "is": { "loved": true } }, { "gt": { "rating": 3 } }] },
    { "inTheRange": { "year": [1981, 1990] } }
  ],
  "sort": "year",
  "order": "desc",
  "limit": 25
}

Example 3: Favourites

This playlist includes all loved tracks, sorted by the date they were loved.

{
  "all": [{ "is": { "loved": true } }],
  "sort": "dateLoved",
  "order": "desc",
  "limit": 500
}

Example 4: All Songs in Random Order

This playlist includes all songs in a random order. Note: This is not recommended for large libraries.

{
  "all": [{ "gt": { "playCount": -1 } }],
  "sort": "random"
  // limit: 1000 // Uncomment this line to limit the number of songs
}

Example 5: Multi-Field Sorting

This playlist demonstrates multiple sort fields - songs from the 2000s, sorted by year (descending), then by rating (descending), then by title (ascending).

{
  "name": "2000s Hits by Year and Rating",
  "all": [{ "inTheRange": { "year": [2000, 2009] } }],
  "sort": "-year,-rating,title",
  "limit": 200
}

Example 6: Library-Specific Playlist

This playlist includes only high-rated songs from a specific library (useful in multi-library setups).

{
  "name": "High-Rated Songs from Library 2",
  "all": [{ "is": { "library_id": 2 } }, { "gt": { "rating": 4 } }],
  "sort": "-rating,title",
  "limit": 100
}

Example 7: Percentage-Based Limit

This playlist includes 10% of all loved tracks, selected randomly. Use limitPercent instead of limit to specify a percentage of matching tracks (1-100). A minimum of 1 track is always returned when there are matches.

{
  "all": [{ "is": { "loved": true } }],
  "sort": "random",
  "limitPercent": 10
}

Example 8: Recently Added Albums, in Album Order

Sorting by the track-level dateadded scatters an album’s tracks, because each track has its own timestamp. Sorting by albumdateadded keeps the album together and puts the most recently added albums first, while discnumber and tracknumber order the tracks within each album.

{
  "name": "Recently Added Albums",
  "all": [{ "inTheLast": { "albumdateadded": 30 } }],
  "sort": "-albumdateadded,album,discnumber,tracknumber"
}

Example 9: Daily Mix (stable for a day)

This playlist picks 20 random tracks played in the last 30 days, and keeps the same track list for a full day before re-evaluating. Without refreshDelay, a playlist like this would change after every song you play, which breaks offline caches. See Refreshing Playlists for details.

{
  "name": "Daily Mix",
  "all": [{ "inTheLast": { "lastPlayed": 30 } }],
  "sort": "random",
  "limit": 20,
  "refreshDelay": "1d"
}

Creating Smart Playlists using the UI

Currently Smart Playlists can only be created by manually editing .nsp files. We plan to add a UI for creating and editing Smart Playlists in future releases.

In the meantime, if you want a graphical way to create playlists, you can use Feishin, a desktop/web client for Navidrome, that supports creating Smart Playlists:

Smart Playlists created/edited in Feishin will be available in Navidrome UI as soon as they are saved.

Importing Smart Playlists

Smart Playlists are imported the same way as regular (.m3u) playlists, during the library scan. Place your .nsp files in any folder in your library or the path specified by the PlaylistsPath configuration. Navidrome will automatically detect and import these playlists.

Managing Smart Playlists

Visibility and Ownership

• Visibility: To make a Smart Playlist accessible to all users, set it to ‘public’. When referencing a playlist from another .nsp file (with inPlaylist and notInPlaylist), the playlist must be accessible to the smart playlist’s owner: owners can reference their own playlists (public or private), any user can reference public playlists, and admins can reference any playlist. See Referencing Other Playlists for details.
• Ownership: By default, Smart Playlists are owned by the first admin user. You can change the ownership in the Playlists view to allow other users to manage them.

User-Specific Playlists

Smart Playlists based on user interactions (e.g., play count, loved tracks) are automatically updated based on the owner’s interactions. If you want personalized playlists for each user, create separate .nsp files for each user and assign ownership accordingly.

Refreshing Playlists

Smart Playlists are refreshed automatically when they are accessed by the UI or any Subsonic client. This ensures that the playlist is up-to-date when you view it. To avoid unnecessary load, there is a minimum delay between refreshes. This delay can be adjusted by setting the SmartPlaylistRefreshDelay configuration option. By default, this is set to 5s, meaning that Smart Playlists refreshes are spaced at least 5 seconds apart. You can adjust this value in the configuration file.

Per-Playlist Refresh Delay

You can override the global delay for an individual playlist by adding a refreshDelay to its .nsp file. The playlist then keeps the same track list until that much time has passed since it was last evaluated. This is useful for “daily mix” style playlists whose rules would otherwise reshuffle the tracks on every access, and it keeps the track list stable for clients that cache playlists for offline playback.

{
  "name": "Weekly Discoveries",
  "all": [{ "notInTheLast": { "lastPlayed": 90 } }],
  "sort": "random",
  "limit": 50,
  "refreshDelay": "1w"
}

The value is a duration string. Besides the standard units (h, m, s), d (days) and w (weeks) are also supported, so values like "12h", "1d", "1w" or "1d12h" all work. The delay is a rolling window measured from the last evaluation, not aligned to calendar days. When refreshDelay is not set, the global SmartPlaylistRefreshDelay applies.

Editing the playlist’s rules (by changing the .nsp file or via a client) always takes effect on the next access, even if the refresh delay has not elapsed yet.

Troubleshooting Common Issues

Playlist Not Showing Up

If a Smart Playlist is not showing up in the Navidrome UI, check the following:

• Check the logs for any errors during the library scan.
• Ensure the .nsp file is in the correct folder and has the correct permissions.
• Ensure the file is correctly formatted and does not contain any syntax errors. Tip: Use a JSON validator to check the file (ex: https://jsonlint.com/)
• Check the playlist’s visibility and ownership settings.

Referencing Other Playlists

When referencing another playlist (using the inPlaylist or notInPlaylist operators), ensure that the referenced playlist is accessible to the smart playlist’s owner:

• The owner can reference their own playlists, whether public or private.
• Any user can reference playlists that are set to ‘public’.
• Admins can reference any playlist, regardless of owner or visibility.

This applies whether the referenced playlist is a regular or another Smart Playlist. If the referenced playlist is not accessible, Navidrome logs a warning during the scan and the rule simply matches no tracks, rather than failing the whole playlist.

Special Characters in Conditions

If you encounter issues with conditions like contains or endsWith, especially with special characters like underscores (_), be aware that these might be ignored in some computations. Adjust your conditions accordingly.

Sorting by multiple fields

You can now sort by multiple fields by separating them with commas. You can also control the sort direction for each field by prefixing it with + (ascending, default) or - (descending).

Examples:

• "sort": "year,title" - Sort by year first (ascending), then by title (ascending)
• "sort": "year,-rating" - Sort by year (ascending), then by rating (descending)
• "sort": "-lastplayed,title" - Sort by last played date (descending), then by title (ascending)

The global order field can still be used and will reverse the direction of all sort fields.

Deleting Users with Shared Smart Playlists

If you encounter issues deleting users with shared Smart Playlists, check if the playlists are used by other users. See this issue for details.

Editing Playlists

To change the rules of a Smart Playlist, you need to edit the .nsp file directly (or use Feishin). Changes are automatically detected during the next library scan. The list of tracks in a Smart Playlist is read-only and cannot be edited directly.

Additional Resources

Fields

Here’s a table of fields you can use in your Smart Playlists:

Notes

• Dates must be in the format "YYYY-MM-DD".
• Booleans must not be enclosed in quotes. Example: { "is": { "loved": true } }.
• Boolean fields: hascoverart, compilation, missing, loved, albumloved, artistloved.
• filepath is relative to your music library folder. Ensure your paths are correctly specified without the /music prefix (or whatever value you set in MusicFolder).
• Numeric fields like library_id, year, tracknumber, discnumber, size, duration, bitrate, bitdepth, samplerate, bpm, channels, playcount, rating, averagerating, albumduration, albumsongcount, albumsize, and the ReplayGain fields (rgtrackgain, rgtrackpeak, rgalbumgain, rgalbumpeak) support numeric comparisons (gt, lt, inTheRange, etc.).
• Multi-Library: Smart Playlists can include songs from multiple libraries if the user has access to them. Use the library_id field to filter songs from specific libraries.
• Album & Artist Fields: Fields prefixed with album or artist (e.g., albumrating, artistplaycount) filter tracks based on their parent album or artist properties. This lets you create playlists like “tracks from highly-rated albums” or “tracks from frequently-played artists”. albumdateadded, albumdatemodified, albumduration, albumsongcount and albumsize describe the album itself rather than your listening history, so they are the same for every track on an album — which is what makes them useful as a sort key (see Example 8).

Special Fields

• random: Used for random sorting (e.g., "sort": "random")

MusicBrainz Fields

The following fields contain MusicBrainz IDs that can be used to create playlists based on specific MusicBrainz entities:

• mbz_album_id: Filter by specific MusicBrainz album
• mbz_album_artist_id: Filter by specific MusicBrainz album artist
• mbz_artist_id: Filter by specific MusicBrainz artist
• mbz_recording_id: Filter by specific MusicBrainz recording
• mbz_release_track_id: Filter by specific MusicBrainz release track
• mbz_release_group_id: Filter by specific MusicBrainz release group

Custom Tags

Any tags imported from the music files, that are not listed above, can be also used as fields in your Smart Playlists. Check the complete list of tags imported by navidrome. You can also add your own custom tags to your music files and use them in your Smart Playlists. Check the Custom Tags for more information.

Operators

Here’s a table of operators you can use in your Smart Playlists:

The nature of the field determines the argument type. For example, year and tracknumber require a number, while title and album require a string.

Checking for Missing or Present Tags

The isMissing and isPresent operators let you match tracks based on whether a field has any value at all, regardless of what that value is. They are supported for:

• Tag fields, such as genre, mood, or any custom tag
• Role fields, such as composer or conductor
• Numeric fields where Navidrome stores no value when the tag is absent: the ReplayGain fields (rgtrackgain, rgtrackpeak, rgalbumgain, rgalbumpeak), bpm, and bitdepth (a missing bit depth also matches lossy formats such as MP3, which have no bit depth)
• Text fields, where an empty value also counts as missing: album, comment, lyrics, catalognumber, discsubtitle, albumcomment, explicitstatus, sorttitle, sortalbum, sortartist, sortalbumartist, and the MusicBrainz ID fields (mbz_album_id, mbz_album_artist_id, mbz_artist_id, mbz_recording_id, mbz_release_track_id, mbz_release_group_id)

Each takes a single field mapped to a boolean. The boolean inverts the check, so isMissing and isPresent are mirror images of each other:

{ "all": [{ "isMissing": { "genre": true } }] }

The example above matches tracks that have no genre tag. The following all describe the opposite condition (tracks that do have a genre tag):

{ "isMissing": { "genre": false } }
{ "isPresent": { "genre": true } }

The inPlaylist and notInPlaylist operators take a condition object with the playlist’s id:

{ "inPlaylist": { "id": "dVX0hgcj4JJFjTs66xpEqI" } }

To get a playlist’s ID, navigate to the playlist in the Navidrome UI and check the URL. The ID is the last part of the URL after the /playlists/ path:

Here’s a complete example of a Smart Playlist that includes all tracks from another playlist, shuffled randomly:

{
  "all": [{ "inPlaylist": { "id": "dVX0hgcj4JJFjTs66xpEqI" } }],
  "sort": "random",
  "limit": 50
}

Alternatively, the inPlaylist and notInPlaylist operators can take a path argument, which can either be absolute or relative to your playlist. This allows your smart playlists to be tranferrable between servers.

{ "inPlaylist": { "path": "../other_playlist.nsp" } }

Here’s an example of building a smart playlist out of multiple more focused playlists. Keep all the rules under a single top-level group (all or any) and nest a group when you need to mix the two logics: a top-level any and all cannot be combined at the same level.

{
  "name": "Overplayed Favorites",
  "comment": "Most Played Favorites Played Within Last 4yr",
  "public": true,
  "all": [
    { "inPlaylist": { "path": "most-played-favorites.nsp" } },
    { "notInPlaylist": { "path": "favorites-not-played-in-4-yrs.nsp" } }
  ],
  "sort": "playCount, lastPlayed"
}

4.2.2 - Multi-Library Support

Overview

Navidrome supports multiple music libraries since v0.58.0, allowing you to organize your music into separate collections with user-specific access controls. This feature is perfect for:

• Separating different types of content (music vs. audiobooks)
• Organizing by quality (lossy vs. lossless)
• Separating personal collections (family members, roommates)
• Organizing by genre or era (classical, jazz, modern)
• Managing different sources (official releases vs. bootlegs/live recordings)

How Multi-Library Works

Default Library

When Navidrome starts, it automatically creates a default library using your MusicFolder configuration. This becomes “Library 1” and all existing users automatically get access to it, ensuring backward compatibility.

User Access Control

• Admin users automatically have access to all libraries
• Regular users must be explicitly granted access to libraries by an administrator
• Users can only see and access music from libraries they have permission to use
• Each user can switch between their accessible libraries using the library selector in the UI

Data Isolation

• Albums are scoped to a single library; each library maintains its own set of albums and their songs.
• Artists can have albums and songs spread across multiple libraries. The same artist may appear in several libraries, each with different albums or tracks.
• Artist statistics and metadata are aggregated across all libraries where the artist appears.
• Playlists can contain songs from multiple libraries (if the user has access to those libraries)
• Smart playlists can be scoped to specific libraries
• Search results are filtered by the user’s accessible (and selected) libraries

Setting Up Multi-Library

Creating Additional Libraries

1. Access Library Management

   • Log in as an administrator
   • Go to Settings → Libraries

2. Create a New Library

   • Click the "+" button to add a new library
   • Provide a Name for the library (e.g., “Audiobooks”, “FLAC Collection”)
   • Set the Path to the folder containing your music files
   • Optionally set the library as default for new users
   • Click Save

3. Initial Scan

   • The new library will automatically begin scanning
   • Monitor the scanning progress in the Activity Panel
   • Large libraries may take time to complete the initial scan

Managing User Access

1. Assign Libraries to Users

   • Go to Settings → Users
   • Click on a user to edit their settings
   • In the Libraries section, check the libraries the user should access
   • Click Save

2. Verify Access

   • Users will see a library selector in the sidebar if they have access to multiple libraries
   • The library selector is displayed in the top left corner of the UI
   • Users can select multiple libraries to browse and listen to their music

Configuration Considerations

File Organization

Each library should have its own root folder structure:

/music/main/           # Default library (MusicFolder)
├── Artist 1/
├── Artist 2/
└── ...

/music/audiobooks/     # Audiobooks library
├── Author 1/
├── Author 2/
└── ...

/other_path/lossless/       # High-quality library
├── Artist 1/
├── Artist 2/
└── ...

It is up to the user where to save music collections. You can store your artists in /music or any other path you want to use.

Permissions

• The Navidrome user must have read access to all library folders
• Consider using the same ownership/permissions across all library folders
• Ensure adequate disk space for each library’s cache and metadata

Performance

• Each library maintains its own file system watcher
• Multiple libraries scanning simultaneously may impact performance
• Consider staggering initial scans of large libraries
• Large numbers of libraries may affect UI performance

Using Multi-Library

Switching Libraries

• Use the library selector in the sidebar to select visible libraries
• All browsing, searching, and playback is scoped to the selected libraries

Cross-Library Features

• Playlists: Can contain songs from multiple libraries (user must have access)
• Smart Playlists: Can be scoped to specific libraries using filters
• Search: Results from all accessible libraries (filtered by permissions)
• Statistics: Maintained separately per library

API and Client Support

Subsonic API

• The getMusicFolders endpoint returns all libraries accessible to the authenticated user
• All other endpoints respect the user’s library permissions
• Clients that support multiple music folders will work with Navidrome’s multi-library feature

Client Compatibility

Most Subsonic-compatible clients that support multiple music folders will work with Navidrome’s multi-library feature. Check your client’s documentation for music folder support.

Troubleshooting

Library Not Scanning

• Verify the path exists and is readable by the Navidrome user
• Check the logs for permission errors
• Ensure the path doesn’t overlap with other libraries

User Cannot Access Library

• Verify the user has been granted access to the library in user settings
• Check that the library has completed its initial scan

Performance Issues

• Monitor system resources during simultaneous library scans
• Consider adjusting scanner settings if experiencing high I/O

Best Practices

• Design your folder structure before creating libraries
• Use clear, descriptive names for libraries
• Consider future growth when organizing

Related Features

• Configuration Options: Basic setup and MusicFolder configuration
• Smart Playlists: Create dynamic playlists with library-specific filters
• Backup: Protecting your multi-library setup

4.2.3 - Jukebox mode

Introduction

Navidrome’s Jukebox feature is a built-in functionality that allows users to play music directly to the server’s audio hardware. This essentially turns your server into a jukebox, enabling you to play songs or playlists remotely through a supported Subsonic client. With the Jukebox feature, you can control the audio playback in real-time, just like you would with any other media player. It’s a convenient way to enjoy your music collection without the need for additional hardware or software. Ideal for parties, background music, or personal enjoyment, this feature enhances the versatility of your Navidrome server setup.

Navidrome’s Jukebox mode is based on the OpenSource audio player MPV. MPV is a mature and tested audio/videoplayer that is supported on many platforms. Navidrome’s Jukebox mode uses MPV for audio playback in combination with MPV’s feature to be controlled through IPC.

MPV Installation

MPV must be present on the system where the Navidrome server runs. You might find it already installed or could install it yourself using the methods given on the MPV’s installation page.

The minimal requirement is the IPC support. MPV added IPC support with version 0.7.0 for Linux and macOS and added Windows support with version 0.17.0. Your OS will most probably include newer versions (0.3X) which we recommend. After the installation check the version with:

$ mpv --version

Jukebox mode will use the MPV audio device naming scheme for its configuration. To get an overview about the available audio devices on the system do:

$ mpv --audio-device=help

Here is an example on macOS:

List of detected audio devices:
  'auto' (Autoselect device)
  'coreaudio/AppleGFXHDAEngineOutputDP:10001:0:{D109-7950-00005445}' (BenQ EW3270U)
  'coreaudio/AppleUSBAudioEngine:Cambridge Audio :Cambridge Audio USB Audio 1.0:0000:1' (Cambridge Audio USB 1.0 Audio Out)
  'coreaudio/BuiltInSpeakerDevice' (MacBook Pro-Lautsprecher)

or on Linux:

List of detected audio devices:
  'auto' (Autoselect device)
  'alsa' (Default (alsa))
  'alsa/jack' (JACK Audio Connection Kit)
  'alsa/default:CARD=Headphones' (bcm2835 Headphones, bcm2835 Headphones/Default Audio Device)

  ...

  'jack' (Default (jack))
  'sdl' (Default (sdl))
  'sndio' (Default (sndio))

Please use the full device name if you do not want to use MPV’s auto device. For example on macOS:

"coreaudio/AppleUSBAudioEngine:Cambridge Audio :Cambridge Audio USB Audio 1.0:0000:1"

Configuration

Jukebox mode is enabled by setting this option in your configuration file (normally navidrome.toml):

Jukebox.Enabled = true

In most cases, this should be the only config option needed.

The MPV binary should be found automatically on the path. In case this does not work use this configuration option:

MPVPath = "/path/to/mpv"

Jukebox mode will use MPV’s auto device for playback if no device is given.

One can supply an array of multiple devices under Jukebox.Devices (note: this config option cannot be set as an environment variable):

Jukebox.Devices = [
    # "symbolic name " "device"
    [ "internal",     "coreaudio/BuiltInSpeakerDevice" ],
    [ "dac",          "coreaudio/AppleUSBAudioEngine:Cambridge Audio :Cambridge Audio USB Audio 1.0:0000:1" ]
]

and select one by using Jukebox.Default:

Jukebox.Default = "dac"

Here is one example configuration:

# Enable/Disable Jukebox mode
Jukebox.Enabled = true

# List of registered devices, syntax:
#  "symbolic name " - Symbolic name to be used in UI's
#  "device" - MPV audio device name, do mpv --audio-device=help to get a list

Jukebox.Devices = [
    # "symbolic name " "device"
    [ "internal",     "coreaudio/BuiltInSpeakerDevice" ],
    [ "dac",          "coreaudio/AppleUSBAudioEngine:Cambridge Audio :Cambridge Audio USB Audio 1.0:0000:1" ]
]

# Device to use for Jukebox mode, if there are multiple entries above.
# Using device "auto" if missing
Jukebox.Default = "dac"

The MPVCmdTemplate / Snapcast integration

There might be cases, where you want to control the call of the mpv binary. Noteable mentions would be the integration with Snapcast for multi room audio. You can use the MPVCmdTemplate for this.

The default value is mpv --audio-device=%d --no-audio-display --pause %f --input-ipc-server=%s.

To integrate with Snapcast alter the template:

MPVCmdTemplate = "mpv --no-audio-display --pause %f --input-ipc-server=%s --audio-channels=stereo --audio-samplerate=48000 --audio-format=s16 --ao=pcm --ao-pcm-file=/tmp/snapfifo"

This assumes Snapcast is running on the same machine as Navidrome. Check the Snapcast documentation for details.

Usage

Once Jukebox mode is enabled and configured, to start playing music through your servers speakers you’ll need to download a third-party Subsonic client. This client acts as a remote control. Not all Subsonic clients support Jukebox mode and you’ll need to check that your client supports this feature.

Jukebox mode is currently not supported through the Navidrome Web UI.

Troubleshooting

If Jukebox mode is enabled one should see the message “Starting Jukebox service” in the log. The number of detected audio devices and the device chosen will be given in the log as well:

INFO[0000] Starting playback server
INFO[0000] 4 audio devices found
INFO[0000] Using default audio device: dac

For further troubleshooting, set Navidrome’s loglevel to DEBUG:

LogLevel = 'DEBUG'

4.2.4 - Sharing

Navidrome has a “Sharing” feature which allows users to generate a shareable link for a track, album, artist, or playlist. This link can then be sent to friends, allowing them to listen or download the music without having an account on your Navidrome instance.

Enabling and Disabling Sharing

The Sharing feature is enabled by default. To turn it off, set EnableSharing=false in your configuration file, or set the environment variable ND_ENABLESHARING=false.

Any user can create shares. Each user only sees and manages the shares they created (editing a share’s description and expiration date, or deleting it); administrators can see and manage all shares. A share’s content is limited to the libraries its owner can access.

Sharing is controlled by a single server-wide toggle, so there is no per-user setting for who may create shares. If you’d rather your users not create public links, disable the feature as shown above.

Default Expiration for Shares

By default, new shares (public links) expire after 1 year (“8760h”). You can set a different default expiration time for all new shares using the DefaultShareExpiration config option. This sets how long new shares will be valid, unless you manually change the expiration when creating the share.

Set it in your config file:

DefaultShareExpiration = "8760h"  # Shares expire after 1 year by default

Or as an environment variable:

ND_DEFAULTSHAREEXPIRATION=8760h

Use values like "24h" or "1h30m". Valid suffixes are "h" (hours), "m" (minutes), and "s" (seconds).

Using the Sharing Feature

When browsing your music collection, you will notice a “Share” button or menu item available for each item, be it a track, album, artist, or playlist. To share an item, simply click on this “Share” button.

Upon clicking the “Share” button, a dialog box will appear, allowing you to configure your share. This includes setting a description other configurations for the share.

Once you have configured your share as desired, click the “Share” button. This will generate a unique shareable link, which you can then copy and share with your friends.

The generated sharable links will be in the following format: http://yourserver.com/share/XXXXXXXXXX. If you have Navidrome behind a reverse proxy, ensure you allow traffic to /share.

Subsonic API Endpoints

The Sharing feature also implements the related Subsonic API endpoints. See the API docs for implemented endpoints

Meta-tags to HTML

Meta-tags are added to the HTML to provide some information about the shared music on chat platforms. Example of a link shared in Discord:

4.2.5 - Scrobbling

Navidrome allows you to easily scrobble your played songs to Last.fm and ListenBrainz.

Last.fm

1. Ensure you have the API Key and API Secret set according to the instructions in External Integrations.
2. Go to your user profile’s Personal Settings.
3. Toggle the option Scrobble to Last.fm, a new browser tab will open directing you to Last.fm.

4. If you are not logged in, then log in with your Last.fm credentials.

5. Click “Yes, allow access”.

ListenBrainz

1. Toggle the option Scrobble to ListenBrainz. If you already have a User key generated, skip to step 4.
2. Click on the appropriate link in the pop-up that opens.

3. On the ListenBrainz website, either generate a new token or copy your existing one, then go back to your Navidrome tab.

4. Paste the token in the pop-up and save.

If you are using a self-hosted ListenBrainz-compatible server (e.g., Maloja), you can change the ListenBrainz.BaseURL config option to point to your instance.

Scrobble Filter

Starting with version 0.64.0, each user can keep some songs out of their scrobbles. Maybe you do not want holiday music in your Last.fm profile, or you only want songs rated 4 stars or more to shape your recommendations.

The filter uses the same JSON rules as smart playlists. Navidrome does not send matching songs to Last.fm, ListenBrainz or scrobbler plugins. It still counts the play locally, so play counts and scrobble history stay complete.

To set a filter, edit the user and paste the rules in the Scrobble filter field. Admins can do this for any user in Settings > Users. Regular users can set their own filter from their profile, if EnableUserEditing is on. Leave the field empty to scrobble everything.

Skip songs with the genre “Christmas”:

{"all":[{"is":{"genre":"Christmas"}}]}

Skip songs rated below 4 stars. Unrated songs have a rating of 0, so this skips them too:

{"all":[{"lt":{"rating":4}}]}

Skip everything in one library:

{"all":[{"is":{"library_id":3}}]}

The filter checks one song at a time, so limit, limitPercent, offset and refreshDelay make no sense here. Navidrome rejects rules that use them, and rules with unknown fields.

Scrobble History

Starting with version 0.59.0, Navidrome tracks your scrobble/listen history natively. This means that for music added after this version, Navidrome maintains a complete record of when each track was played. This historical data will be used in future features such as statistics and analytics (“Navidrome Wrapped” style reports).

4.2.6 - Plugins

Navidrome supports a plugin system that allows you to extend its functionality with community-developed extensions. Plugins run in a secure WebAssembly sandbox, providing isolation from the main application while enabling powerful customizations.

What Plugins Can Do

Plugins can extend Navidrome in several ways:

• Metadata Agents: Fetch artist biographies, album information, and images from external sources
• Scrobblers: Send your listening history to external services beyond the built-in Last.fm and ListenBrainz support
• Scheduled Tasks: Run periodic background tasks
• Event Handlers: React to events like playback or websocket events

Each plugin declares which capabilities it provides, and you can enable only the plugins you need.

Finding Plugins

Community-developed plugins can be found on GitHub using the navidrome-plugin topic.

When evaluating a plugin, consider:

• Repository activity: Check when the plugin was last updated
• Documentation: Look for clear installation and configuration instructions
• Issues and discussions: Review any reported problems or user feedback
• Source code: Plugins are open source, so you can review the code before installing

Installing Plugins

1. Download the plugin: Go to the plugin’s GitHub repository and download the .ndp file from the Releases page.

2. Place in plugins folder: Copy the .ndp file to your plugins directory:

   • Default location: <DataFolder>/plugins
   • Custom location: Set Plugins.Folder in your configuration

3. Rescan for plugins: Click the “Rescan” button in the Plugins section of the web UI, or if you have Plugins.AutoReload = true configured, the plugin will be detected automatically.

4. Enable the plugin: Go to the Navidrome web UI, navigate to the Plugins section in the admin area, and enable the plugin.

5. Configure the plugin: Some plugins require additional configuration. Check the plugin’s documentation for required settings.

Server Configuration

The following configuration options control the plugin system:

Example Configuration

[Plugins]
Enabled = true
Folder = "/path/to/plugins"    # Optional: custom plugins folder
AutoReload = true              # Useful during development/testing
LogLevel = "debug"             # Enable detailed plugin logging
CacheSize = "200MB"            # WASM compilation cache size

Or using environment variables (useful for Docker):

ND_PLUGINS_ENABLED=true
ND_PLUGINS_FOLDER=/data/plugins
ND_PLUGINS_AUTORELOAD=true
ND_PLUGINS_LOGLEVEL=debug

Managing Plugins in the Web UI

Once plugins are installed, you manage them through the Navidrome web interface:

Viewing Installed Plugins

Navigate to the Plugins section in the admin area to see all installed plugins. Each plugin shows its name, description, version, and current status.

Enabling and Disabling Plugins

Toggle individual plugins on or off. Disabled plugins remain installed but won’t run.

Configuring Plugin Settings

Many plugins have configurable options. Click on a plugin to view and modify its settings. The available options depend on what the plugin supports - check the plugin’s documentation for details on each setting.

User Access

Some plugins are user-scoped, meaning they operate on a per-user basis (like scrobblers). For these plugins, you need to configure which users have access:

• All users: Grant access to every user
• Specific users: Select individual users who can use the plugin

Library Access

Plugins that interact with your music library may need library access configured:

• All libraries: Grant access to all libraries
• Specific libraries: Select which libraries the plugin can access

Security

WebAssembly Sandbox

All plugins run inside a WebAssembly (WASM) sandbox provided by the Extism runtime. This means:

• Plugins cannot directly access your filesystem (except explicitly granted library paths)
• Network access is restricted to hosts declared in the plugin’s manifest
• Plugins are isolated from each other and from Navidrome’s internal systems

Permission System

Each plugin declares the permissions it needs in its manifest:

• HTTP access: Which external hosts the plugin can contact
• Storage: Whether the plugin can store persistent data
• Library access: Whether the plugin needs to read your music files
• User access: Whether the plugin operates on a per-user basis

Review these permissions before enabling a plugin to understand what it can access.

Network Access to Local Services

A plugin can only open HTTP and WebSocket connections to the hosts listed in its manifest. Starting with version 0.64.0, Navidrome checks the IP address when the connection opens, not only the host name. A host name in the manifest, like api.example.com, never allows a connection to a private, loopback or link-local address, even if that name resolves to one. This blocks a plugin from reaching your local network through DNS tricks or redirects.

To reach a service on your local network, the plugin manifest must list its IP address or a CIDR range, like 192.168.1.50 or 192.168.0.0/16, or allow all hosts with "*". Plugins that let you type the service address in their settings, like AudioMuse-AI, usually use "*".

If a plugin worked before 0.64.0 and now cannot reach a service on your network, ask its author to update the manifest.

Best Practices

• Only install plugins from trusted sources
• Review the plugin’s source code if you have concerns
• Start with plugins disabled and enable them one at a time
• Monitor your logs after enabling new plugins
• Keep plugins updated to get security fixes

Troubleshooting

Plugin Not Appearing

• Verify the .ndp file is in the correct plugins folder
• Check that Plugins.Enabled = true in your configuration
• Click the “Rescan” button in the Plugins section to detect new plugins
• Check logs for any errors during plugin discovery

Plugin Won’t Enable

• Check the Navidrome logs for error messages
• Verify all required permissions are configured (users, libraries)
• Ensure the plugin’s configuration requirements are met
• Try setting Plugins.LogLevel = "debug" for more detailed logs
• If the logs show HTTP request ... is not allowed, the plugin uses an HTTP call that Navidrome 0.64.0 removed. Update the plugin, or ask its author for a version built with the current plugin SDK

Configuration Issues

• Refer to the plugin’s documentation for required settings
• Check that configuration values match the expected format
• Look for validation errors in the logs

Checking Logs

Enable debug logging for plugins to troubleshoot issues:

[Plugins]
LogLevel = "debug" # or "trace" for more verbosity

Plugin-related log messages will contain plugin=<plugin-name> in them, making it easy to filter and identify issues.

4.2.7 - Jellyfin API (Experimental)

Starting with version 0.64.0, Navidrome can answer a subset of the Jellyfin API. Music apps built for Jellyfin can connect to Navidrome and play your library. You do not need a Jellyfin server.

Enabling the API

The Jellyfin API is off by default. Turn it on in your configuration file:

Jellyfin.Enabled = true

Or with an environment variable:

ND_JELLYFIN_ENABLED=true

Restart Navidrome. The API is now at the /jellyfin path of your server, for example http://192.168.1.10:4533/jellyfin. If you set a BaseURL, the path goes after it: https://example.com/music/jellyfin.

Connecting a client

We test the API with Finamp, Jellify and Feishin. Other Jellyfin music clients may work too.

1. In the client, add a new server.
2. Enter the server address with /jellyfin at the end, for example http://192.168.1.10:4533/jellyfin.
3. Log in with your Navidrome username and password.

Every client device that connects shows up as a player in Settings > Players. If you set a transcoding format on that player, Navidrome applies it to the Jellyfin streams too. Downloads always send the original file.

Finding the server on your network

Some clients can find Jellyfin servers on your local network, so you do not have to type the address. Navidrome can answer these searches. This is off by default, because a real Jellyfin server on the same machine uses the same port. Turn it on with:

Jellyfin.AutoDiscovery = true

Navidrome then listens on UDP port 7359. If another program already uses that port, Navidrome logs a warning and keeps running without discovery.

The client gets the address from your BaseURL, if it has a host. If not, Navidrome sends its own IP address and Port. If Navidrome listens only on one IP address (Address) and clients cannot reach that IP, set BaseURL to the address clients should use.

Docker

Clients find the server with a broadcast message. On Linux, Docker does not send broadcast messages to a container in the default (bridge) network mode, even if you publish port 7359. You must use host networking:

services:
  navidrome:
    image: deluan/navidrome:latest
    network_mode: host
    environment:
      ND_JELLYFIN_ENABLED: "true"
      ND_JELLYFIN_AUTODISCOVERY: "true"
    # ...keep your user, volumes and other settings

With the docker command line tool, use --network host.

With host networking, Docker ignores the ports section. Navidrome uses the ports of the host directly: 4533 for the web UI and API, and UDP 7359 for discovery. Navidrome also sees the real IP of the host, so you do not need to set BaseURL for discovery.

If you cannot use host networking, turn auto-discovery off and type the server address in the client.

Quick Connect

Quick Connect lets you log in a new device without typing your password on it. It is on by default.

1. In the client, choose Quick Connect. The client shows a 6-digit code.
2. In the Navidrome web UI, open the user menu (top right) and click Quick Connect. You can also use a Jellyfin client where you are already logged in.
3. Type the code. Navidrome shows the app and the device that asked for it. Check that you know them, then approve.
4. The client logs in with your user.

A code expires after 10 minutes, or when Navidrome restarts. Each code logs in one time only. Approving codes counts against the same login rate limit as a normal login.

To turn Quick Connect off:

Jellyfin.QuickConnect = false

Login screen user list

Some clients show a list of users on the login screen, so you tap a name and type only the password. Anyone who can reach your server can see this list without logging in. For that reason Navidrome shows no users by default. To show some, list their usernames:

Jellyfin.ExposedPublicUsers = "alice, bob"

Sessions

A Jellyfin login token does not expire, same as in Jellyfin. To log a user out of all their Jellyfin clients, change that user’s password. Login attempts count against the same login rate limit as the web UI.

What works

• Libraries. Each Navidrome library the user can access shows up as its own music library in the client.
• Browsing and search. Artists, albums, songs, genres and playlists. Clients can filter by year and record label.
• Favorites and ratings for songs, albums, artists and playlists.
• Playlists. Create, rename, reorder, add and remove tracks, change the cover, and delete. Only the owner can change a playlist.
• Streaming, with transcoding and ReplayGain.
• Lyrics, from the same sources as the web UI (see LyricsPriority).
• Playback reports. Plays count in Navidrome and scrobble to Last.fm, ListenBrainz and scrobbler plugins.
• Instant Mix from a song, album, playlist or genre.
• Sonic similarity. With a sonic similarity plugin such as AudioMuse-AI, clients get similar tracks and song-to-song paths. Navidrome also answers the AudioMuse-AI endpoints that some clients, like Symfonium, call when they connect as a Jellyfin client.

Configuration options

• Jellyfin.Enabled (ND_JELLYFIN_ENABLED, default false). Turns the Jellyfin API on.
• Jellyfin.ServerName (ND_JELLYFIN_SERVERNAME, default "Navidrome <version>"). The server name that clients show.
• Jellyfin.ExposedPublicUsers (ND_JELLYFIN_EXPOSEDPUBLICUSERS, default empty). Comma-separated usernames to show on the client login screen. See above.
• Jellyfin.AutoDiscovery (ND_JELLYFIN_AUTODISCOVERY, default false). Answers Jellyfin client searches on the local network (UDP port 7359). See above.
• Jellyfin.QuickConnect (ND_JELLYFIN_QUICKCONNECT, default true). Lets users log in new devices with a 6-digit code. See above.
• Jellyfin.MaxConcurrentStreams (ND_JELLYFIN_MAXCONCURRENTSTREAMS, default half the database connection pool, at least 2). How many large list responses Navidrome sends at the same time. Each one holds a database connection until it ends, and extra requests wait. The default leaves the other half of the connections for the scanner, scrobbles and the web UI. You rarely need to change it.

Known limitations

• The genre list shows genres from all libraries, not only the ones the user can access.
• While artwork loads, clients show a placeholder in one solid color, not a blurred copy of the cover.
• The client’s live connection only keeps the session open. Navidrome does not push events, like library changes, over it.

Troubleshooting

If a client fails on some screen, it may be calling an endpoint that Navidrome does not answer yet. Set LogLevel = "debug" and look for log lines with Jellyfin API: unhandled route. Each one shows the method and path the client asked for. Add those lines when you open an issue.

4.3 - Library Management

4.3.1 - Tagging Guidelines

Why Proper Tagging is Important

Navidrome organizes your music library entirely based on the metadata tags in your audio files. Unlike some music players, it does not use folder names or file names to group tracks (why?). This means that having clean and consistent tags is crucial for your music to display correctly. Proper tagging ensures that albums aren’t split up, artists are listed correctly, and you can easily browse or search for your music in Navidrome.

Good tagging practices not only make your music library more enjoyable to use, but also make it future-proof: If you ever switch to a different music player/server, or want to use a different music management tool, having well-tagged files will make the transition smoother.

Tagging Basics and Best Practices

Consistent and Complete Metadata

• Fill in essential tags for every song: At minimum, each music file should have the Title (song name), Artist, Album, Album Artist, and Track Number. Optionally include Genre, Year/Date and Disc Number (for multi-disc albums). Consistent use of these fields allows Navidrome to accurately group and identify your music.
• Be consistent with naming: Use the same spelling and punctuation for artist and album names across all tracks. For example, decide whether an artist is “AC/DC” or “ACDC”, “The Beatles” or “Beatles”, and stick to one. Consistent naming prevents duplicate entries for what is actually the same artist or album.
• Avoid unknown or blank tags: Make sure important fields aren’t left blank or set to generic values like “Unknown Artist”. Tracks with missing tags may be hard to find or get grouped incorrectly in Navidrome.

Key Metadata Fields and Usage

Each tag field has a specific purpose. Here are the important ones and how to use them:

• Title: The name of the song. (Example: “Imagine”)
• Artist: The performing artist(s) for the song. (Example: “John Lennon”) If a track has multiple artists, include all of them here (see Handling Multiple Artists below).
• Album: The name of the album the song belongs to. All tracks in the same album should have exactly the same Album tag.
• Album Artist: The primary artist for the album. This is usually the album’s main artist or group, or “Various Artists” for a compilation. Every track in an album should share the same Album Artist so Navidrome knows they belong to one album. For example, on a soundtrack or compilation album, set Album Artist to “Various Artists”. If a track has multiple album artists (like collaboration albums), include all of them here (see Handling Multiple Artists below).
• Track Number: The song’s track number on the album. This can be just the track number (like “5”) or a fraction like “5/12” to indicate track 5 of 12. Use leading zeros if your tag editor requires (e.g., “05”). Proper track numbers help Navidrome sort songs in the album’s order.
• Disc Number: If an album spans multiple discs, use this to differentiate disc 1, disc 2, etc. For example, “1/2” for Disc 1 of 2. Ensure all tracks that are on the same disc have the same disc number, and all tracks share the Album name. Navidrome will group multi-disc albums together and may show disc divisions.
• Year/Date: The date associated with the track. While not strictly required, it is useful information and many views or clients use it. All date fields accept YYYY, YYYY-MM, or YYYY-MM-DD. Navidrome recognizes several distinct date tags, each with its own meaning:
  • DATE: The recording date of the track (stored internally as recordingdate; ID3v2.4 TDRC).
  • YEAR: Treated as the release date (it is an alias of releasedate). Note that a plain YEAR tag maps to the release date, not the recording date.
  • RELEASEDATE: The release date of the album (same field as YEAR).
  • ORIGINALDATE/ORIGINALYEAR: The original release date of the album (stored internally as originaldate).
• Genre: The genre of the music (e.g., Rock, Jazz). This is a multi-valued field and can help when browsing or creating genre-based playlists.
• Compilation (Part of a Compilation): A special flag for various-artists albums. For a “Various Artists” compilation album, set this tag on all its tracks so Navidrome treats them as one album. In MP3/ID3 tagging, this is often labeled “Part of a Compilation” (technically the TCMP frame) which should be set to “1” (true). In FLAC/Vorbis tags, use a tag named COMPILATION with value “1”. Not all editors show this field explicitly, but many (like iTunes or Picard) will mark an album as a compilation for you if you specify it. If you can’t find this tag, simply ensuring Album Artist is “Various Artists” usually works, but using the compilation tag is a best practice.

File and Folder Naming (Optional but Helpful)

Navidrome ignores actual file names and folder structure when organizing music (it relies on tags), but a clear naming scheme is still recommended for your own sanity and compatibility with other tools:

• Use a folder structure like Artist/Album/ for your files, and file names like "01 - Song Title.mp3". For example: Music/Queen/A Night at the Opera/01 - Death on Two Legs.mp3. This isn’t required for Navidrome, but keeping your files organized logically makes management easier and reduces confusion.
• Keep naming conventions consistent. For instance, decide on a pattern for file names (Track - Title or Artist - Title, etc.) and apply it across your library. Similarly, maintain consistent folder naming (avoid having one folder called “Greatest Hits” and another called “GreatestHits” for example).
• If you use a tool like Picard or MediaMonkey, you can often configure it to rename and sort files into folders based on tags automatically. This can help enforce consistency after you’ve tagged everything.
• Remember, if you do rename or move files, Navidrome will update on the next scan (since it scans the library folder). Just make sure the tags inside the files are correct, because that’s still what Navidrome will use to display your music.

Album Art Handling

Including album cover art enhances the Navidrome experience. Here’s how to manage artwork:

• Embed cover art in audio files: Embedding the album cover in each music file’s tags is a reliable way to ensure Navidrome finds it. Most tagging tools allow you to add an image (JPEG/PNG) to the file’s metadata. Navidrome will display embedded cover art when browsing albums or playing songs.
• Use folder images: Additionally, save the album cover image as a file in the album’s folder (common names are cover.jpg, folder.jpg, or front.png). By default, Navidrome looks for images with those names. If it finds one, it will use it for the album cover. This is useful if you prefer not to embed large images in every file, or to provide artwork for players that look for folder images.
• Image quality: Use reasonably sized images. 500x500 to 1000x1000 pixels is usually plenty. Extremely large images (e.g., 3000x3000) will work, but keep in mind they take more space and can make the UI sluggish. Navidrome will cache thumbnails for performance, but it’s good practice not to go overboard.
• Consistency: Ensure all tracks of an album have the same album art. If you embed art, embed the same image in each track of that album (most tools can do this in batch). If you’re using a folder image, one image in the folder is enough for all songs in that album.
• Handling missing art: If you don’t have art for an album, Navidrome might try to fetch it from the internet (Last.fm or Apple Music) if enabled, but it’s best to supply your own for completeness and offline use. Taking the time to add cover art makes browsing much nicer.

Handling Multiple Artists and Collaborations

When tagging tracks with multiple artists or collaborators, it’s important to clearly and consistently represent each artist. Navidrome supports both singular (ARTIST and ALBUMARTIST) and plural (ARTISTS and ALBUMARTISTS) tags. However, multi-valued tags (ARTISTS and ALBUMARTISTS) are preferred, as they allow Navidrome to more accurately identify individual artists and improve library organization.

Recommended Approach: Multi-Valued Tags

• Preferred:
  • Use multiple ARTISTS tags to explicitly specify each artist individually.
  • Example (FLAC/Vorbis comments):

    ARTISTS=Alice
    ARTISTS=Bob
    

  • Navidrome clearly distinguishes each artist.
  • Facilitates better searching, sorting, and browsing.

Singular vs. Plural Tags

• Singular (ARTIST): Typically a single text entry (e.g., “Artist1 feat. Artist2”).

  • Navidrome will attempt to parse this field into multiple artists if one of the default separators is found: " / ", " feat. ", " feat ", " ft. ", " ft ", or "; ". Matching is case-insensitive (so " FEAT. " works too), and only applies to single-valued tags — multi-valued tags are never split.
  • However, relying on separators is less precise than multi-valued tags.

• Plural (ARTISTS): Explicitly multi-valued tag allowing multiple distinct entries.

  • Each artist can have individual associated metadata (like MusicBrainz IDs).
  • Preferred method, as it avoids ambiguity and parsing errors.

Navidrome treats the display name (the text shown in the UI) and the individual artists (the entries you can browse and click) as two separate things:

• If you have both singular and plural tags, Navidrome uses the singular one (ARTIST or ALBUMARTIST) only as the display name, and takes the individual artists from the plural tag (ARTISTS or ALBUMARTISTS). In this case the singular tag is not split — it is shown verbatim.
• If you provide only a plural tag (no singular one), the display name is built automatically by joining its values with " • " (e.g. Alice • Bob). This joiner is configurable via the Scanner.ArtistJoiner option.

This is why the ideal example below sets both: ARTIST controls how the name reads (Alice feat. Bob), while ARTISTS preserves Alice and Bob as distinct, individually-linkable artists.

Examples:

Ideal tagging (FLAC/Vorbis Comments example):

TITLE=Sunshine
ARTIST=Alice feat. Bob
ARTISTS=Alice
ARTISTS=Bob
ALBUM=Brighter Days
ALBUMARTIST=Alice
TRACKNUMBER=7

Less ideal (single-valued ARTIST):

TITLE=Sunshine
ARTIST=Alice feat. Bob
ALBUM=Brighter Days
ALBUMARTIST=Alice

In the ideal example, Navidrome clearly identifies each artist separately. In the less ideal example, Navidrome may split the artist names based on the default separators (like " feat. ", " / ", or "; "), but it’s less accurate. Note that the display name still shows the full ARTIST string (Alice feat. Bob); the split only affects the individual artists.

COMPOSER: Alice
COMPOSER: Bob

Multi-Valued Tags Support by Format

• Vorbis/FLAC, Opus: Multi-valued tags are fully supported and straightforward.
• ID3v2.4 (MP3): Supports true multi-valued tags, similar to Vorbis.
• ID3v2.3 (Older MP3 format): Does not officially support multiple artists. Instead, use a consistent separator (ex: "; ") if you must combine artists into one tag, though this approach is less ideal. Avoid using this format if possible and prefer the newer ID3v2.4
• Other tag formats (APE, MP4, WMA): Check your tag editor’s documentation for multi-valued tag support. Most modern tools can handle multi-valued tags in any format.

Best Practices:

• Always prefer multi-valued tags (ARTISTS and ALBUMARTISTS) when supported by your tagging software.
• If multi-valued tags are unavailable, use one of the default separators consistently (" / ", " feat. ", " ft. ", or "; ").
• Maintain consistency throughout your library to avoid duplicate or misidentified artist entries.
• Always verify how your tags appear in Navidrome and adjust tagging accordingly.

Proper use of multi-valued tags significantly enhances the accuracy and enjoyment of your music library in Navidrome.

Example: For a song “Sunshine” by Alice featuring Bob on the album Brighter Days (which is primarily Alice’s album):

• In a FLAC (Vorbis comments) file, the recommended tagging is:

  TITLE=Sunshine  
  ARTIST=Alice feat. Bob  
  ARTISTS=Alice  
  ARTISTS=Bob  
  ALBUM=Brighter Days  
  ALBUMARTIST=Alice  
  TRACKNUMBER=7  
  

• In an MP3 using the older ID3v2.3 format (which lacks multi-valued tags), the closest equivalent is:

  Title: Sunshine  
  Artist: Alice / Bob  
  Album: Brighter Days  
  Album Artist: Alice  
  Track: 7  
  

  In the FLAC example, ARTIST gives the display name (Alice feat. Bob) while the two ARTISTS fields preserve Alice and Bob as distinct, individually-linkable artists. In the ID3v2.3 example, the two names are combined in a single ARTIST field with a " / " separator; Navidrome will split them into Alice and Bob and show Alice / Bob as the display name. Both work, but the FLAC method is more explicit and accurate.

  Note: if you instead put two separate ARTIST values (Alice and Bob) with no ARTISTS tag, the display name becomes Alice • Bob — which is why the ARTIST + ARTISTS combination above is preferred.

Differences in Tag Formats (ID3, Vorbis, APE, etc.)

Different audio file formats use different tagging standards. You don’t need to know all the technical details, but it’s useful to understand the basics so you can tag consistently:

• MP3 (ID3 tags): MP3 files use ID3 tags (versions 2.3 and 2.4 are common). Most tagging tools default to ID3v2.3 for compatibility with older players. ID3v2.4 is a newer standard that supports features like multiple values in one field. Navidrome can read both. If available, use ID3v2.4 for better multi-artist and multi-genre support. Key ID3 tag frames include:
  • TIT2 (Title)
  • TPE1 (Artist)
  • TALB (Album)
  • TPE2 (Album Artist, in practice)
  • TRCK (Track number)
  • TPOS (Disc number, called “Part of a set”)
  • TYER/TDRC (Year/Date)
  • TCON (Genre)
  • TCMP (Compilation flag)
    You normally don’t need to remember these codes; tag editors handle them for you. Just be aware that some older software might not show an “Album Artist” field for MP3 because ID3v2.3 didn’t officially have it (those tools might be writing it as a custom tag or using TPE2).
• FLAC, Ogg Vorbis, Opus (Vorbis comments): These formats use Vorbis Comments for tags. Vorbis comments are simple “FIELD=Value” pairs and are very flexible. Common field names are in all caps by convention: e.g., TITLE, ARTIST, ALBUM, ALBUMARTIST, TRACKNUMBER, DISCNUMBER, DATE (year), GENRE. You can have multiple instances of a field to represent multiple values (e.g., two ARTIST lines). Vorbis comments don’t have fixed frames like ID3; you can even add non-standard fields (Picard, for example, can add a MUSICBRAINZ_ALBUMID tag for its own use). The main thing is to use standard field names so that Navidrome (and other players) know what to do with them. Navidrome will read these tags and support multi-valued fields natively.
• APE tags: APE is another tagging format, used primarily in Monkey’s Audio (.ape files) and sometimes WavPack or Musepack. APE tags also consist of key-value pairs (similar to Vorbis comments). Field names might be similar (often not all-caps; could be “Artist”, “Album”, etc.). If you’re dealing with APE files, just ensure your tag editor writes the standard fields. APE tags, like Vorbis, allow multiple entries of the same field name as well. One caveat: Some MP3 files might have APE tags attached (left over from old software or for ReplayGain data). It’s generally best to avoid having both ID3 and APE on the same MP3, as it can confuse some programs. If you encounter this, use your tag tool to remove or synchronize one of them (Navidrome reads ID3 by default for MP3).
• MP4/M4A (AAC files): These use the MP4 container’s metadata format (often called MP4 tags or atoms). You’ll see tag codes like ©ART (Artist), ©alb (Album), aART (Album Artist), trkn (track number), etc. Most tag editors (Picard, iTunes, etc.) let you edit these without worrying about the codes. Navidrome fully supports M4A/MP4 metadata, so just make sure to fill in the equivalent fields (including Album Artist and track numbers) and you’re set.
• WMA (Windows Media): Uses ASF tags. If you have WMA files, fill in the standard fields (Title, Artist, Album, Album Artist, Track number, Year, Genre) in your tag editor. Navidrome will read those as well.
• Other formats: Navidrome supports many formats (MP3, FLAC, Ogg, Opus, AAC, WMA, APE, etc.). The best practice is to use a good tagging tool which provides a unified interface for editing tags, regardless of the underlying format. The tool will handle mapping your input to the correct tag type for that file. As long as you fill out the tags consistently in the software, you don’t need to manually worry about the format differences — just be aware when switching formats that the same concept might have a different technical name under the hood.

Tagging Tools and Workflow

Because Navidrome is read-only with respect to your files’ metadata, you’ll need to use external tools to edit tags. Here are some recommendations and tips on workflow:

• Use a tag editor or music manager: Pick a tool that fits your comfort level. For beginners, a user-friendly tag editor with a GUI is ideal. Some popular options:
  • MusicBrainz Picard – Free, open source (Windows/Mac/Linux). Great for auto-tagging files by matching them to the huge MusicBrainz database. Picard can lookup albums by track info or acoustic fingerprint, fill in all tags (including Album Artist and album art), and even rename/move files based on a template. It’s a powerful tool that can greatly speed up tagging and ensure consistency.
  • Mp3tag – Free (Windows, with a Mac version available). Excellent for editing tags in bulk. You can manually edit multiple files, copy/paste tag fields, or use online database lookups. Mp3tag has a simple interface but lots of power under the hood.
  • beets – Free, command-line (cross-platform). Very powerful for auto-organizing and tagging using MusicBrainz data (or Discogs, using plugins), but it requires comfort with terminal commands. Great if you want automation and don’t mind writing a configuration file.
  • Other options: Kid3 (GUI, multi-platform), MusicBee (Windows, a player with strong tagging features), MediaMonkey (Windows), foobar2000 (Windows, has tagging capabilities), or even iTunes/Apple Music for editing tags of files. All of these can write tags that Navidrome will read.
• Workflow tips:

  1. Backup first: Before mass editing tags, especially with auto-tagging tools, back up your music files. Mistakes can happen, and you might not like the results of an automated tag rewrite.

  2. Work album by album (or artist by artist): Load a manageable chunk of files in your tag editor (for example, one album at a time). This ensures all tracks in an album get the same Album and Album Artist, etc., and it’s easier to spot and correct inconsistencies.

  3. Use online databases: Leverage tools like Picard to fetch tags and album art from databases. This can fill in missing info and standardize spelling (for instance, ensuring " feat. " is used consistently for “featuring”).

  4. Review and edit: Even with Picard or other auto-taggers, double-check the tags before saving. Make sure the album and artist names match your preferred format. Sometimes database entries have variations (like an album title including a subtitle or different punctuation).

  5. Save (write) tags: Apply the changes and save the tags to the files. If you’re renaming/moving files as part of this (many tools can do so based on tags), ensure the files end up in the correct location (your Navidrome music library folder).

     Caution: If you are retagging files that are already in Navidrome, avoid retagging and moving in one step, as this could cause Navidrome to lose track of the files. Instead, retag and save, rescan, then move the files and rescan again. See details here.

  6. Rescan in Navidrome: Navidrome usually auto-detects changes, but you can trigger a library rescan or restart the server to be sure. Once scanned, check in the Navidrome interface that everything appears as expected. You can check the tags of any file in Navidrome by looking at the “Get Info”->“Raw Tags” tab:

     

  7. Iterate as needed: If something looks wrong in Navidrome (e.g., an album is split into two entries, or is missing artwork), go back to your tag editor to fix those tags and then re-save and rescan. Common fixes include making Album Artist and Release Dates consistent, correcting typos or extra spaces, or adding missing compilation flags.

Picard specific tips

• In Picard’s settings, you can enable options to embed cover art and save a cover image file. Doing both is ideal (embed for portability, and cover.jpg for any software that looks for it). Picard also allows scripting for file naming — handy if you want to auto-organize your folders as mentioned.
• Because Navidrome matches artists based on their name, enable the “Use standardized artist names” option in Picard (Preferences -> Metadata). This helps ensure consistent naming (e.g., always using “Osees” instead of variations like “Thee Oh Sees”, “Oh Sees”, etc.).
• For a better integration with Navidrome, you can add the following scripts to your Picard configuration, to add extra tags that can help Navidrome organize your library:

  # Multiple artists
  $setmulti(albumartists,%_albumartists%)
  $setmulti(albumartistssort,%_albumartists_sort%)
  $setmulti(artistssort,%_artists_sort%)
  

  # Album Version
  $set(musicbrainz_albumcomment,%_releasecomment%)
  $if(%_recordingcomment%, $set(subtitle,%_recordingcomment%))
  

  # Release and Original dates
  $set(releasedate,%date%)
  $set(date,%_recording_firstreleasedate%)
  $set(originaldate,%originaldate%)
  $delete(originalyear)
  

Final Tips and Recap

• Consistency is key: Uniform tags result in a well-organized Navidrome library. If you notice duplicates or split albums, it’s almost always a tagging inconsistency — fix the tags and the issue will resolve.
• Leverage Album Artist and Compilation tags: These tags are your friends for ensuring albums stay together. Always set Album Artist (even if it’s the same as Artist for a solo album), and use “Various Artists” + the compilation flag for multi-artist albums.
• Keep tags tidy: Little details like extra spaces at the end of names or inconsistent capitalization can lead to multiple entries (e.g., “The Beatles” vs “The Beatles “). Try to keep things tidy. Many tag editors can batch-clean or case-correct tags.
• Continuous tagging: Make tagging part of your routine. When you add new music, tag it properly before (or immediately after) adding it to Navidrome. It’s easier to keep a library organized from the start than to fix a messy library later. Your future self will thank you!
• Use Navidrome’s strengths: Navidrome reads a lot of tags (including comments, lyrics, grouping, mood, etc.). If you want to enrich your library, consider adding lyrics or other info via your editor — Navidrome will display lyrics if present, for example, and has filters for various tags, like Genre, Grouping, Mood, Album Type, etc.
• Enjoy your music: A bit of effort in tagging goes a long way. Once everything is tagged well, Navidrome will present a beautiful, browsable collection. You’ll spend less time searching for songs or fixing metadata and more time listening. Happy tagging!

4.3.2 - Artwork location resolution

Artists

Fetching images for artists is controlled by the ArtistArtPriority config option. This is a comma-separated list of places to look for artist images. The default is artist.*, album/artist.*, external, meaning:

• First try to find an artist.* image in the artist folder(s)
• If not found, try to find an artist.* image in one of the album folders for this artist
• If not found, try to fetch it from an external service
• If not found, use the artist image placeholder (grey star image)

You can also configure a centralized folder for artist images using the ArtistImageFolder config option and adding image-folder to ArtistArtPriority. When configured, Navidrome will look for image files in that folder named after the artist’s MusicBrainz ID or name.

Albums

CoverArt fetching for albums is controlled by the CoverArtPriority config option. This is a comma-separated list of places to look for album art images. The default is cover.*, folder.*, front.*, embedded, external, meaning:

• First try to find a cover.*, folder.* or front.* image in the album folder(s)
• If not found, try to read an embedded image from one of the mediafiles for that album
• If not found, try to fetch it from an external service (currently only Last.fm)
• If not found, use the cover placeholder (blue record image)

Disc Cover Art

Multi-disc albums can have disc-specific artwork. Navidrome uses the DiscArtPriority config option to find disc-level images. The default is disc*.*, cd*.*, cover.*, folder.*, front.*, discsubtitle, embedded, meaning:

• First try to find a disc*.* or cd*.* image in the disc’s folder
• Then try cover.*, folder.*, or front.* in the disc’s folder
• The special keyword discsubtitle matches image files whose filenames equal the disc’s subtitle
• Try to read an embedded image from one of the mediafiles for that disc
• If no disc-specific image is found, fall back to the album-level artwork

Example directory layout for a multi-disc album:

Music/
└── Artist - Album/
    ├── disc1/
    │   ├── disc1.jpg        ← matched by disc*.*
    │   ├── 01 - Track.flac
    │   └── 02 - Track.flac
    ├── disc2/
    │   ├── cd2.png          ← matched by cd*.*
    │   ├── 01 - Track.flac
    │   └── 02 - Track.flac
    └── cover.jpg            ← album-level fallback

Forcing the Album Artwork for All Discs

If you prefer every disc in a multi-disc album to display the album cover (instead of any disc-specific image or the embedded image of a track), set DiscArtPriority to an empty string:

DiscArtPriority = ""

With no disc-level sources to try, Navidrome skips straight to the album-level artwork fallback, so all discs share the same cover as the album. This is useful when your library has inconsistent or unwanted disc-specific images (e.g. embedded art that differs from the album cover) and you want a uniform look across discs.

MediaFiles

Some players (including Navidrome’s own WebUI) can display different cover art images for each track in an album. Navidrome resolves mediafile artwork in the following order:

1. Try to read an embedded image from the mediafile itself
2. For multi-disc albums, fall back to the disc-level artwork (see Disc Cover Art above)
3. Fall back to the album cover art

MediaFile cover art can be slow in some systems and can be disabled by setting EnableMediaFileCoverArt=false.

Playlists

Playlist artwork is resolved in the following order:

1. Uploaded image: A custom image uploaded via the web UI (see Artwork Uploads below)
2. Sidecar image: An image file with the same base name as the playlist file, placed alongside it
3. M3U directive: An image URL specified via the #EXTALBUMARTURL directive inside the M3U file. To allow HTTP/HTTPS URLs, set EnableM3UExternalAlbumArt to true in your configuration. Local file paths are always accepted.
4. Tiled image: An auto-generated mosaic of up to 4 album covers from the playlist
5. If none of the above are available, the album cover placeholder is used

Example of a playlist with a sidecar image:

Playlists/
├── My Playlist.m3u
└── My Playlist.jpg          ← sidecar image

Artwork Uploads

Navidrome allows uploading custom images for playlists, artists, and internet radio directly from the web UI. This is controlled by the EnableArtworkUpload config option (enabled by default). When disabled, only admin users can upload artwork.

Supported formats: JPEG, PNG, WebP, GIF Maximum file size: 10 MB Storage location: Uploaded images are stored in <DataFolder>/artwork/, organized by entity type (artist/, playlist/, radio/)

Playlist Cover Art

To upload a custom playlist cover, open the playlist in the Navidrome web UI and hover the mouse over the current artwork. You should see a camera icon where you can click to select the image to upload. Uploaded images take priority over all other playlist artwork sources.

Artist Images

Custom artist images can be uploaded via the web UI on the artist detail page. Follow the same process as the playlist cover art.

Internet Radio Images

You can also upload a custom image on the internet radio’s edit page. This image will be used as the station’s artwork instead of fetching its favicon (when available).

Image Format & Quality

By default, Navidrome encodes resized artwork as JPEG (or PNG, for PNG sources and square thumbnails). You can opt into WebP encoding for smaller images by enabling the EnableWebPEncoding config option (default: false), at the cost of more CPU when resizing. Note that some older clients may not be able to display WebP images.

The CoverArtQuality config option controls the encoding quality for resized JPEG and WebP output (default: 75). It does not apply to PNG.

Animated GIFs embedded in or associated with your music files are preserved during resize. They are converted to animated WebP using ffmpeg.

Troubleshooting

When artwork is wrong or missing, the navidrome artwork CLI commands show what happened. artwork explain prints the priority chain recorded for one item. It shows which candidate won, why the others lost, and whether a file was missing or present but unreadable. artwork status shows the queue, how many items have no image, and whether artwork settings changed since the last full reprocess.

Navidrome doesn’t retry missing artwork by itself. Changing an artwork setting doesn’t update artwork that is already stored, either. navidrome artwork reprocess handles both. Use --source absent to retry missing artwork, or --all to apply a setting change. For a single album or artist, admins can use Refresh Metadata in its context menu.

4.3.3 - Missing Files

Overview

When using Navidrome, you may encounter missing tracks or albums in your library. When moving or renaming files, Navidrome may not be able to match the old versions of your files with the new ones when scanning your library. This can result in “ghost” (grayed out) tracks or albums in your library.

Only admins can see the missing tracks and albums in the library:

Missing files are not removed from the database on new scans to avoid inadvertently losing information like ratings, and play counts and references in playlists.

You can still get the missing tracks information, including path and when it went missing by clicking in the ? icon:

Note that this information is only available for admins.

Common Causes

The main reason this can happen is that the file paths in your music library have changed, and Navidrome was not able to match the new paths with the old ones. This can happen when you move or rename files AND change tags in the same operation.

To learn how Navidrome matches missing files and newly discovered ones, see the documentation on PIDs To avoid getting into this situation, it is recommended to move or rename files first, trigger a quick scan, and then update the tags.

Another common case is when you have a network drive that is not always available, or a removable drive that is not connected:

In these cases, Navidrome will mark the files as missing until the drive is available again.

Reconnecting a Missing File to its Replacement

If the scanner could not match an old file with its new path, you can remap the two by hand from the command line. This moves the play count, rating, starred status and bookmarks from the missing file onto the replacement, the same way the scanner does it automatically.

First list the missing files to get their paths:

navidrome missing list

Then remap a missing file onto the file that replaced it:

navidrome missing fix "Rock/Old Album/track01.mp3" "Rock/New Album/track01.mp3"

The replacement must already be scanned into the library. See missing in the CLI reference for the other argument forms and the JSON output option.

Automatically Purging Missing Files

Navidrome lets you control when missing files are automatically removed from the database using the Scanner.PurgeMissing option. This option accepts three possible values:

• "never" (default): Just mark files, albums, and artists as missing (they remain in the database, preserving ratings, play counts, and playlist references).
• "always": Purge any missing files, albums, and artists from the database after every scan.
• "full": Purge missing files, albums, and artists only after a full scan (not after quick/incremental scans).

To set this option, add to your config file:

Scanner.PurgeMissing = "always"

Or set the environment variable:

ND_SCANNER_PURGEMISSING=always

How to permanently delete Missing Files

If you are sure that the missing files are not coming back, you can permanently delete them from the database. Log in as an admin, click on the Settings meu, and click on the Missing Files option.

You will see a list of all missing files, with path, size and time they went missing. You will see options to export the list to a CSV file, or delete them from the database:

To delete permanently the files from the database, select the ones you want to remove and click on the Remove button.

4.3.4 - Exclude Content From Library

Overview

Navidrome allows the usage of a .ndignore file to exclude content from being added to Navidrome’s library. These files can be used in the following ways:

1. A blank .ndignore file can be added to a directory, and as a result Navidrome will ignore that folder and its subfolders from being added to Navidrome’s library.
2. A .ndignore file also supports .gitignore syntax inside of it to set rules for content to exclude. This allows you to place a single file in your parent Music folder and then use a single file to establish rules on ignoring certain folders, filetypes, or files.

Key behaviors

• Cascading: Patterns from parent directories apply to all subdirectories
• Multiple files: You can place .ndignore files in different directories

Syntax Usage and Examples

A single .ndignore can be placed at the parent folder of your library and then syntax added to it.

For example, if your ~/Music folder is mounted to Navidrome then you could create ~/Music/.ndignore and add syntax to it. The following examples assume the .ndignore is placed in the parent folder of your library:

# .ndignore supports comments starting with '#'

# Ignore all .flac
*.flac

# ignore specific folders
/untagged/
/unsorted/

# Negate the .flac ignore rule for a favorite album. 
!/thursday/taking-inventory-of-a-frozen-lake/*.flac

Limitations

• Brace expansion like *.{flac,mp3} don’t work – use separate lines instead

Technical Details

• The .ndignore syntax utilizes the go-gitignore library. See documentation for additional syntax usage.

4.4 - Integration

4.4.1 - External Integrations (A.K.A. Agents)

Navidrome uses external services (through agents) to enrich your music library with artist biographies, images, album covers, similar artists, and more. Multiple agents can be configured, and they are tried in priority order. If one fails or returns no results, the next one is tried.

How Agents Work

The Agents config option controls which agents are enabled and in what order. It accepts a comma-separated list of agent names.

The default is "deezer,lastfm,listenbrainz", meaning Deezer is tried first, then Last.fm, then ListenBrainz. A built-in local agent is always appended automatically as a final fallback.

To disable a specific agent, either remove it from the Agents list or set its individual *.Enabled option to false. To disable all external integrations at once, set EnableExternalServices to false.

Last.fm

Last.fm provides the broadest set of metadata among the built-in agents.

Provides: Artist biographies, artist images, similar artists, top songs, album covers, similar songs

Configuration: Requires API keys. Set the config options LastFM.ApiKey and LastFM.Secret. You can obtain these values by creating a free API account in Last.fm:

1. Go to https://www.last.fm/api/account/create and create an API account. Only the Application Name field is mandatory:

2. After submitting the form, you can get the API Key and Shared Secret from the Account Created page:

3. Copy the values above to your configuration file as LastFM.ApiKey and LastFM.Secret (or set them as environment variables ND_LASTFM_APIKEY and ND_LASTFM_SECRET)
4. After the configuration is done, you can set up scrobbling for your user.

Last.fm can be completely disabled by setting LastFM.Enabled to false.

Deezer

Deezer’s public API doesn’t require API keys or authentication, making it the simplest external integration.

Provides: Artist images, artist biographies, similar artists, top songs

Configuration: Enabled by default, no setup required. To disable it, set Deezer.Enabled to false in your configuration file or set the environment variable ND_DEEZER_ENABLED to false.

ListenBrainz

ListenBrainz provides metadata based on MusicBrainz data and community listening statistics. It works best when your music files have MusicBrainz IDs in their tags.

Provides: Artist URLs, similar artists, top songs, similar songs

Configuration: Enabled by default, no setup required for metadata. To disable it, set ListenBrainz.Enabled to false.

ListenBrainz also supports scrobbling, which requires per-user authorization.

Local Agent

The local agent is always active and serves as the final fallback. It provides top songs based on your own library’s play counts and ratings. No external service is contacted.

Extending with Plugins

Navidrome’s external metadata capabilities can be extended through plugins. Plugins can provide additional metadata agents for artist and album information and images, lyrics providers, and scrobblers. See the Plugins documentation for more information.

One example is AudioMuse-AI, which provides similar songs and artists based on sonic analysis of your own files, powering Instant Mix and similar-song features without relying on external metadata services.

4.4.2 - AudioMuse-AI

AudioMuse-AI is a self-hosted service that analyzes the actual audio content of your music library — tempo, timbre, energy, and other sonic characteristics — and uses that analysis to find songs that sound similar. Unlike the external metadata agents, which rely on third-party databases like Last.fm or Deezer, AudioMuse-AI works entirely from your own files, so it can find matches even for obscure or unreleased music.

It integrates with Navidrome through a plugin, the AudioMuse-AI-NV-plugin. Once set up, you get:

• Instant Mix in the Navidrome web UI: open any song’s context menu and build a queue of sonically similar tracks
• Similar songs and similar artists in Subsonic clients such as Symfonium, Feishin, Substreamer, Tempus, and Wavio, through the standard getSimilarSongs/getSimilarSongs2 (songs/radio) and getArtistInfo/getArtistInfo2 (related artists) endpoints
• The OpenSubsonic sonicSimilarity extension, which clients can use to fetch sonic matches and build song-to-song transitions

Requirements

• The latest versions of all three components, kept aligned: Navidrome, the AudioMuse-AI core, and the Navidrome plugin. A version mismatch is the most common cause of problems, so always update the three together.
• Docker and Docker Compose for AudioMuse-AI (or one of its native builds).
• Navidrome and AudioMuse-AI must be able to reach each other over the network.

Step 1 — Deploy AudioMuse-AI

AudioMuse-AI runs as a small stack: a web app, a worker, PostgreSQL, and Redis. The provided Docker Compose file wires all of this for you — normally you only set the database credentials and timezone in its .env file. Follow the deployment instructions in the AudioMuse-AI documentation. If you prefer not to use Docker, there are native builds for Linux, macOS, and Windows on their releases page.

Once the stack is running, open the AudioMuse-AI web interface (port 8000 by default). The Setup Wizard appears on first start:

1. Pick Navidrome as the media server and enter your Navidrome URL, user, and password.
2. In the AudioMuse-AI authentication section, set a username, password, and API token. You will need this token later to configure the plugin.
3. Save and finish the wizard.

Then run a first analysis before anything else: AudioMuse-AI can only find similar songs after it has analyzed them. Start a new analysis from its main page and let it finish — this can take a while on a large library. When it is done, confirm it works by using Similar Song on any track in the AudioMuse-AI UI.

Step 2 — Configure Navidrome

Make sure the plugin system is enabled (it is by default), and add audiomuseai to your Agents list. The order matters: Navidrome uses the first agent that supports sonic similarity, so keep audiomuseai first.

services:
  navidrome:
    image: deluan/navidrome:latest
    ports:
      - "4533:4533"
    environment:
      - ND_PLUGINS_ENABLED=true
      - ND_PLUGINS_AUTORELOAD=true
      - ND_AGENTS=audiomuseai,lastfm,deezer
    volumes:
      - ./data:/data
      - /path/to/music:/music:ro

Step 3 — Install the plugin

1. Download the latest audiomuseai.ndp file from the plugin releases page.
2. Copy it into your Navidrome plugins folder (<DataFolder>/plugins by default).
3. Restart Navidrome, or click “Rescan” in the Plugins section of the web UI (with Plugins.AutoReload enabled, the plugin is picked up automatically).

See Installing Plugins for details on the general installation flow.

Step 4 — Configure the plugin

In the Navidrome web UI, go to Settings > Plugins, enable the AudioMuse-AI plugin, and open its settings:

• API URL: the address where Navidrome can reach the AudioMuse-AI core app, for example http://192.168.1.50:8000. Use a host and port the Navidrome container can actually reach — not localhost, unless both run in the same network namespace.
• API token: the same token you set in the Setup Wizard in Step 1.