Configuration

• 1: Navidrome Configuration Options
• 2: Using custom tags with Navidrome
• 3: Customizing Persistent IDs in Navidrome

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

2 - Using custom tags with Navidrome

Overview

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

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

Configuring custom tags

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

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

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

Example configuration

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

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

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

Common use cases

Here are some common use cases for custom tags.

Adding a new tag for disambiguation

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

Example:

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

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

Disabling tags

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

Example: disabling the subtitle tag

Tags.Subtitle.Ignore = true

Changing separators

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

Example: Splitting the artist tag by \ and ;

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

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

Tags.Genre.Split = []

Artist splitting

By default, Navidrome will split the artist tag value by various common separators (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.

3 - Customizing Persistent IDs in Navidrome

Persistent IDs in Navidrome

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

Overview of Persistent IDs

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

Key Features

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

Default Configuration

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

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

• Track PID:

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

• Album PID:

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

Customizing PIDs

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

• Grouping albums by folder:

  PID.Album = "folder"
  

• Using Discogs or custom IDs for albums:

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

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

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

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

Handling File Moves and Retagging

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

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

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

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

Artist IDs

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

Troubleshooting and Support

If issues arise when enabling or configuring PIDs:

• Review Navidrome logs.
• Validate your configuration file.