Developers

• 1: Development Environment
• 2: Creating New Themes
• 3: Translations
• 4: Adding Client Apps to the Catalog
• 5: 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 Windows/386:

make docker-build PLATFORMS=windows/386

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,linux/arm64 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:

Language	Code	Progress	Last Updated
Arabic	ar	70.95%	2023-03-26
Basque	eu	100.00%	2025-12-19
Bosnian	bs	98.76%	2025-07-29
Bulgarian	bg	83.61%	2025-12-06
Catalan	ca	80.71%	2025-04-17
Chinese (simplified)	zh-Hans	98.76%	2025-11-07
Chinese (traditional)	zh-Hant	98.76%	2025-11-07
Czech	cs	71.78%	2023-08-06
Danish	da	100.00%	2025-11-17
Dutch	nl	100.00%	2025-12-03
English	en	100.00%	2025-11-15
Esperanto	eo	100.00%	2025-12-03
Estonian	et	100.00%	2025-11-16
Finnish	fi	100.00%	2025-12-06
French	fr	100.00%	2025-12-01
Galician	gl	100.00%	2025-12-03
German	de	100.00%	2025-11-17
Greek	el	100.00%	2025-11-20
Hindi	hi	98.76%	2025-07-28
Hungarian	hu	99.38%	2025-12-02
Indonesian	id	98.76%	2025-07-19
Japanese	ja	100.00%	2025-11-21
Korean	ko	98.55%	2025-11-07
Norwegian	no	81.54%	2025-12-02
Polish	pl	100.00%	2025-11-16
Portuguese (BR)	pt-br	100.00%	2025-11-15
Russian	ru	100.00%	2025-11-24
Serbian	sr	80.71%	2025-04-17
Slovenian	sl	100.00%	2026-01-06
Spanish	es	100.00%	2025-12-01
Swedish	sv	100.00%	2025-11-17
Thai	th	100.00%	2025-11-21
Turkish	tr	100.00%	2025-12-02
Ukrainian	uk	100.00%	2025-11-17
Vietnamese	vi	100.00%	2025-12-11
Yiddish	yi	73.86%	2025-03-25

4 - Adding Client Apps to the Catalog

Want to list your app in the Compatible Client Apps catalog? This guide explains how to submit your app or update an existing entry.

Prerequisites

• Your app must support the OpenSubsonic, Subsonic, or Navidrome API
• You’ll need a GitHub account to submit a pull request
• Images must be in WebP format, max 1200px (PNG/JPEG needs to be converted)

Quick Start

1. Fork the navidrome/website repository
2. Create a folder for your app in assets/apps/ using kebab-case (e.g., my-awesome-app)
3. Add an index.yaml file with your app’s metadata
4. Add a thumbnail image and optional gallery screenshots
5. Convert (or resize) images if needed:

   npm run convert:images my-awesome-app
   

6. Validate your entry using the provided scripts:

   npm run validate:app my-awesome-app
   

7. Submit a pull request

Folder Structure

Each app has its own folder under assets/apps/:

assets/apps/
  my-app/
    index.yaml        # App metadata (required)
    thumbnail.webp    # App thumbnail (required)
    screen1.webp      # Gallery screenshot (optional)
    screen2.webp      # Gallery screenshot (optional)

Creating index.yaml

Use the template at assets/apps/_template/index.yaml as a starting point.

Required Fields

Optional Fields

Open Source vs Repository URL

The repoUrl field is used to fetch the app’s last release date. If your app has a GitHub or GitLab repository, include it for accurate “last updated” information.

The isOpenSource field controls whether the app displays an open source badge and appears in the “Open Source Only” filter:

• If repoUrl is set and isOpenSource is omitted → app is treated as open source (default)
• If repoUrl is set and isOpenSource is false → app is NOT treated as open source
• If repoUrl is not set → app is NOT treated as open source (regardless of isOpenSource)

Use isOpenSource: false when your app has a GitHub/GitLab repository for releases or issue tracking, but the source code is not publicly available under an open source license.

Supported Platforms

• android - Google Play Store
• ios - Apple App Store
• macos - macOS (optionally with Mac App Store link)
• windows - Windows
• linux - Linux
• web - Web browser
• docker - Docker container (optionally with Docker Hub link)
• other - CLI tools, other platforms

Example index.yaml

name: My Music App
url: https://example.com/my-app
repoUrl: https://github.com/example/my-app  # Optional - used for release tracking
# isOpenSource: false  # Uncomment if repo exists but source code is not public

platforms:
  android:
    store: https://play.google.com/store/apps/details?id=com.example.myapp
  ios:
    store: https://apps.apple.com/app/my-app/id123456789
  web: true
  linux: true

api: OpenSubsonic

description: A beautiful music player with offline support and gapless playback.

screenshots:
  thumbnail: thumbnail.webp
  gallery:
    - screen1.webp
    - screen2.webp

keywords:
  - dlna
  - chromecast
  - carplay
  - android auto

Image Guidelines

Thumbnail (Required)

• Max size: 1200×1200px
• Aspect ratio: Square preferred
• Format: WebP (PNG/JPEG needs to be converted)

Gallery Images (Optional)

• Max size: 1200×1200px
• Aspect ratio: Any
• Format: WebP (PNG/JPEG needs to be converted)
• File size: Keep under 500KB per image

Processing Images

If your images don’t meet the guidelines, run the conversion script:

npm run convert:images my-app

This automatically converts images to WebP format, resizes them to max 1200px, and optimizes file sizes.

Validating Your Entry

Before submitting, validate your app entry:

npm run validate:app my-app

The validation checks:

• YAML syntax and structure
• Required fields are present
• APIs are correctly specified
• Image files exist
• URLs are valid and reachable
• File sizes (warns if images > 500KB)

Updating an Existing App

To update an existing app entry:

1. Find the app folder in assets/apps/
2. Modify the index.yaml or replace images as needed
3. Run validation and submit a pull request

Questions?

If you have questions about adding your app, please open an issue on GitHub.

5 - 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
• Navidrome supports multiple Music Libraries (Music Folders) with user-specific access controls
• 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