Sonobarr

Music discovery for Lidarr power users, blending Last.fm insights, ListenBrainz playlists, and a modern web UI.

Sonobarr marries your existing Lidarr library with Last.fm's discovery graph to surface artists you'll actually like. It runs as a Flask + Socket.IO application, ships with a polished Bootstrap UI, and includes admin tooling so folks can share a single instance safely.

Features at a glance

🔌 Deep Lidarr integration - sync monitored artists, apply per-source monitor strategies, toggle monitor-new-albums policies, and send additions straight back to Lidarr.
🧭 Personal discovery hub - stream batches sourced from your Lidarr library, your saved Last.fm scrobbles, and ListenBrainz Weekly Exploration playlists, all controllable from the sidebar.
🤖 AI assistant - describe the vibe you want and let any OpenAI-compatible model seed new sessions with fresh artists, respecting optional library exclusions.
🙋 Artist requests workflow - non-admins raise requests, admins approve or reject with a single click, and every action is audited in real time.
🎧 Preview & context panels - launch YouTube or iTunes previews, inspect Last.fm biographies, and read key stats without leaving the grid.
⚡️ Real-time UX - Socket.IO keeps discovery progress, toast alerts, and button states in sync across every connected client.
👥 Role-based access - authentication, user management, profile controls for personal services, and admin-only settings live in one UI.
🔐 OIDC Single Sign-On - enable OpenID Connect for authentication, with optional group-based admin assignment and "OIDC-only" mode.
🛡️ Hardened configuration - atomic settings writes, locked-down file permissions, and CSRF-protected forms keep secrets safe.
🔔 Update & schema self-healing - footer badges surface new releases and the app backfills missing DB columns before loading users.
🐳 Docker-first deployment - official GHCR image, rootless-friendly UID/GID mapping, and automatic migrations on start.
🌐 Public API - REST API for integrating external tools such as custom dashboards (Documentation upcoming, for now study /api/docs/ on your instance).

How it works

┌──────────────────────┐        ┌──────────────────────┐
│ Lidarr (HTTP API)    │◀──────▶│ Sonobarr backend     │
│  - Artist catalogue  │        │  Flask + Socket.IO   │
│  - API key auth      │        │  Last.fm + Deezer    │
└──────────────────────┘        │  Worker threads      │
                                └─────────┬────────────┘
                                          │
                                          ▼
                                ┌──────────────────────┐
                                │ Sonobarr web client  │
                                │  Bootstrap + JS      │
                                │  Admin UX            │
                                └──────────────────────┘

Sonobarr spins up with a persistent SQLite database inside the config/ volume.
Admins provide Lidarr + Last.fm credentials through the settings modal.
When a user starts a discovery session, Sonobarr pulls artists from Lidarr, fans out to Last.fm, and streams cards back to the browser.
Optional preview and biography data is enriched via YouTube/iTunes/MusicBrainz.

Quick start (Docker)

🐳 Requirements: Docker Engine ≥ 24, Docker Compose plugin, Last.fm API key, Lidarr API key.

Create a working directory, cd into it, and make sure it's owned by the UID/GID the container will use (defaults to 1000:1000, configurable via PUID/PGID). The container starts as root to fix permissions, then drops privileges to PUID/PGID:
```
mkdir -p sonobarr && cd sonobarr
sudo chown -R 1000:1000 .
```

Download the sample configuration:

curl -L https://raw.githubusercontent.com/Dodelidoo-Labs/sonobarr/develop/docker-compose.yml -o docker-compose.yml
curl -L https://raw.githubusercontent.com/Dodelidoo-Labs/sonobarr/develop/.sample-env -o .env

Open .env and populate at least these keys (set PUID/PGID if you want a different container user):

PUID=1000
PGID=1000
secret_key=change-me-to-a-long-random-string
lidarr_address=http://your-lidarr:8686
lidarr_api_key=xxxxxxxxxxxxxxxxxxxxxxxx
last_fm_api_key=xxxxxxxxxxxxxxxxxxxxxxxx
last_fm_api_secret=xxxxxxxxxxxxxxxxxxxxxxxx

All keys in .env are lowercase by convention; the app will happily accept uppercase equivalents if you prefer exporting variables.

Start Sonobarr:
```
docker compose up -d
```
Browse to http://localhost:5000 (or the host behind your reverse proxy) and sign in using the super-admin credentials defined in .env.

Reverse proxy deployment

The provided docker-compose.yml exposes port 5000. It is however a better practice to attache Sonobarr to an external network. To do so, add the network name and static IP so it fits your proxy stack (NGINX Proxy Manager, Traefik, etc.) to the docker compose file. No additional environment: stanza is needed - everything comes from the .env file referenced in env_file.

For example:

...
    networks:
      npm_proxy:
        ipv4_address: 192.168.97.23

networks:
  npm_proxy:
    external: true

Updating

docker compose pull
docker compose up -d

The footer indicator will show a green dot when you are on the newest release and red when an update is available.

Environment reference

All variables can be supplied in lowercase (preferred for .env) or uppercase (useful for CI/CD systems). Defaults shown are the values Sonobarr falls back to when nothing is provided.

Key	Default	Description
`secret_key` (required)	-	Flask session signing key. Must be a long random string; store it in `.env` so sessions survive restarts.
`lidarr_address`	`http://192.168.1.1:8686`	Base URL of your Lidarr instance.
`lidarr_api_key`	-	Lidarr API key for artist lookups and additions.
`root_folder_path`	`/data/media/music/`	Default root path used when adding new artists in Lidarr (see issue #2).
`lidarr_api_timeout`	`120`	Seconds to wait for Lidarr before timing out requests.
`quality_profile_id`	`1`	Numeric profile ID from Lidarr (see issue #1).
`metadata_profile_id`	`1`	Numeric metadata profile ID.
`fallback_to_top_result`	`false`	When MusicBrainz finds no strong match, fall back to the first Lidarr search result.
`search_for_missing_albums`	`false`	Toggle Lidarr's "search for missing" flag when adding an artist.
`dry_run_adding_to_lidarr`	`false`	If `true`, Sonobarr will simulate additions without calling Lidarr.
`last_fm_api_key`	-	Last.fm API key for similarity lookups.
`last_fm_api_secret`	-	Last.fm API secret.
`youtube_api_key`	-	Enables YouTube previews in the "Listen" modal. Optional but recommended.
`openai_api_key`	-	Optional key for your OpenAI-compatible provider. Leave empty if your endpoint allows anonymous access.
`openai_model`	`gpt-4o-mini`	Override the model slug sent to the provider.
`openai_api_base`	-	Custom base URL for LiteLLM, Azure OpenAI, self-hosted Ollama gateways, etc. Blank uses the SDK default. **Must be complete base url such as `http://IP:PORT/v1` for example.
`openai_extra_headers`	-	JSON object of additional headers sent with every LLM call (e.g., custom auth or routing hints).
`openai_max_seed_artists`	`5`	Maximum number of seed artists returned from each AI prompt.
`similar_artist_batch_size`	`10`	Number of cards sent per batch while streaming results.
`auto_start`	`false`	Automatically start a discovery session on load.
`auto_start_delay`	`60`	Delay (seconds) before auto-start kicks in.
`sonobarr_superadmin_username`	`admin`	Username of the bootstrap admin account. If unset or blank, Sonobarr uses `admin`.
`sonobarr_superadmin_password`	`change-me`	Password for the bootstrap admin. If unset or blank, Sonobarr uses `change-me`.
`sonobarr_superadmin_display_name`	`Super Admin`	Friendly display name shown in the UI.
`sonobarr_superadmin_reset`	`false`	Set to `true` and restart Sonobarr to reapply bootstrap credentials for the configured username (default `admin`). Set it back to `false` after that restart.
`release_version`	`unknown`	Populated automatically inside the Docker image; shown in the footer. No need to set manually.
`sonobarr_config_dir`	`/sonobarr/config`	Override where Sonobarr writes `app.db`, `settings_config.json`, and migrations.

✅ Docker UID/GID mapping: set PUID/PGID in .env. The entrypoint fixes ownership and then drops privileges to that UID/GID.

ℹ️ secret_key is mandatory. If missing, the app refuses to boot to prevent insecure session cookies. With Docker Compose, make sure the key exists in .env and that .env is declared via env_file: as shown above.

ℹ️ Super-admin bootstrap applies only to the configured bootstrap username. With sonobarr_superadmin_reset=true, Sonobarr updates that user if it exists or creates it if it does not; it does not modify other admin accounts.

OIDC SSO Configuration

Key	Default	Description
`oidc_client_id`	-	Client ID from your OIDC provider.
`oidc_client_secret`	-	Client Secret from your OIDC provider.
`oidc_server_metadata_url`	-	The Discovery or Server Metadata URL of your OIDC provider (e.g., `https://your-provider.com/.well-known/openid-configuration`).
`oidc_admin_group`	-	Users in this OIDC group will automatically be granted admin privileges. Admin status syncs on every login.
`oidc_only`	`false`	If `true`, disables password-based login and redirects all users to the OIDC provider.

Important Note for OIDC Configuration: When configuring your OIDC provider, you must register a Redirect URI (or Callback URL). This is the URL where the OIDC provider will send the user back to Sonobarr after successful authentication. The format for this URI is: https://[YOUR_SONOBARR_DOMAIN_OR_IP]/oidc/callback

For security, OIDC providers require https for all production URLs. For local development, most providers allow http://localhost:[port] as an exception.

Using the app

Sign in with the bootstrap admin credentials. Create additional users from the User management page (top-right avatar → User management).
Configure integrations via the Settings button (top bar gear icon). Provide your Lidarr endpoint/key and optional YouTube key (can both be set in .env or UI)
Fetch Lidarr artists with the left sidebar button. Select the artists you want to base discovery on.
Hit Start. Sonobarr queues batches of similar artists and streams them to the grid. Cards show genre, popularity, listeners, similarity (from Last.fm), plus a status LED dot in the image corner.
Use Bio and Listen buttons for deeper context - the bio modal keeps Last.fm paragraph spacing intact. Click Add to Lidarr to push the candidate back into your library; feedback appears on the card immediately.
Stop or resume discovery anytime. Toast notifications keep everyone informed when conflicts or errors occur.

AI-powered prompts

Click the AI Assist button on the top bar to open a prompt modal.
Describe the mood, genres, or examples you're craving (e.g. "dreamy synth-pop like M83 but calmer").
Provide an API key and/or base URL in the settings modal (.env works too) for whichever OpenAI-compatible provider you use; without valid credentials the assistant stays disabled.
The assistant picks a handful of seed artists, kicks off a discovery session automatically, and keeps streaming cards just like a normal Lidarr-driven search.

The footer shows:

GitHub repo shortcut.
Current version.
A red/green status dot indicating whether a newer release exists.

Screenshots

Troubleshooting & FAQ

The container exits with "SECRET_KEY environment variable is required"

Ensure your Compose file references the .env file via env_file: and that .env contains a non-empty secret_key. Without it, Flask cannot sign sessions.

UI says "Update available" even though I pulled latest

The footer compares your runtime release_version with the GitHub Releases API once per hour. If you built your own image, set RELEASE_VERSION at build time (docker build --build-arg RELEASE_VERSION=custom-tag).

Artists fail to add to Lidarr

Check the container logs - Sonobarr prints the Lidarr error payload. Common causes are incorrect root_folder_path, missing write permissions on the Lidarr side, or duplicate artists already present.

Contributing

See CONTRIBUTING.md

License

This project is released under the MIT License.

Name		Name	Last commit message	Last commit date
Latest commit History 164 Commits
.github/workflows		.github/workflows
doc		doc
migrations		migrations
src		src
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
.sample-env		.sample-env
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
gunicorn_config.py		gunicorn_config.py
init.sh		init.sh
pytest.ini		pytest.ini
requirements.txt		requirements.txt
sonar-project.properties		sonar-project.properties

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Sonobarr

Table of contents

Features at a glance

How it works

Quick start (Docker)

Reverse proxy deployment

Updating

Environment reference

OIDC SSO Configuration

Using the app

AI-powered prompts

Screenshots

Troubleshooting & FAQ

The container exits with "SECRET_KEY environment variable is required"

UI says "Update available" even though I pulled latest

Artists fail to add to Lidarr

Contributing

License

About

Uh oh!

Releases 13

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Sonobarr

Table of contents

Features at a glance

How it works

Quick start (Docker)

Reverse proxy deployment

Updating

Environment reference

OIDC SSO Configuration

Using the app

AI-powered prompts

Screenshots

Troubleshooting & FAQ

The container exits with "SECRET_KEY environment variable is required"

UI says "Update available" even though I pulled latest

Artists fail to add to Lidarr

Contributing

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 13

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages