# Project pack: Navidrome @ 56cc32a

Facts about **Navidrome** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Navidrome turns your folder of music files into a personal streaming service. Browse by album, artist or genre, make playlists, star favourites and see song lyrics, from a web page or dozens of free phone apps. Each family member gets their own playlists and play counts. It is light enough for a Raspberry Pi and copes happily with very large collections.

## Version and source
- Repository: https://github.com/navidrome/navidrome
- Pinned commit: `56cc32aedea8dcb28919adbdcfc1f51294df2e5f`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/navidrome/navidrome/archive/56cc32aedea8dcb28919adbdcfc1f51294df2e5f.zip
- Official docs: https://www.navidrome.org/docs/
- Live demo: https://demo.navidrome.org (user: demo / password: demo). Official demo with free music. Settings are disabled there.
- Licence: **GPL-3.0-only**. Free to use and change. If you give copies of the program (changed or not) to other people, you must share the source code under the same licence. Running it for your household, or as a service others use online, has no extra obligations.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/navidrome/navidrome bespoke-navidrome
  cd bespoke-navidrome
  git checkout --detach 56cc32aedea8dcb28919adbdcfc1f51294df2e5f
  # Prepare development requirements and local configuration first.
  # Setup notes: backend and UI with hot reload; UI dev server proxies to the backend on :4533
  make setup && make dev
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  docker run -d --name navidrome --restart=unless-stopped --user $(id -u):$(id -g) -v /path/to/music:/music:ro -v /path/to/data:/data -p 4533:4533 -e ND_LOGLEVEL=info navidrome/navidrome:latest # then open http://localhost:4533 and create the first (admin) user
  ```

- Needs: Docker, or the ready-made binary for Linux, macOS, Windows or Raspberry Pi, FFmpeg for transcoding (included in the Docker image), For development, Go and Node.js (make setup installs the rest)
- Develop: `make setup && make dev   # backend and UI with hot reload; UI dev server proxies to the backend on :4533`
- Test: `make testall`
- Check/lint: `make lintall`
- Build: `make build`
- Stack: go, javascript (chi, Squirrel, goose migrations, React, react-admin, Material UI, Vite, Extism (WebAssembly plugins)). Difficulty for a non-developer with an AI: **moderate**. A tidy, well-tested project: a Go backend (server/, core/, persistence/, scanner/) and a React web interface in ui/ built on react-admin. Themes are small JavaScript files, and many options are a single ND_ variable. The WebAssembly plugin system lets you add features in Go, Rust, Python or TypeScript without forking. Code changes need Go and Node.

## The project's own AI instructions
Read these in the repository before changing code: `CONTRIBUTING.md`, `plugins/README.md`.

## Customisation points (settings → extend → code)
- **themes** [settings]: Light, dark, Spotify-like, Nord, Catppuccin and more, chosen by each person. → `Personal → Theme (more than 30 themes in ui/src/themes/); ND_DEFAULTTHEME for new users`
- **options** [settings]: Welcome message, login background, sharing, downloads, scan schedule, lyrics order and more. → `ND_* environment variables or navidrome.toml (all defaults in conf/configuration.go)`
- **users-and-libraries** [settings]: An account for each person, and which music libraries each one can see. → `Settings → Users and Libraries (docs usage/features/multi-library)`
- **smart-playlists** [extend]: Playlists that fill themselves, e.g. "five-star songs not played this month" or "80s rock". → `.nsp files in your music folder (docs usage/features/smart-playlists)`
- **plugins** [extend]: Add metadata sources, scrobblers, lyrics providers, webhooks or scheduled tasks without forking. → `WebAssembly plugins (plugins/README.md, examples in plugins/examples/)`
- **subsonic-apps** [extend]: Use phone and desktop apps such as Symfonium, Substreamer, play:Sub or Feishin, or scripts. → `Subsonic API (server/subsonic/); any Subsonic-compatible app`
- **new-theme** [code]: A theme in your own colours, which upstream also welcomes as a contribution. → `ui/src/themes/ (add a theme file and register it in ui/src/themes/index.js)`
- **web-ui** [code]: Change screens, such as a big-button view for the kitchen. → `ui/src/ (React, e.g. album/, artist/, playlist/, audioplayer/), text in ui/src/i18n/en.json and resources/i18n/`
- **backend** [code]: New data or behaviour. Database changes need a migration (make migration-sql / migration-go). → `server/nativeapi/ and server/subsonic/ (APIs), core/, persistence/, db/migrations/`

## Must keep working
- Your music files. Mount the music folder read-only.
- Playlists, play counts, ratings and favourites in navidrome.db. Back up before upgrades or code changes.
- The Subsonic API, which every phone and desktop app relies on.
- Each user's private playlists and library permissions.

## Staying updatable
Themes, ND_ options, smart playlists, plugins and Subsonic apps cover most wishes without a fork. Upstream asks for an issue first, Conventional Commit messages and a DCO sign-off (git commit --signoff) on every commit (CONTRIBUTING.md). New themes are a classic, welcome first contribution.

## Data, costs and safety
- Personal data: **yes**. Stored in: Music files stay in your music folder (mount it read-only). Users, playlists, play counts, favourites and the library index live in navidrome.db (SQLite) in the data folder. Back up the data folder. Navidrome has built-in database backups (see the backup page in the docs and `navidrome backup`). Your music folder is never changed.
- Service: Last.fm (optional, free (needs your own API key)): Artist biographies, images, similar artists and scrobbling your listening history.
- Service: ListenBrainz (optional, free): Scrobble what you play to ListenBrainz.
- Service: Deezer (optional, free): Artist images (on by default; turn off with ND_DEEZER_ENABLED=false).
- Service: Navidrome Insights (optional, free): Sends anonymous usage statistics to insights.navidrome.org once a day. Turn off with ND_ENABLEINSIGHTSCOLLECTOR=false.
- Setting `ND_MUSICFOLDER`: Folder with your music (/music in Docker).
- Setting `ND_DATAFOLDER`: Folder for the database and cache (/data in Docker).
- Setting `ND_UIWELCOMEMESSAGE`: A message shown on the login page.
- Setting `ND_DEFAULTTHEME`: Theme for new users (default Dark). Each user can pick their own.
- Setting `ND_DEFAULTLANGUAGE`: Interface language for new users, e.g. en.
- Setting `ND_SCANNER_SCHEDULE`: How often to look for new music (e.g. 1h or a cron expression); the folder is also watched for changes.
- Setting `ND_ENABLESHARING`: Allow public share links to songs, albums and playlists.
- Setting `ND_ENABLEDOWNLOADS`: Allow users to download music files.
- Setting `ND_ENABLETRANSCODINGCONFIG`: Show the transcoding settings in the UI. Only turn on while configuring, as it allows running commands.
- Setting `ND_ENABLEINSIGHTSCOLLECTOR`: Set to false to stop sending anonymous usage statistics.
- Setting `ND_LASTFM_APIKEY` (**secret**: the person enters it themselves, never in chat): Your Last.fm API key. ND_LASTFM_SECRET (also secret) goes with it.
- Setting `ND_LASTFM_SECRET` (**secret**: the person enters it themselves, never in chat): Your Last.fm shared secret.
- Setting `ND_BASEURL`: Set when serving Navidrome under a sub-path such as /music behind a reverse proxy.
- The first account created becomes the admin. Create it straight after starting, before anyone else can reach the page.
- Use HTTPS through a reverse proxy if you open it to the internet; Subsonic apps send passwords with every request.
- Keep ND_ENABLETRANSCODINGCONFIG off except while you set up transcoding, because it lets admins run commands.
- Anonymous usage statistics are sent daily by default. Set ND_ENABLEINSIGHTSCOLLECTOR=false if you prefer not to.

---

# Customising Navidrome

Navidrome is a tidy Go server with a React web interface. **Most wishes are themes, ND_ options, smart playlists, plugins or a different phone app.** Use levels 1 and 2 first.

## Level 1: Settings (no code)
- **Themes:** each person picks one under Personal → Theme (more than 30, from Light and Dark to Spotify-ish, Nord and Catppuccin). Set the default for new users with `ND_DEFAULTTHEME`.
- **Options:** set `ND_*` environment variables or a `navidrome.toml` file. All defaults are in `conf/configuration.go`; the options page on navidrome.org explains each one. Useful ones:
  - `ND_UIWELCOMEMESSAGE`, `ND_UILOGINBACKGROUNDURL`
  - `ND_ENABLESHARING`, `ND_ENABLEDOWNLOADS`
  - `ND_SCANNER_SCHEDULE`, `ND_LYRICSPRIORITY`, `ND_DEFAULTLANGUAGE`
  - Turn off outside calls with `ND_ENABLEINSIGHTSCOLLECTOR=false`, `ND_DEEZER_ENABLED=false` and `ND_ENABLEEXTERNALSERVICES=false`.
- **People and libraries:** Settings → Users (admin). Each user can be limited to certain libraries if you add more than one music folder.
- **Scrobbling:** each user links Last.fm or ListenBrainz in Personal settings. Last.fm needs `ND_LASTFM_APIKEY` and `ND_LASTFM_SECRET` on the server.

## Level 2: Extend (no fork)
- **Smart playlists:** `.nsp` files (JSON rules) in your music folder become playlists that update themselves, e.g. rating ≥ 4 and not played in 30 days. See "Smart Playlists" in the docs.
- **Plugins:** WebAssembly plugins add metadata sources, scrobblers, lyrics, webhooks, scheduled jobs and more. Read `plugins/README.md`. Working examples are in `plugins/examples/` (`webhook-rs`, `nowplaying-py`, `wikimedia`, `discord-rich-presence-rs`…). Manage them in the UI or with `navidrome plugin`.
- **Apps:** any Subsonic-compatible app works (Symfonium, Substreamer, play:Sub, Feishin, Supersonic…). Many allow offline downloads.
- **Subsonic API** (`server/subsonic/`) for scripts and home automation.

## Level 3: Code
Read upstream `CONTRIBUTING.md` first.

| Change | Where |
|---|---|
| New theme | Add `ui/src/themes/<name>.js` (and optional `<name>.css.js`), then register it in `ui/src/themes/index.js` |
| Screens | `ui/src/` (e.g. `album/`, `artist/`, `playlist/`, `audioplayer/`, `layout/`) |
| Text | `ui/src/i18n/en.json` (UI); other languages in `resources/i18n/` via POEditor |
| API used by the web UI | `server/nativeapi/` |
| Subsonic API | `server/subsonic/`. Keep it compatible with existing apps. |
| Business logic | `core/` |
| Database access | `persistence/` + a migration in `db/migrations/` (`make migration-sql` or `make migration-go`) |
| Scanning music | `scanner/` |

## Running locally
- **Just use it:**
  1. `docker run -d --user $(id -u):$(id -g) -v /path/to/music:/music:ro -v /path/to/data:/data -p 4533:4533 navidrome/navidrome:latest`
  2. Open http://localhost:4533 and create the admin user straight away.
- **Develop:**
  1. Install Go and Node.js.
  2. Run `make setup` once.
  3. Run `make dev` for the backend and UI with hot reload.
  - `make server` runs the backend only. `make build` makes a single binary with the UI inside.
- **Check:** `make testall` (Go, i18n and JS tests) and `make lintall`.

## Pitfalls
- The `master` branch can be unstable. Run releases for real use, and test your changes on a copy of the data folder.
- Docker permission errors: the `--user` must own the data folder and be able to read the music folder.
- Don't break the Subsonic API. Phone apps you don't control depend on it.
- Commits to upstream need `--signoff` (DCO) and Conventional Commit messages.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/navidrome/56cc32a/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/navidrome/56cc32a/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/navidrome/56cc32a/r2/SKILL.md)