Documentation

• 1: Navidrome Overview
• 2: Installation
• 2.1: Windows Install
• 2.2: Installing with Docker
• 2.3: Linux Install
• 2.4: macOS Install
• 2.5: FreeBSD Install
• 2.6: Community Maintained Packages
• 2.7: Managed Hosting
• 2.8: Build from sources
• 3: Getting Started
• 3.1: Anonymous Data Collection
• 4: Usage
• 4.1: Navidrome Configuration Options
• 4.2: Tagging Guidelines
• 4.3: Using custom tags with Navidrome
• 4.4: Customizing Persistent IDs in Navidrome
• 4.5: Artwork location resolution
• 4.6: External Integrations
• 4.7: Sharing
• 4.8: How to Use Smart Playlists in Navidrome (Beta)
• 4.9: Missing Files
• 4.10: Monitoring Navidrome
• 4.11: Reverse proxy authentication
• 4.12: Jukebox mode
• 4.13: Security Considerations
• 4.14: Automated Backup
• 5: Developers
• 5.1: Development Environment
• 5.2: Creating New Themes
• 5.3: Translations
• 5.4: 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-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 17 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
• Reverse Proxy authentication*
• 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 Spotify (requires configuration)
• Album images and description from Last.fm
• Lyrics (currently only from embedded tags)
• Internet Radios
• Jukebox mode
• Shares (experimental support)

Apps

Besides its own Web UI, Navidrome should be compatible with all Subsonic clients. The following clients are tested and confirmed to work properly:

• Android
• iOS
• Web
• Desktop
• Other

For more options, look at the list of clients maintained by the Airsonic project.

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:

• Multiple libraries
• 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 # should be owner of volumes
    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

Customization

• The user argument should ideally reflect the UID:GID of the owner of the music library to avoid permission issues. For testing purpose you could omit this directive, but as a rule of thumb you should not run a production container as root.
• 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.
• 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.

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 dependancies 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 dependancies:

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.

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 navidrone 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 - macOS Install

Navidrome can be ran by simply double-clicking the binary that has been downloaded from the release page or by running it in the command line. However, that will keep a terminal window open while Navidrome is running.

To have Navidrome running in the background, we can run it as a service. We define a service as shown below and save that in a file named navidrome.plist in the ~/Library/LaunchAgents/ folder.

The example shown assumes a few things:

1. The binary has been downloaded and extracted to the /opt/navidrome folder.
2. A configuration file for Navidrome has been created and is named navidrome.toml in that folder. Be sure to set the DataFolder option as well.
3. A log file for Navidrome has been created and is named navidrome.log in that folder.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>Label</key>
        <string>navidrome</string>
        <key>ProgramArguments</key>
        <array>
            <string>/opt/navidrome/navidrome</string>
            <string>-c</string>
            <string>/opt/navidrome/navidrome.toml</string>
        </array>
        <key>RunAtLoad</key>
        <true/>
        <key>StandardOutPath</key>
        <string>/opt/navidrome/navidrome.log</string>
        <key>StandardErrorPath</key>
        <string>/opt/navidrome/navidrome.log</string>
    </dict>
</plist>

Then to load the service, run:

launchctl load ~/Library/LaunchAgents/navidrome.plist

To start the service, run:

launchctl start navidrome

You can verify that Navidrome has started by navigating to http://localhost:4533, by running launchctl list | grep navidrome or by checking the log file specified.

To stop the service, run:

launchctl stop navidrome

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

sudo xattr -d com.apple.quarantine /path/to/navidrome

2.5 - 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.6 - 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.7 - 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.

2.8 - 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.22+ and Node 20+. 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

You’ll also need to install the TagLib library:

• Debian/Ubuntu: sudo apt install libtag1-dev
• Arch Linux: pacman -S taglib
• macOS: brew install taglib
• FreeBSD: pkg install taglib
• For other platforms check their installation instructions

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

After installing Navidrome in your platform, you need to create your first user. This will be your admin user, a super user that can manage all aspects of Navidrome, including the ability to manage other users. Just browse to Navidrome’s homepage at http://localhost:4533 and you will be greeted with a screen like this:

Just fill out the username and password you want to use, confirm the password and click on the “Create Admin” button.

That’s it! You should now be able to browse and listen to all your music.

Note: It usually take a couple of minutes for your music to start appearing in Navidrome’s UI. You can check the logs to see what is the scan progress. If you see any errors, reach out and we can help you

Note: If you have any .m3u playlist in your music folder, they should be added as playlist in Navidrome automatically. However, Navidrome only does that when there is an admin user. On a fresh installation, it can happen that Navidrome already finished scanning your music folder before you created the first admin user. In that case, you need to make sure the “last modified” date of the m3u files is newer than the last scan. On Linux and macOS systems, this can be done with the touch command.

3.1 - Anonymous Data Collection

Overview

Navidrome includes an anonymous usage statistics feature designed to help improve the project for all users. This page explains what data is collected, how it is used, and how to opt out if you prefer not to participate.

Key Principles

• Anonymous Data Only: Navidrome collects only non-personal, anonymous data to guide future improvements.
• What’s Collected: See Collected Data.
• What’s NOT Collected: No emails, IP addresses, usernames, or other identifiable data. See Excluded Data.
• Opt-Out Available: Enabled by default, but you can disable it anytime.
• In-House Data Handling: Collected data goes to an open-source server hosted by the project—no third-party services.
• Full Transparency: Logs and UI indicators show when data is sent and what it contains.

What Will Be Collected?

Below is a plain-English explanation of what each field is generally intended to represent. Each field corresponds to a piece of information about the running application or its environment:

Top-level Fields

• InsightsID: A unique, randomly generated identifier for a given Navidrome instance. It’s a random ID that allows reports from the same instance to be grouped together. It is NOT directly connected to any of your data, and it cannot be used to directly identify you or your instance.

• Version: Shows which Navidrome version each report came from. In aggregate analysis, this tells you how many users are on a particular version and can highlight upgrade patterns.

• Uptime: The amount of time an instance has been running. When aggregated, this helps gauge the overall stability and average runtime before restarts across the community.

Build Information

Information about custom builds. Aggregated, this can reveal common build configurations used by the community, and if there are any issues (e.g. performance impact or high memory usage) specific to certain build configurations.

• Build.Settings: Key-value pairs representing the compile-time settings for Navidrome (build tags, compiler options, etc.).

• Build.GoVersion: The version of Go used to compile Navidrome.

OS Information

• OS.Type: Operating system type (e.g., “linux”, “windows”, “darwin”). When aggregated, this shows the distribution of OS usage.

• OS.Distro: OS distribution name for Linux-based systems (e.g., “ubuntu”, “debian”). Useful in aggregate form to see which Linux distributions are most common.

• OS.Version: The version of the operating system or distribution. Aggregating these versions helps track environment trends and legacy OS usage.

• OS.Containerized: Whether Navidrome is running in a containerized environment (Docker, Kubernetes, etc..)

• OS.Arch: CPU architecture (e.g., “amd64”, “arm”). This allows to understand how Navidrome is typically deployed (e.g., on Raspberry Pis vs. standard x86 servers).

• OS.NumCPU: The number of logical CPUs available. Aggregated, it helps form a picture of typical hardware profiles used across deployments.

Memory Information

Aggregated memory usage helps analyze typical resource consumption patterns and, together with other metrics, help identify causes for memory leaks.

• Mem.Alloc: Current memory allocated by the Go runtime (in bytes).

• Mem.TotalAlloc: Memory allocated over the lifetime of the application.

• Mem.Sys: Total memory requested from the underlying system.

• Mem.NumGC: Number of completed garbage collection runs. Collected in aggregate, this shows a high-level overview of how Navidrome manages memory across various deployments.

File System Information

Each FS-related field captures information about the directories or storage mediums used by Navidrome. Aggregating this data can help understand how frequently different types of storage are configured and where media content is commonly stored. This information is just the type of the filesystem (ex: nfs, ext4, ntfs…) used for each type of storage, not the actual path.

• FS.Music: File system type for storing music files.

• FS.Data: File system type storing Navidrome’s database.

• FS.Cache: File system type storing cached data.

• FS.Backup: The file system type for backups.

Each of these includes Type, describing the kind of storage (e.g., local disk, network mount). Aggregating them shows how widely different storage setups are used, and their impact on performance.

Library Information

These fields represent aggregate counts of media items and user data within each instance’s library. Across many deployments, they help illustrate general usage trends of the Navidrome library functionality.

• Library.Tracks: Total number of songs (tracks).

• Library.Albums: Total number of albums.

• Library.Artists: Count of distinct artists.

• Library.Playlists: Number of playlists.

• Library.Shares: Number of shares (public links).

• Library.Radios: The count of radio station entries or streaming sources.

• Library.ActiveUsers: Number of currently active users in the last 7 days. This helps understand the average load the server is operating under.

• Library.ActivePlayers: Number of currently active players in the last 7 days. This allows to understand what are the most used players.

Configuration Settings

These are various Navidrome configuration flags and settings. In aggregate, they help show which features are commonly enabled or how the service is typically set up across the community. These are mostly boolean flags or simple settings, NO identifiable data is collected (paths, ids, tokens, etc..). For a reference of what each one represents, take a look at the configuration options page in the documentation.

• Config.LogLevel
• Config.LogFileConfigured
• Config.TLSConfigured
• Config.ScanSchedule
• Config.TranscodingCacheSize
• Config.ImageCacheSize
• Config.EnableArtworkPrecache
• Config.EnableDownloads
• Config.EnableSharing
• Config.EnableStarRating
• Config.EnableLastFM
• Config.EnableListenBrainz
• Config.EnableSpotify
• Config.EnableMediaFileCoverArt
• Config.EnableJukebox
• Config.EnablePrometheus
• Config.SessionTimeout
• Config.SearchFullString
• Config.RecentlyAddedByModTime
• Config.PreferSortTags
• Config.BackupSchedule
• Config.BackupCount
• Config.DefaultBackgroundURL
• Config.DevActivityPanel
• Config.EnableCoverAnimation

In Summary:
When gathered from many Navidrome instances, these metrics and settings are invaluable in understanding the aggregate patterns of usage, deployment environments, media collections, and configuration preferences. This aggregated data is not intended for diagnosing single-instance issues; rather, it provides a high-level view of how Navidrome is deployed and used by its community overall.

Here’s a sample of the data sent: https://gist.github.com/deluan/1c8944fb92329c1658d96bb72a8e8db4

Data Retention

• Sent daily
• Retained for 30 days, then permanently deleted.

What Will NOT Be Collected?

To protect your privacy, the following will not be collected:

• No Personal Information: No emails, usernames, or anything identifiable.
• No Network Information: No IP addresses or device fingerprints.
• No Detailed Playback History: Individual song plays are not tied to specific users.
• No Library Details: Song/artist/album/playlist names are excluded.
• No Sensitive Configuration Data: Passwords, tokens, or logs with personal info are never collected.

Why Collect This Data?

Collecting anonymous usage statistics helps:

• Identify popular platforms and configurations.
• Prioritize features and fixes based on usage patterns.
• Ensure updates don’t unintentionally disrupt the majority of users.

Privacy and Transparency

Transparency Measures

1. Human-Readable Documentation: This page explains all details in a clear, accessible way.
2. Log Transparency: Each data submission logs:
   • The exact payload sent.
   • The destination URL. Example:

   Sent Insights data (for details see http://navidrome.org/docs/getting-started/insights  data="{\"id\":\"4c457065-101a-435a-b158-244b573579cd\",\"version\":\"0.53.3-SNAPSHOT (7f47e0a53)\",\"uptime\":0,\"build\":{\"settings\":{\"-buildmode\":\"exe\",\"-compiler\":\"gc\",\"-ldflags\":\"-extldflags '-static -latomic' -w -s         -X github.com/navidrome/navidrome/consts.gitSha=7f47e0a53         -X github.com/navidrome/navidrome/consts.gitTag=v0.53.3-SNAPSHOT\",\"-tags\":\"netgo\",\"CGO_ENABLED\":\"1\",\"GOAMD64\":\"v1\",\"GOARCH\":\"amd64\",\"GOOS\":\"linux\",\"vcs\":\"git\",\"vcs.modified\":\"true\",\"vcs.revision\":\"7f47e0a5373d1ea067de8929c828ee0cd85a0795\",\"vcs.time\":\"2024-12-15T02:01:46Z\"},\"goVersion\":\"go1.23.4\"},\"os\":{\"type\":\"linux\",\"distro\":\"qts\",\"version\":\"5.2.2\",\"arch\":\"amd64\",\"numCPU\":4},\"mem\":{\"alloc\":2750544,\"totalAlloc\":9076584,\"sys\":14243080,\"numGC\":4},\"fs\":{\"music\":{\"type\":\"ext2/ext3/ext4\"},\"data\":{\"type\":\"ext2/ext3/ext4\"},\"cache\":{\"type\":\"ext2/ext3/ext4\"},\"backup\":{\"type\":\"ext2/ext3/ext4\"}},\"library\":{\"tracks\":85200,\"albums\":6255,\"artists\":1319,\"playlists\":26,\"shares\":19,\"radios\":7,\"activeUsers\":1},\"config\":{\"logLevel\":\"debug\",\"transcodingCacheSize\":\"100GB\",\"imageCacheSize\":\"50GB\",\"enableArtworkPrecache\":true,\"enableDownloads\":true,\"enableSharing\":true,\"enableStarRating\":true,\"enableLastFM\":true,\"enableListenBrainz\":true,\"enableMediaFileCoverArt\":true,\"enableSpotify\":true,\"enableCoverAnimation\":true,\"sessionTimeout\":\"168h0m0s\",\"recentlyAddedByModTime\":true,\"backupSchedule\":\"5 4 * * *\",\"backupCount\":5,\"devActivityPanel\":true,\"defaultBackgroundURL\":true}}" server="https://insights.navidrome.org/collect" status="200 OK"
   

3. UI Indicator: You will be able to see the last submission date/time in the About dialog:

   

How to Opt-Out

Data collection is enabled by default, but you can disable it anytime, by setting the new config option EnableInsightsCollector (or ND_ENABLEINSIGHTSCOLLECTOR env var) to false. If you have EnableExternalServices set to false, it will also disable the insights collection.

Detailed instructions will be provided in the release notes.

Data Collection Server

The data collection server is open-source and hosted by the Navidrome project, ensuring secure, in-house handling. Check it out: Navidrome Insights Server.

Thank You for Your Support

By allowing anonymous usage statistics, you’re contributing to the future of Navidrome. Your trust is invaluable, and if you’re uncomfortable, you can always opt out—no questions asked.

For questions or concerns, feel free to reach out via:

• Discord
• GitHub Discussions
• Reddit

Thank you for being part of the Navidrome community!

Deluan
Navidrome Developer

4 - Usage

4.1 - Navidrome Configuration Options

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

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:
• Windows
• macOS
• Unix-based systems

# 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'

# 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'

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:
• Windows
• macOs
• Unix-based systems

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

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

$ navidrome --configfile "/home/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:
• Windows
• macOs
• Unix-based systems

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

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

$ navidrome --musicfolder "/mnt/music"

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

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.2 - 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 year (or full date) of the album’s recording. While not strictly required, the year is useful information and some views or clients might use it. Formats accepted are: YYYY (for YEAR and DATE) and YYYY-MM-DD or YYYY-MM (for DATE). For a more precise date information, you can leverage other Date fields:
  • DATE/YEAR: The date of the track recording.
  • ORIGINALDATE/ORIGINALYEAR: The original release date of the album.
  • RELEASEDATE/RELEASEYEAR: The release date of the album.
• 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 Spotify) 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 common separators (e.g., " / ", " feat. ", "; ") are used.
  • 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.

Note that if you have both singular and plural tags, Navidrome will use the singular one (ARTIST or ALBUMARTIST) as a “Display Name” for the artist (or album artist)

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 common separators (like " feat. ", " / ", or "; "), but it’s less accurate.

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 consistent separators (" feat. ", " / ", 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, you might have tags:

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

• In an MP3 with ID3v2.3, the tags could be:

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

  In the FLAC example, there are two separate ARTIST fields (one for Alice, one for Bob). In the MP3 example, the two artist names are combined in one field with a " / " separator. Both will display correctly in Navidrome, but the FLAC method more explicitly preserves the two distinct artist entries.

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.
• 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 - 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 (e.g., feat., ft., /, etc.) to identify multiple artists. To customize the separators used for artist splitting, you can configure the Tags.Artist.Split option:

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

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.4 - 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.5 - 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 (currently only Spotify)
• If not found, use the artist image placeholder (grey star image)

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)

MediaFiles

Some players (including Navidrome’s own WebUI), can display different cover art images for each track in an album. Navidrome tries to read an embedded image from the mediafile. If it does not have one, it will get the album cover art as explained above. MediaFile cover art can be slow in some systems and can be disabled by setting EnableMediaFileCoverArt=false.

Playlists

Currently, Playlists CoverArt images are generated tiled images, containing up to 4 covers from the albums in the playlist. If for any reason it cannot be generated, it will use the album cover placeholder (blue record image). This is currently only available in the Subsonic API.

4.6 - External Integrations

Last.fm

Navidrome can use Last.fm to retrieve artists biographies, top songs, similar artists and album covers. It can also send your scrobbles to Last.fm. For these features to work, you’ll need to 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)

Spotify

Artist images can be retrieved from Spotify. You’ll need to set the config options Spotify.ID and Spotify.Secret. To obtain these values, create a free account in Spotify, then follow these steps:

1. Click on the “Create app” button in Spotify’s Developer dashboard: https://developer.spotify.com/dashboard/applications:

2. Fill the name and description fields, fill the “Redirect URI” field with http://localhost/ and click on the “Save” button:

3. Go to “Settings”:

4. Click “View client secret”:

5. Copy the values of ID and secret to your configuration file as Spotify.ID and Spotify.Secret (or set them as environment variables ND_SPOTIFY_ID and ND_SPOTIFY_SECRET):

4.7 - 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 the Sharing Feature

The Sharing feature is disabled by default. To enable it, you need to adjust your Navidrome configuration. In your configuration file, set EnableSharing=true, or set the environment variable ND_ENABLESHARING=true.

Once the Sharing feature is enabled, all users will have access to all existing shares. This includes the ability to change the description and expiration date of the shares, as well as the capability to create new shares.

Please note that at this time, there is no way to set specific sharing permissions per user. This means that once the Sharing feature is enabled, all users have equal access and capabilities related to sharing. This includes the ability to view, modify, and create shares.

Due to this, we advise you to enable this feature only if you are comfortable with these permissions. Future updates may include more granular permission controls for sharing.

Using the Sharing Feature

Once the Sharing feature is enabled, all users will be able to access current shares, modify descriptions and expiration, and create new ones. However, as of the initial implementation, there is currently no way to set permissions per user. 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.8 - 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
}

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’. This is crucial if you want to use it in another .nsp file (with inPlaylist and notInPlaylist).
• 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.

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 by ID (using the operator inPlaylist), ensure that the referenced playlist is not another Smart Playlist unless it is set to ‘public’. This ensures proper functionality.

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

Currently, sorting by multiple fields is not supported.

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 } }.
• 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).

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.

To get a playlist’s ID to be used in inPlaylist and notInPlaylist, 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:

4.9 - 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.

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.10 - Monitoring Navidrome

Currently, Navidrome supports monitoring and alerting using Prometheus/OpenMetrics standard. Example Grafana dashboard:

Overview

Prometheus is a service that takes data from a metrics endpoint and collects it. Grafana is a dashboard service that can take data from a Prometheus server and display it. Navidrome has an easy way to create a metrics endpoint that Prometheus can use. Once you point Prometheus to this endpoint, and Grafana to your Prometheus server, you will be able to monitor your Navidrome instance.

The easiest way to do this is using docker-compose and Docker networks.

Configuration

You need to set ND_PROMETHEUS_ENABLED to enable Prometheus metrics endpoint. Setting custom ND_PROMETHEUS_METRICSPATH is highly recommended if your Navidrome instance is publicly available.

Minimal docker compose example file with metrics enabled, and Prometheus and Grafana containers:

version: '3'
services:
  navidrome:
    image: deluan/navidrome
    user: 1000:1000 # should be owner of volumes
    ports:
      - "4533:4533"
    environment:
      ND_PROMETHEUS_ENABLED: "true"
      ND_PROMETHEUS_METRICSPATH: "/metrics_SOME_SECRET_KEY"
    volumes:
      - "./data:/data"
      - "./music:/music"
    networks:
      - metrics-network
  prometheus:
    image: prom/prometheus
    container_name: prometheus
    command:
      - '--config.file=/prometheus/prometheus.yml'
    ports:
      - 9090:9090
    restart: unless-stopped
    volumes:
      - ./etc/prometheus:/etc/prometheus
      - ./prometheus:/prometheus
    networks:
      - metrics-network
  grafana:
    image: grafana/grafana
    container_name: grafana
    ports:
      - 3000:3000
    restart: unless-stopped
    environment:
      - GF_SERVER_ROOT_URL=<your external grafana endpoint here>
      - GF_SERVER_SERVE_FROM_SUB_PATH=false # if your external grafana endpoint has a subpath or not
    volumes:
      - ./etc/grafana:/etc/grafana/provisioning/datasources
    networks:
      - metrics-network
networks:
  metrics-network:
    driver: bridge

Example prometheus.yml config to parse this instance:

global:
  scrape_interval: 10s
scrape_configs:
  - job_name: 'navidrome'
    metrics_path: /metrics_SOME_SECRET_KEY
    scheme: http
    static_configs:
      - targets: ['navidrome:4533']

Dashboard

Grafana dashboard available here: #18038.

Simple to install but fully fledged Grafana docker compose configuration can be found here.

4.11 - Reverse proxy authentication

Configuration

By default, reverse proxy authentication is disabled. To enable the feature, configure a trusted reverse proxy with the ReverseProxyWhitelist option. This option takes a comma-separated list of either:

• An IPv4 or IPv6 range in CIDR notation.
• An @ (at sign) when listening on a UNIX socket (see the Address option).

When enabled via the ReverseProxyWhitelist option, Navidrome validates the requests’ source IP address against the ranges configured in ReverseProxyWhitelist. If no range matches the address, reverse proxy authentication is not used even if the reverse proxy user header is present (see below), and falls back to a standard authentication mechanism. For requests received through a UNIX socket, IPs can’t be validated and Navidrome will use the reverse proxy user header if and only if ReverseProxyWhitelist contains @.

With reverse proxy authentication enabled, Navidrome gets the username of the authenticated user from incoming requests’ Remote-User HTTP header. The header can be changed via the ReverseProxyUserHeader configuration option.

If a user is successfully authenticated by the proxy but does not exist in the Navidrome DB, it will be created with a random password. The first user created in a fresh installation (whether through reverse proxy authentication or direct login) will always be an admin user.

You might also be interested in the EnableUserEditing option, which allows disabling the User page that lets users change their Navidrome password.

Sharing endpoint

If you plan to use the Sharing feature, where you can create unauthenticated links to parts of your library, you’ll need to whitelist the /share/* URLs.

Subsonic endpoint

The subsonic endpoint also supports reverse proxy authentication, and will ignore the subsonic authentication parameters (u, p, t and s) if the reverse proxy user header is present. If the header is absent or has an empty value, Navidrome will fall back to the standard subsonic authentication scheme.

If your reverse proxy does not support the standard subsonic authentication scheme, or if the subsonic clients you want to use don’t support an alternate authentication mechanism also supported by your proxy (such as BasicAuth), you can still configure your proxy to bypass authentication on /rest/* URLs and let Navidrome perform authentication for those requests. In that case, your users will have to update their (initially random) password in Navidrome, to use it with their subsonic client.

Navidrome Web App

The Navidrome web app uses a mix of internal and subsonic APIs, and receives subsonic credentials from the server to use for requests against the subsonic API. As the credentials received from the server likely won’t match those in your dedicated authentication service, you need to handle subsonic requests from the Navidrome web app (identified as the subsonic client NavidromeUI via the c query parameter) in a special way. You can either:

• Ignore the subsonic authentication parameters and authenticate those requests the same way as non-subsonic requests. This relies on the fact that requests to the subsonic API will look the same to the proxy as requests to the internal API (e.g. same session cookies).
• Bypass authentication on your proxy for those requests and let Navidrome handle it. This relies on the fact that the web app receives the subsonic credentials from the server when it loads, and it can load only if the proxy has already authenticated the user.

Note that if you don’t intend to support third-party subsonic clients, you can simply place the subsonic endpoint behind the same protection rule as the rest of the application, i.e. you don’t need any special handling to bypass authentication.

Security

Make sure to check the reverse proxy authentication section in the dedicated Security Considerations page.

Examples

For the examples below, it is assumed that you are familiar with the various products in use, i.e. reverse proxy, authentication service but also Navidrome.

The examples focus on the integration between the products, and provide configuration snippets stripped down to the relevant parts, which you can adapt to the specifics of your deployment.

Caddy with forward_auth

In this example, Navidrome is behind the Caddy reverse proxy, and Authentik is used to authenticate requests, with the help of Caddy’s forward_auth middleware.

Caddyfile excerpt stripped down to the relevant parts:

example.com

reverse_proxy /outpost.goauthentik.io/* http://authentik:9000

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

# Authentik uses the Authorization header if present, so should be able to
# authenticate subsonic clients that support BasicAuth. Requests from the
# Navidrome Web App will be authenticated via the existing session cookie.
# If you want to have Navidrome authenticate subsonic requests, remove this
# forward_auth block.
@subsonic path /rest/*
forward_auth @subsonic http://authentik:9000 {
  uri /outpost.goauthentik.io/auth/caddy
  copy_headers X-Authentik-Username>Remote-User

  # Some clients that claim to support basicauth still expect a subsonic
  # response in case of authentication failure instead of a proper basicauth
  # response.
  @error status 1xx 3xx 4xx 5xx
  handle_response @error {
    respond <<SUBSONICERR
      <subsonic-response xmlns="http://subsonic.org/restapi" status="failed" version="1.16.1" type="proxy-auth" serverVersion="n/a" openSubsonic="true">
        <error code="40" message="Invalid credentials or unsupported client"></error>
      </subsonic-response>
      SUBSONICERR 200
  }
}

reverse_proxy navidrome:4533

Note that if you want to whitelist the unprotected paths as part of your Authentik configuration instead of doing it in Caddy, the copy_headers subdirective won’t work as expected: Authentik won’t set the X-Authentik-Username header for whitelisted paths, but Caddy will still copy the header with an incorrect value. In order to make it work, you need a workaround:

forward_auth http://authentik:9000 {
  uri /outpost.goauthentik.io/auth/caddy
  # copy_headers subdirective removed
}

# Only set the Remote-User header if the request was actually authentified (user
# header set by Authentik), as opposed to whitelisted (user header not set).
@hasUsername `{http.reverse_proxy.header.X-Authentik-Username} != null`
request_header @hasUsername Remote-User {http.reverse_proxy.header.X-Authentik-Username}

Traefik with ForwardAuth

In this example, Navidrome is behind the Traefik reverse proxy, and Authelia is used to authenticate requests, with the help of Traefik’s ForwardAuth middleware. Each service has its own subdomain. Docker Compose is used to deploy the whole thing.

The error response rewriting for subsonic authentication failure is not implemented, which means that subsonic clients are expected to handle correctly BasicAuth error responses (HTTP 401 with WWW-Authenticate header).

docker-compose.yml excerpt stripped down to the relevant parts:

services:
  authelia:
    image: authelia/authelia:4.38.8
    labels:
      # The login page and user dashboard need to be reachable from the web
      traefik.http.routers.authelia.rule: Host(`auth.example.com`)
      traefik.http.routers.authelia.entrypoints: https
      # Standard authentication middleware to be used by web services
      traefik.http.middlewares.authelia.forwardauth.address: http://authelia:9091/api/verify?rd=https://auth.example.com/
      traefik.http.middlewares.authelia.forwardauth.authResponseHeaders: Remote-User
      # Basicauth middleware for subsonic clients
      traefik.http.middlewares.authelia-basicauth.forwardauth.address: http://authelia:9091/api/verify?auth=basic
      traefik.http.middlewares.authelia-basicauth.forwardauth.authResponseHeaders: Remote-User

  navidrome:
    image: deluan/navidrome:0.52.0
    labels:
      # Default rule which uses Authelia's web-based authentication. If you enable
      # navidrome's Sharing feature, you can configure Authelia to bypass
      # authentication for /share/* URLs, so you don't need an extra rule here.
      traefik.http.routers.navidrome.rule: Host(`music.example.com`)
      traefik.http.routers.navidrome.entrypoints: https
      traefik.http.routers.navidrome.middlewares: authelia@docker
      # Requests to the subsonic endpoint use the basicauth middleware, unless
      # they come from the Navidrome Web App ("NavidromeUI" subsonic client), in
      # which case the default authelia middleware is used.
      traefik.http.routers.navidrome-subsonic.rule: Host(`music.example.com`) && PathPrefix(`/rest/`) && !Query(`c`, `NavidromeUI`)
      traefik.http.routers.navidrome-subsonic.entrypoints: https
      traefik.http.routers.navidrome-subsonic.middlewares: authelia-basicauth@docker
    environment:
      # Navidrome does not resolve hostnames in this option, and by default
      # traefik will get assigned an IP address dynamically, so all IPs must be
      # trusted.
      # This means that any other service in the same docker network can make
      # requests to navidrome, and easily impersonate an admin.
      # If you assign a static IP to your traefik service, configure it here.
      ND_REVERSEPROXYWHITELIST: 0.0.0.0/0
      # Since authentication is entirely handled by Authelia, users don't need to
      # manage their password in Navidrome anymore.
      ND_ENABLEUSEREDITING: false

If you want to add support for the subsonic authentication scheme in order to support all subsonic clients, you can have a look at the Traefik plugin BasicAuth adapter for Subsonic which transforms subsonic authentication parameters into a BasicAuth header that Authelia can handle, and performs the error response rewriting.

4.12 - 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 playback server” 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.13 - Security Considerations

Permissions

You should NOT run Navidrome as root. Ideally you should have it running under its own user. Navidrome only needs read-only access to the Music Folder, and read-write permissions to the Data Folder.

Encrypted passwords

To be able to keep compatibility with the Subsonic API and its clients, Navidrome needs to store user’s passwords in its database. By default, Navidrome encrypts the passwords in the DB with a shared encryption key, just for the sake of obfuscation as this key can be easily found in the codebase.

This key can be overridden by the config option PasswordEncryptionKey. Once this option is set and Navidrome is restarted, it will re-encrypt all passwords with this new key. This is a one-time only configuration, and after this point the config option cannot be changed anymore or else users won’t be able to authenticate.

Network configuration

Even though Navidrome comes with an embedded, full-featured HTTP server, you should seriously consider running it behind a reverse proxy (Ex: Caddy, Nginx, Traefik, Apache) for added security, including setting up SSL. There are tons of good resources on the web on how to properly setup a reverse proxy.

When using Navidrome in such configuration, you may want to prevent Navidrome from listening to all IPs configured in your computer, and only listen to localhost. This can be achieved by setting the Address flag to localhost.

Reverse proxy authentication

When reverse proxy authentication is enabled, Navidrome trusts the reverse proxy user header (configured with the ReverseProxyUserHeader option, by default Remote-User).

In principle, the reverse proxy user header is ignored if requests don’t come from a reverse proxy trusted with the ReverseProxyWhitelist option. This check can however be fooled by requests with a forged source IP address if the reverse proxy can be bypassed (e.g. sent by a compromised service running next to Navidrome).

When using reverse proxy authentication in a fresh installation, the first user created through this method will automatically be granted admin privileges, consistent with the behavior when creating the first user through the web interface.

Listening on a UNIX socket

If you are listening on a UNIX socket (Address option) and enable reverse proxy authentication (ReverseProxyWhitelist configured with the special value @), any process able to write to the socket can forge authenticated requests.

Make sure to properly protect the socket with user access controls (see the UnixSocketPerm option).

Reverse proxy with a dynamic IP address

Navidrome does not support resolving hostnames in the ReverseProxyWhitelist configuration option.

In scenarios where the reverse proxy has a dynamic IP address, for example when you use docker, you might consider using 0.0.0.0/0 to allow requests from the reverse proxy. This essentially disables the check, so you have to make sure that only the reverse proxy can send requests to Navidrome.

In particular with docker and docker-compose, without extra configuration containers are usually placed on the same default network and can therefore freely communicate.

Potential HPP vulnerability

When reverse proxy authentication is enabled, Navidrome currently does not disable the other authentication methods. This could potentially create an HTTP Parameter Pollution vulnerability if the reverse proxy is misconfigured, or due to a bug or oversight in Navidrome.

You should make sure that the reverse proxy user header is always set for requests against protected endpoints. As a rule of thumb, for a reverse proxy authentication setup, the only endpoints that are not protected are /rest/* (depending on whether your proxy can handle the subsonic authentication scheme) and /share/*.

Transcoding configuration

To configure transcoding, Navidrome’s WebUI provide a screen that allows you to edit existing transcoding configurations and to add new ones. That is similar to other music servers available in the market that provide transcoding on-demand.

The issue with this is that it potentially allows an attacker to run any command in your server. This married with the fact that some Navidrome installations don’t use SSL and/or run it as a super-user (root or Administrator), is a recipe for disaster!

In an effort to make Navidrome as secure as possible, we decided to disable the transcoding configuration editing in the UI by default. If you need to edit it (add or change a configuration), start Navidrome with the ND_ENABLETRANSCODINGCONFIG set to true. After doing your changes, don’t forget to remove this option or set it to false.

Limit login attempts

To protect against brute-force attacks, Navidrome is configured by default with a login rate limiter, It uses a Sliding Window algorithm to block too many consecutive login attempts. It is enabled by default and you don’t need to do anything. The rate limiter can be fine tuned using the flags AuthRequestLimit and AuthWindowLength and can be disabled by setting AuthRequestLimit to 0, though it is not recommended.

4.14 - Automated Backup

Navidrome version 0.54.x introduces a backup feature that allows the music server’s data to get periodically exported. This guide will walk you through configuring backups using both a configuration file and environment variables, where to locate the backups, and how to restore from a backup.

Configuring Backup with config.toml

To configure backups using the navidrome.toml file, insert the following lines to set up backups:

[Backup]
Path = "/path/to/backup/folder"
Count = 7
Schedule =  "0 0 * * *"

• Backup.Path: The directory where backups will be stored. Replace “/path/to/backup/folder” with the desired path.
• Backup.Count: The number of backup files to keep.
• Backup.Schedule: cron-like syntax to define how often backups occur. The example above schedules a backup every 24 hours at midnight.

Configuring Backup with Environment Variables

Alternatively, you can configure backups using environment variables ND_BACKUP_PATH, ND_BACKUP_SCHEDULE, and ND_BACKUP_COUNT.

environment:
  ND_BACKUP_PATH: /backup
  ND_BACKUP_SCHEDULE: "0 0 * * *"
  ND_BACKUP_COUNT: 7
volumes:
  - ./data:/data
  - ./backup:/backup

Manually Creating a Backup

You can manually create a backup via the navidrome backup create command:

sudo navidrome backup create

If you use docker compose, you can do the same with:

sudo docker compose run <service_name> backup create
# service_name is usually `navidrome` 

When manually creating a backup, no prune cycle is run, so none of the existing backups will be pruned. However, next time the automated backup process runs, the normal prune cycle will run and potentially remove several backups until the number of backups is down to the configured backup count setting. To manually run a prune cycle, use the navidrome backup prune command:

sudo navidrome backup prune

If you use docker compose, you can do the same with:

sudo docker compose run <service_name> backup prune
# service_name is usually `navidrome`

Locating Backup

Once configured, Navidrome will store backups in the directory specified by the BackupFolder or ND_BACKUP_PATH setting. To verify the location:

• Check the Config File: If using a configuration file, look for the Backup config node and confirm that all three options are configured.
• Check Environment Variables: If using environment variables, ensure that all three variables is set correctly.

Restoring a Backup

When you restore a backup, the existing data in the database is wiped and the data in the backup gets copied into the database.

Note: YOU MUST BE SURE TO RUN THIS COMMAND WHILE THE NAVIDROME APP IS NOT RUNNING/LIVE.

Restore a backup by running the navidrome backup restore command.

Additional Resources

For more detailed configuration options and examples, refer to the Navidrome Configuration Options page. This resource provides comprehensive guidance on customizing Navidrome to fit your needs.

By following this guide, you can effectively set up and manage backups for your Navidrome music server, ensuring your data is protected and easily recoverable.

5 - Developers

This page is for developers looking to learn more about Navidrome. For information about contributing to Navidrome, see the Navidrome Contribution Guide.

5.1 - Development Environment

Any IDE with good support for GoLang and JavaScript/Node can be used for Navidrome development. We suggest using Visual Studio Code, which has excellent support for both languages.

Using VSCode + Dev Container (Docker)

The project includes a VSCode Dev Container configuration for using with Docker. The Dev Container provides all dependencies out-of-the-box. If you prefer to install all dependencies yourself, or cannot/don’t want to install Docker for any reason, see the other sections below for step by step instructions for your OS.

Unix-based systems (Linux, macOS, BSD, …)

1. Install GoLang 1.23+

2. Install Node 20

3. Install TagLib 2.0+

   • Arch Linux: pacman -S taglib
   • macOS: brew install taglib --HEAD
   • For other platforms check their installation instructions

4. Install pkg-config

5. Clone the project from https://github.com/navidrome/navidrome

6. Install development tools: make setup. This may take a while to complete

7. Test installation: make build. This command should create a navidrome executable in the project’s folder

8. Create a navidrome.toml config file in the project’s folder with (at least) the following options:

# Set your music folder, preferable a specific development music library with few songs,
# to make scan fast
MusicFolder = "/path/to/music/folder"

# Make logging more verbose
LogLevel = "debug"

# This option will always create an `admin` user with the specified password, so you don't
# have to create a user every time you delete your dev database
DevAutoCreateAdminPassword = "password"

# Move the data/DB folder out of the root. `./data` folder is ignored by git
DataFolder = "./data"

# If you are developing in macOS with its firewall enabled, uncomment the next line to avoid 
# having to accept incoming network connections every time the server restarts:
# Address = "localhost"

To start Navidrome in development mode, just run make dev. This will start both the backend and the frontend in “watch” mode, so any changes will automatically be reloaded. It will open Navidrome automatically in your browser, using the URL http://localhost:4533/

If it does not open a new window in your browser, check the output for any error messages.

For more useful make targets, run make help.

Building it locally

To build Navidrome locally, follow these steps:

1. Make sure you have all the dependencies installed as mentioned in the previous sections.
2. Open a terminal and navigate to the project’s folder.
3. Run the command make build to build the whole project. This will create a navidrome binary in the project’s folder

Building with Docker

If you want to build Navidrome for a different platform than your own dev environment, use make docker-build and specify the OS/Platform as parameters. Example for Linux/ARM:

make docker-build PLATFORMS=linux/amd64,windows/amd64

To get a list of all available platforms, run make docker-platforms.

If you want to build a Docker image with your local changes, use make docker-image. The built image will be tagged locally as deluan/navidrome:develop. This can be overridden by setting the DOCKER_TAG variable. Use IMAGE_PLATFORMS to specify the platforms you want to build the image for. Example:

make docker-image IMAGE_PLATFORMS=linux/amd64,windows/amd64 DOCKER_TAG=mytag

Windows (using WSL)

Even though it is possible to setup a fully working Navidrome development environment in Windows, we currently don’t provide instructions for that (feel free to contribute to these docs if you successfully set it up).

The (arguably better) alternative is to set up the project using Visual Studio Code and WSL, which effectively lets you develop in a Linux environment while still using your Windows system.

Installing WSL

1. Make sure your Windows 10 is updated.
2. Go to Settings > Turn Windows feature on or off > Windows subsystem for Linux.
3. Go to Microsoft Store and download and install any Linux distro you like. For maximum compatibility, we recommend Ubuntu.
4. Open Downloaded Linux distro, add username and password and then update it using: sudo apt update && sudo apt upgrade -y.
5. Install needed compilers for building Navidrome: sudo apt install gcc g++
6. This will create an Linux terminal where you can execute any Linux commands.

Make sure you are using WSL 2.0

Configuring Visual Studio Code

1. Click on Extensions (present on leftmost column), install Remote Development extension and reload VSCode.
2. Press F1, execute Remote-WSL: New Window. This will connect your installed Linux distro to VSCode.
3. Now you can open a VSCode terminal and you’ll be able to run any Linux command.

Common Issues

1. Because of this WSL issue you need to use your network IP address to be able to login to Navidrome in development mode. Otherwise you will get an Error: Unauthorized when logging in. You can see your network IP address after running make dev.

Now that you have a working instance of Linux running on your machine, follow the steps above for Unix-based system in the VSCode terminal. For more information on working with VSCode+WSL, check their documentation.

Troubleshooting

System limit for number of file watchers reached

If you encounter the Error: ENOSPC: System limit for number of file watchers reached, watch while running make dev on Linux systems, then your system is maxing out the number of files that can be “watched” for changes at one time.

To increase this limit, you can run the command echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p, which adds the line fs.inotify.max_user_watches=524288 to /etc/sysctl.conf and reloads sysctl so the change takes effect. this allows inotify to watch more files and folders for changes at a time.

More information about this can be found here

5.2 - Creating New Themes

Themes in Navidrome are simple Material-UI themes. They are basic JS objects, that allow you to override almost every visual aspect of Navidrome’s UI.

Steps to create a new theme:

1. Create a new JS file in the ui/src/themes folder that exports an object containing your theme. Create the theme based on the ReactAdmin/Material UI documentation below. See the existing themes for examples.
2. Add a themeName property to your theme. This will be displayed in the theme selector
3. Add your new theme to the ui/src/themes/index.js file
4. Start the application, your new theme should now appear as an option in the theme selector

Before submitting a pull request to include your theme in Navidrome, please test your theme thoroughly and make sure it is formatted with the Prettier rules found in the project (ui/src/.prettierrc.js). Also, don’t forget to add lots of screenshots!

Resources for Material-UI theming

• Start reading ReactAdmin documentation
• Color Tool: https://material-ui.com/customization/color/#official-color-tool

5.3 - Translations

Translations are currently managed in POEditor. If you want to contribute new translations or help reviewing/proofreading any of the existing ones, please join our Discord server, channel #translations, for translation efforts coordination and to get further instructions.

Contributing with a Pull Request

Alternatively, you can submit a pull request with your proposed changes directly to our project in GitHub. This method requires you to have a GitHub account and some basic knowledge of Git.

If you choose to contribute translations via a pull request, most of the translation files are located in the resources/i18n directory. The English translation file is the only one located outside of this directory. It can be found in the ui/src/i18n/en.json.

Translation Status

Languages with at least 70% of the terms translated:

5.4 - Subsonic API Compatibility

Supported Subsonic API endpoints

Navidrome is currently compatible with Subsonic API v1.16.1, with some exceptions.

OpenSubsonic extensions are being constantly added. For an up to date list of supported extensions, check here.

This is a (hopefully) up-to-date list of all Subsonic API endpoints implemented in Navidrome. Check the “Notes” column for limitations/missing behavior. Also keep in mind these differences between Navidrome and Subsonic:

• Navidrome will not implement any video related functionality, it is focused on Music only
• Right now, Navidrome only works with a single Music Library (Music Folder)
• There are currently no plans to support browse-by-folder. Endpoints for this functionality (Ex: getIndexes, getMusicDirectory) returns a simulated directory tree, using the format: /Artist/Album/01 - Song.mp3.
• Navidrome does not mark songs as played by calls to stream, only when scrobble is called with submission=true
• IDs in Navidrome are always strings, normally MD5 hashes or UUIDs. This is important to mention because, even though the Subsonic API schema specifies IDs as strings, some clients insist in converting IDs to integers

6 - Google Summer of Code 2021

Introduction

Navidrome started in February 2016 as a modern and lightweight alternative to Subsonic: written in Go/React, implementing the subsonic API and thus compatible with all the subsonic clients in the world, licensed under GPL3, … Being relatively young, it does come/use modern development practices like continuous integration, a comprehensive testsuite, a relatively clean codebase, automatic dependency upgrades, automatic linting/CI/static analysis/… on each pull-request, comprehensive documentation … It recently gained popularity due to the decay of Subsonic/Airsonic, and currently has more than 4M downloads of its docker image, and had its binaries downloaded more than 12k times.

A demo version is available as well: https://demo.navidrome.org

Mentors and Contacts

We’re using discord for communications, feel free to join.

As for the mentors:

• Deluan Quintão (ET): deluan – @deluan
• Julien Voisin (CET): jvoisin – @dustriorg

Development methodology

The main repository is hosted on Github, which is also used for tracking bugs and running the continuous integration. The main communication medium is Discord, along with X for announcements, and Reddit as general purpose forum. The usual way to get code in is to submit a pull-request, which will be reviewed by the community and merged. Adding some tests might of course speed up this process.

Instructions for students

Students willing to take part in the Google Summer of Code 2021 with navidrome should send a couple of pull-requests, to demonstrate that they’re both motivated and capable of writing code and contributing to the project.

Tech stack

• Server:
  • Go
  • SQLite3
• Frontend (WebUI)
  • React
  • React Admin
  • Material-UI
  • Redux

Recommended steps

1. Read Google’s instructions for participating
2. Grab any project from the list of ideas that you’re interested in (or even suggest your own!).
3. Write a first draft proposal and ask one of the mentors to review it with you.
4. Submit it using Google’s web interface.

Student proposal guidelines

• Keep it simple enough to fit in no more than a couple of pages. Try to be clear and concise in your writing.
• Try to split GSoC period into tasks, and each task into subtasks. It helps us to understand how you plan to accomplish your goals, but more importantly, it’ll help you to understand the task deep enough before starting, and prioritize important things to do first.
• Please, note, how much time a day/week you are able to spend on this project. We do expect something between 30h and 40h.
• Submit your proposal early, not at the last minute!
• Feel free to choose a “backup” idea (the second task you want to do), so that conflicts (two students for one task) can be resolved.

Ideas

1. Media sharing

One of the nice features of Subsonic is its ability to generate a sharing link for a track/album/artist/playlist to send to friends, so that they can listen/download the music without having an account on your instance. This is a nice alternative to youtube links to share music. A nice way to implement this would be to have a table of shares, with a shorturl as ID. The table would store a reference to what is being shared. This shorturl would be used by a public endpoint. We would also need a standalone player similar to what is provided by Spotify when you share music through their service. Ex:

Steps

• Add a table for shares
• Add a way to create shares in the UI
• Implement the Subsonic API related endpoints: getShares, createShare, updateShare and deleteShare
• Add a standalone player (could be based on our current React Player)

Details

• Skill level: Medium
• Required abilities: Go and willing to learn a bit of React
• Expected outcome: Ability to share music with friends.

Links and further reading

• https://github.com/deluan/navidrome/issues/748

2. Jukebox mode

Some servers can be run in “jukebox” mode where the music is played directly on the server’s audio hardware, ex: mpd and Subsonic. A tricky part of this task might be to properly expose the “jukebox client” in the WebUI interface, as the current react-music-player used by Navidrome would have to somehow control the jukebox (via API) instead of the browser’s Audio component.

Steps

• Implementing a minimal subsonic client in go to connect to the server
• Implementing an audio output for the subsonic client
• Implementing the frontend part to select the jukebox mode and control the subsonic client
• Implementing the Subsonic API’s jukeboxControl endpoint

Details

• Skill level: Hard
• Required abilities: Go and React, a bit of UX would be nice
• Expected outcome: Ability to play music from the device running navidrome.

Links and further reading

• https://github.com/deluan/navidrome/issues/364
• https://airsonic.github.io/docs/jukebox/
• http://subsonic.org/pages/api.jsp#jukeboxControl

3. Google home/alexa integration

Nowadays, tech-oriented people tend to have a home assistant, and thus might want to be able to use it to control their subsonic instance. Since there is already the subsonic API to perform actions, this task on “only” a matter of writing the glue between Alexa/Google home and the API. Some actions might require a bit more than glue, for example, to play specific tracks/albums.

This task can be nicely paired with the jukebox one.

Steps

• Implementing the glue between Alexa/Google home and the Subsonic API
• Implementing the frontend part to configure this machinery

Details

• Skill level: Hard
• Required abilities: Go, having an Alexa/Google Home is a plus, but worse case we can send the student a device.
• Expected outcome: Ability to play/pause/next/previous the music via a home assistant

Links and further reading

• https://github.com/deluan/navidrome/issues/682
• https://developers.google.com/assistant/
• https://developer.amazon.com/en-US/alexa/alexa-skills-kit

4. Multiple libraries support

Some users want to use multiple libraries at the same time, for example to separate lossy/lossless albums, one for official albums and an other for bootlegs/lives, or one for audiobooks, some are even dreaming about having remote ones to listen to their friend’s music without leaving their navidrome instance!

Steps

• Implement support for multiple libraries
• Implement the UI allowing users to switch between libraries
• Implement permissions: Which user has access to which library
• Implement the musicFolderId attribute in most Subsonic API endpoints
• Plus: Implement support to access remote libraries from the WebUI

Details

• Skill level: Hard
• Required abilities: Go and SQL, and a teensy bit of react for the UX
• Expected outcome: Ability to use multiple libraries within a single user account

Links and further reading

• https://github.com/deluan/navidrome/issues/192
• http://subsonic.org/pages/api.jsp#getMusicFolders

5. Omnisearch

One search bar to search across the whole library, using proper SQLite’s Full Text Search, instead of having one separate search field per domain (artist, album, …)

Steps

• Replace current search implementation on the server with a new one using SQLite3’s FTS5
• Implement a search bar in the WebUI on the NavBar
• Implement a Search Results page, with links to artists, albums, songs and playlists
• Plus: integrate FTS5 with Spellfix1, to enable search for close matches. May not be supported by go-sqlite3 library used by Navidrome

Details

• Skill level: Medium
• Required abilities: Go and React.JS
• Expected outcome: Ability to have a single search field operating across all the library

Links and further reading

• https://github.com/deluan/navidrome/issues/255
• https://github.com/deluan/navidrome/issues/468
• https://www.sqlite.org/fts5.html
• https://www.sqlite.org/spellfix1.html#overview

6. Infinite Scroll

Currently, navidrome is using pagination instead of providing a more convenient infinite-scroll. The implementation isn’t trivial because navidrome is using react-admin, which not only doesn’t provide this feature out of the box, but makes it non-trivial to implement.

Steps

• Implement a new List component for React-Admin, that does not use pagination. It should load new data on demand. This component should be usable in all places where we currently use React-Admin’s List

Details

• Skill level: Medium
• Required abilities: React.JS, with a bit of Go and SQL
• Expected outcome: Infinite scrolling is implemented and usable.

Links and further reading

• https://github.com/deluan/navidrome/issues/132
• https://marmelab.com/blog/2019/01/17/react-timeline.html
• https://marmelab.com/react-admin/List.html#uselistcontroller

7. Lyrics support

It would be nice for navidrome to support LRC files to display lyrics. A possible stretch goal would be to implement lyrics fetching.

Steps

• Implement lyrics importing (from tags or external .lrc files)
• Make navidrome library aware of the presence of lyrics
• Implement Subsonic API’s getLyrics endpoint
• In the WebUI, when lyrics are available for the current song being played, set the appropriate attributes of the React Music Player used

Details

• Skill level: Easy
• Required abilities: Go and React.JS
• Expected outcome: Ability to see lyrics in the WebUI or Subsonic client when playing a song

Links and further reading

• https://github.com/deluan/navidrome/issues/249
• http://subsonic.org/pages/api.jsp#getLyrics
• https://github.com/lijinke666/react-music-player

8. Volume normalization

It would be nice if navidrome could perform audio normalization, to avoid having to fiddle with the volume when listening to different tracks of various volumes.

Steps

• Expose a preference to the user
• Implement per-track normalization
• Implement per-album normalization

Details

• Skill level: Easy
• Required abilities: Go and React.JS
• Expected outcome: Ability to have constant volume output in navidrome

Links and further reading

• https://github.com/deluan/navidrome/issues/233
• https://en.wikipedia.org/wiki/Audio_normalization
• https://trac.ffmpeg.org/wiki/AudioVolume

9. New Album grid

It would be nice to have something resembling Plex’s interface, with covert art fading in, as well as a slider to adjust their size.

Steps

• Implement the slider for the covers
• Implement asynchronous loading for the covers
• Implement the fading in upon loading

Details

• Skill level: Medium
• Required abilities: React.JS / Material-UI
• Expected outcome: Have a plex-looking album grid, with fading, scaling and async loading

Links and further reading

• https://github.com/deluan/navidrome/issues/323
• https://www.plex.tv/

Links and resources

• GSoC 2021 timeline
• GSoC FAQ
• GSoC student guide

7 - FAQ

▶︎ Can you add a browsing by folder option/mode to Navidrome?

While it is technically possible to add a browsing by folder option, doing so would require significant changes to Navidrome’s internal structures across most of its components. We have decided to focus on features that align with our vision of a music server that emphasizes tags. Implementing folder browsing would not only be a major undertaking, but it could also make supporting all of Navidrome’s current and future features more difficult and error-prone.

Here are a few situations where users might find folder browsing important, and how Navidrome addresses them:

1. Grouping music by classification (e.g., genre, mood, grouping): Navidrome already handle these tags, you can browse by genres in Subsonic clients, and it will have a dedicated Genre view in the future. There is support for the multivalued grouping tag, (with a dedicated view coming in a future release as well).
2. Having different releases for the same album: This will is already supported, and is configurable via the Persistent IDs feature. You can group albums by musicbrainz_albumid, discogs_release_id, folder, or any other tag you want.
3. Users who don’t have their library tagged: We explicitly do not support this, as it would make it very difficult to support all features Navidrome has and will have. We do not want to have code that “infers” that a folder with a bunch of MP3 files is an album, as this approach would make the code highly complex and error-prone.

If browsing by folder is an essential feature for you, there are alternative music servers that offer this functionality. We encourage you to explore these options if folder browsing is a priority.

▶︎ I have an album with tracks by different artists, why is it broken up into lots of separate albums, each with their own artist?

Navidrome only organises music by tags, it will not automatically group a folder containing a bunch of songs with different artists into one album.

For a “Various Artists” compilation, the Part Of Compilation tag (TCMP=1 for id3, COMPILATION=1 for FLAC) must be set, for all tracks.

For a single-artist album with a different artist name for each track (for example “Alice feat. Bob” , “Alice feat. Carol”), the Album Artist tags must be the same (“Alice”) for all tracks.

Also, take a look at the Persistent IDs feature, which can help you group tracks that belong to the same album, even if they have different artist. You can group tracks by folder, for example, by setting the configuration option PID.Album="folder". Check the PID documentation for more information.

▶︎ How can I edit my music metadata (id3 tags)? How can I rename/move my files?

With Navidrome you can’t. Navidrome does not write to your music folder or the files by design. It may have capabilities to change/add cover art for artists, albums and playlists in the future, but even then it won’t write these images to your Music Folder or embed them in the files.

The main reason for this is security: With an internet-facing server like Navidrome, users would only be one exploit away from all their music getting deleted.

There are many excellent “real” tag editors / music library managers out there to work with your music library.

Navidrome recommends: beets (Linux, macOS, Windows) and Musicbrainz Picard (Linux, macOS, Windows).

Others: mp3tag (Windows, macOS), ExifTool (Linux, macOS, Windows), Yate (macOS), Kid3 (Windows, macOS, Linux), foobar2000 (Windows, macOS), MusicBee (Windows), Media Monkey (Windows), Groove Music (Windows), Windows Media Player (Windows), Apple iTunes (Windows), Apple Music (macOS).

If you are new to organizing and tagging your library, take a look at this post about how to use Picard or beets with Navidrome: Organizing music with Musicbrainz Picard

Don’t forget to take a look at our Tagging Guidelines to ensure your music library is correctly tagged.

▶︎ Where are the logs?

To achieve maximum compatibility with a great number of platforms, Navidrome follows the Twelve Factor App methodology as much as possible. Specifically in the case of logs, Navidrome does not try to do any storage or routing of any log files, it only outputs all information to stdout, making it easy for the proper logging tools in each platform to handle them. Some examples bellow:

• Linux: if you installed Navidrome using the Systemd unit (as explained in the install instructions), you can see the logs using the journalctl tool: journalctl -u navidrome.service.

• Docker: you can use docker logs or docker-compose logs to retrieve/follow the logs.

• FreeBSD by default logs are writen to /var/log/debug.log

• Windows: depending on what you used to install Navidrome as a service, the logs will be in different locations by default:

  • if you used Shawl, just check the shawl_for_navidrome_*.log files created in the same location as the Shawl executable.
  • if you used NSSM, the location of the logs are specified by the AppStdout attribute.
  • if you used WinSW, the log file is in the same directory as the WinSW configuration file for the Navidrome service.

▶︎ Which cloud providers help fund the project with a revenue share?

PikaPods has partnered with us to offer you an officially supported, cloud-hosted solution. A share of the revenue helps fund the development of Navidrome at no additional cost for you.