Usage

• 1: Navidrome Configuration Options
• 2: Tagging Guidelines
• 3: Using custom tags with Navidrome
• 4: Customizing Persistent IDs in Navidrome
• 5: Artwork location resolution
• 6: External Integrations
• 7: Sharing
• 8: How to Use Smart Playlists in Navidrome (Beta)
• 9: Missing Files
• 10: Monitoring Navidrome
• 11: Reverse proxy authentication
• 12: Jukebox mode
• 13: Security Considerations
• 14: Automated Backup

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 - 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!

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.Artists.Split option:

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

Note that case sensitivity matters here. For example, FEAT. (uppercase) will be recognized by default, but feat. (lowercase) requires explicit configuration.

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

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.

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

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:

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:

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.

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.

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.

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.

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'

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

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.

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.