# Project pack: Navidrome @ 56cc32a

Facts about **Navidrome** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v4.md). Pinned to one version; 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.

## Setup path (checked 2026-11-03)
- **Start here, no Docker:** Download the prebuilt program for your system and run it. No Docker.
- Offer Docker only if the person asks or this path fails. The commands further down may use Docker; they are not the starting point.
- Verdict source: https://raw.githubusercontent.com/navidrome/navidrome/HEAD/README.md
- You may be unable to download source archives or run commands in this session. The person downloads and runs things; if you cannot fetch something, give any changed file in full in chat with its path.

## Version and source
- Repository: https://github.com/navidrome/navidrome
- Pinned commit: `56cc32aedea8dcb28919adbdcfc1f51294df2e5f`. Use exactly this version.
- Zip the person can download in a browser: https://github.com/navidrome/navidrome/archive/56cc32aedea8dcb28919adbdcfc1f51294df2e5f.zip
- Fresh checkout (only if you have a shell and git): use the commands below in an empty folder. If this exact source is already checked out, keep your branch and use the development command; do not clone again or reset local changes.
- 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.

## Commands from the pinned source
- Developer commands (they may use Docker):

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

- Separate trial of the current upstream release (not your changes; sample data and a separate data directory only):

  ```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
  ```
- Tools these commands use: 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, in the repository: `CONTRIBUTING.md`, `plugins/README.md`.
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. Secrets are entered by the person, never in chat.

---
Later, only when a step needs it: [reference.md](https://handoff.bespokeai.software/p/navidrome/56cc32a/r3/reference.md) (customisation points, must-keep-working, data and costs, coding conventions) · [hosting.md](https://handoff.bespokeai.software/p/navidrome/56cc32a/r3/hosting.md) (long-term hosting; hosts are paid third parties) · [bespoke.yaml](https://handoff.bespokeai.software/p/navidrome/56cc32a/r3/bespoke.yaml) · [SKILL.md](https://handoff.bespokeai.software/p/navidrome/56cc32a/r3/SKILL.md)