Scan a local music library, enrich it with metadata from MusicBrainz and Spotify, then browse and play music through a fast web UI. Supports local playback, UPnP renderers (e.g., Naim Uniti Atom) with next-track staging, and Chromecast.
- Library scanning — fast tag-based scan with incremental updates and MusicBrainz ID extraction
- Rich metadata — artist bios, artwork, similar artists, top tracks, and external links
- Local + UPnP playback — local streaming and UPnP control (play/pause/seek/volume)
- Next-track staging — UPnP renderers that support SetNextAVTransportURI get the next track ahead of time (gapless where the renderer is; not yet measured on hardware)
- Instant search — across artists, albums, and tracks
- History + Last.fm — local playback history with matched Last.fm scrobbles
- Recommendations — artist/album/track recommendations from listening history
- Playlists — create and manage playlists with ordering support
- Modern UI — responsive SvelteKit interface with renderer switching
Jamarr ships as a Docker image (ghcr.io/darious/jamarr). A server needs
three files, not the repository: docker-compose.yml, .env and
config.yaml. All three are attached to every
release and live at the top of
this repo.
mkdir jamarr && cd jamarr
for f in docker-compose.yml .env.example config.yaml; do
curl -fsSLO "https://raw.githubusercontent.com/darious/jamarr/main/$f"
done
cp .env.example .envEdit .env and set the required values:
| Variable | Description |
|---|---|
HOST_IP |
Your server's LAN IP (renderers fetch streams from it) |
MUSIC_NFS_ADDR |
NFS server address hosting your music library |
MUSIC_NFS_PATH |
NFS export path on the server |
DB_PASS |
PostgreSQL password (the stack refuses to start without it) |
DB_DATA_PATH |
Host directory for PostgreSQL data |
CACHE_PATH |
Host directory for Jamarr cache |
JWT_SECRET_KEY |
Generate with python -c "import secrets; print(secrets.token_urlsafe(32))" |
SPOTIFY_CLIENT_ID / SPOTIFY_CLIENT_SECRET |
Spotify API credentials (for metadata enrichment) |
LASTFM_API_KEY / LASTFM_SHARED_SECRET |
Last.fm API credentials (for scrobbling) |
Optional API keys for additional metadata sources: QOBUZ_*, TIDAL_*, FANARTTV_API_KEY.
Non-secret app config (MusicBrainz URL, logging, concurrency, per-renderer overrides) lives in config.yaml.
docker compose pull && docker compose up -dDatabase migrations run when the app starts. The container uses
network_mode: "host" for UPnP device discovery. To pin a version instead of
latest, change the image tag in docker-compose.yml (for example :1.14.0).
Want a database dump before each upgrade? deploy.sh (also attached to each
release) does prune → pull → dump → migrate → restart in that directory.
docker compose run --rm jamarr uv run python -m app.scanner.cli scan
docker compose run --rm jamarr uv run python -m app.scanner.cli metadataSee Scanner CLI for full command reference.
http://your-server-ip:8111
📖 Full docs: darious.github.io/jamarr — searchable, with a generated API reference and database schema. Source in docs/.
| Topic | Link |
|---|---|
| Install & configuration | Getting Started |
| Architecture & decisions (ADRs) | Architecture |
| API reference (generated from OpenAPI) | API |
| Database schema (generated by tbls) | Schema |
| Clients (web, TUI, Android) | Clients |
| Contributing | CONTRIBUTING.md |
API and schema docs are generated from the code, so they don't drift. Build the
site locally with uv run --group docs mkdocs serve.
Jamarr is licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only). See LICENSE.
Third-party dependencies, logos, service names, and trademarks remain under their own licenses. See THIRD_PARTY_NOTICES.md.