Developers

• 1: Development Environment
• 2: Creating New Themes
• 3: Translations
• 4: Subsonic API Compatibility

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

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

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:

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