8000 GitHub - darious/jamarr: Self-hosted music library scanner and UPnP controller with web and Android clients · GitHub
[go: up one dir, main page]

Skip to content
dariousPublic

About

Self-hosted music library scanner and UPnP controller with web and Android clients

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

254 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
Jamarr

Self-hosted, web-based music controller.

Documentation   License: AGPL v3


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.

Features

  • 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

Quick Start

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.

1. Get the files

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 .env

2. Configure

Edit .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.

3. Start, and upgrade the same way

docker compose pull && docker compose up -d

Database 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.

4. Scan your library

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 metadata

See Scanner CLI for full command reference.

5. Open the UI

http://your-server-ip:8111

Documentation

📖 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.

License

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.

About

Self-hosted music library scanner and UPnP controller with web and Android clients

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages

0