Developers on Navidrome

Development Environment

Mon, 01 Jan 0001 00:00:00 +0000

This is just a summary on how to get started. If you are stuck or have any questions, please join our Discord server and give us a shout on the #dev channel

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.

Creating New Themes

Mon, 01 Jan 0001 00:00:00 +0000

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:

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.
Add a themeName property to your theme. This will be displayed in the theme selector
Add your new theme to the ui/src/themes/index.js file
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!

Translations

Mon, 01 Jan 0001 00:00:00 +0000

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.

Adding Client Apps to the Catalog

Mon, 01 Jan 0001 00:00:00 +0000

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

Fork the navidrome/website repository
Create a folder for your app in assets/apps/ using kebab-case (e.g., my-awesome-app)
Add an index.yaml file with your app’s metadata
Add a thumbnail image and optional gallery screenshots
Convert (or resize) images if needed:
```
npm run convert:images my-awesome-app
```
Validate your entry using the provided scripts:
```
npm run validate:app my-awesome-app
```
Submit a pull request

Folder Structure

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

Subsonic API Compatibility

Mon, 01 Jan 0001 00:00:00 +0000

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

System
`ping`
`getLicense`	Always valid ;)

Browsing
`getMusicFolders`	Returns all libraries accessible to the authenticated user
`getIndexes`	Doesn’t support `shortcuts`, nor direct children
`getMusicDirectory`
`getSong`
`getArtists`
`getArtist`
`getAlbum`
`getGenres`
`getArtistInfo`	Requires external integrations
`getArtistInfo2`	Requires external integrations
`getAlbumInfo`	Requires external integrations
`getAlbumInfo2`	Requires external integrations
`getTopSongs`	Requires Last.fm integration
`getSimilarSongs`	Requires Last.fm integration
`getSimilarSongs2`	Requires Last.fm integration

Album/Songs Lists
`getAlbumList`
`getAlbumList2`
`getStarred`
`getStarred2`
`getNowPlaying`
`getRandomSongs`
`getSongsByGenre`

Searching
`search2`	Doesn’t support Lucene queries, only simple auto complete queries
`search3`	Doesn’t support Lucene queries, only simple auto complete queries

Playlists
`getPlaylists`	`username` parameter is not implemented
`getPlaylist`
`createPlaylist`
`updatePlaylist`
`deletePlaylist`

Media Retrieval
`stream`
`download`	Accepts ids for Songs, Albums, Artists and Playlists. Also accepts transcoding options similar to `stream`
`getCoverArt`
`getLyrics`	Works with embedded lyrics and external files
`getAvatar`	If Gravatar is enabled and the user has an email, returns a redirect to their Gravatar. Or else returns a placeholder

Media Annotation
`star`
`unstar`
`setRating`
`scrobble`

Bookmarks
`getBookmarks`
`createBookmark`
`deleteBookmark`
`getPlayQueue`	`current` is a string id, not `int` as it shows in the official Subsonic API documentation
`savePlayQueue`

Sharing (if `EnableSharing` is `true`)
`getShares`
`createShare`
`updateShare`
`deleteShare`

Internet radio
`getInternetRadioStations`
`createInternetRadioStation`
`updateInternetRadioStation`
`deleteInternetRadioStation`

User Management
`getUser`	Ignores username parameter, and returns the user identified in the authentication. Roles reflect actual server capabilities and user permissions. For example: `downloadRole` depends on download being enabled, `jukeboxRole` depends on jukebox being enabled, etc. Note that some features like ratings and favorites are always available to all users regardless of roles
`getUsers`	Returns only the user identified in the authentication

Media library scanning
`getScanStatus`	Also returns the extra fields `lastScan` and `folderCount`
`startScan`	Accepts an extra `fullScan` boolean param, to force a full scan