Sonobarr

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

This is an independently maintained fork of Dodelidoo-Labs/sonobarr (forked at v0.12.1). The upstream project has been inactive since March 2026. This fork continues active development with new features including OIDC SSO, per-user API keys, a setup wizard, and DB-backed configuration. The Docker image is published to ghcr.io/tinkermesomething/sonobarr.

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.

---

Table of contents

1. Features at a glance
2. How it works
3. Quick start (Docker)
4. Environment reference
5. Local development
6. Using the app
7. Screenshots
8. Troubleshooting & FAQ
9. Contributing
10. License

---

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.
• 🔑 Per-user API keys – users can optionally bring their own Last.fm, YouTube, and LLM keys, with automatic fallback to admin-configured global keys.
• 🛡️ Hardened configuration – all settings stored in SQLite (no config files to lose), and CSRF-protected forms keep secrets safe.
• 🧙 Setup wizard – first-boot wizard guides the admin through Lidarr and API key setup; new users pick their server and personal keys on first login.
• 🔔 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            │
                                └──────────────────────┘

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

---

Quick start (Docker)

🐳 Requirements: Docker Engine ≥ 24, Docker Compose plugin.

1. Create a working directory and make sure it’s owned by UID/GID 1000 (the container default):

   mkdir -p sonobarr && cd sonobarr
   sudo chown -R 1000:1000 .

2. Create a minimal docker-compose.yml:

   services:
     sonobarr:
       image: ghcr.io/tinkermesomething/sonobarr:latest
       container_name: sonobarr
       env_file:
         - .env
       volumes:
         - ./config:/sonobarr/config
         - /etc/localtime:/etc/localtime:ro
       ports:
         - "5000:5000"
       restart: unless-stopped

3. Create .env with just the essentials:

   secret_key=change-me-to-a-long-random-string

   For OIDC SSO, also add:

   OIDC_CLIENT_ID=your-client-id
   OIDC_CLIENT_SECRET=your-client-secret
   OIDC_SERVER_METADATA_URL=https://your-provider/.well-known/openid-configuration

   All other settings (Lidarr, API keys, discovery tuning) are configured through the setup wizard on first login.
4. Start Sonobarr:

   docker compose up -d

5. Browse to http://localhost:5000. The first user to log in becomes admin and is guided through the setup wizard. No credentials in .env needed.

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

Only a handful of variables belong in .env. Everything else is configured through the app UI and stored in the SQLite database.

Key	Required	Description
secret_key	Yes	Flask session signing key. Must be a stable random string — changing it logs everyone out.
OIDC_CLIENT_ID	OIDC only	OAuth 2.0 client ID from your identity provider.
OIDC_CLIENT_SECRET	OIDC only	OAuth 2.0 client secret.
OIDC_SERVER_METADATA_URL	OIDC only	Provider discovery URL (/.well-known/openid-configuration).
OIDC_ADMIN_GROUP	No	Group claim that grants admin status. Seeded into DB on first boot; can be removed once configured via UI.
OIDC_ONLY	No	Set true to disable local password login entirely. Seeded into DB on first boot.

All Lidarr configuration, API keys, discovery tuning, and user management are handled through the setup wizard and admin UI — not in .env. | openai_extra_headers | – | Deprecated. JSON object of additional headers for LLM calls. Now configured per-user in Profile settings. | | openai_max_seed_artists | 5 | Deprecated. Max seed artists from AI prompts. Now configured per-user in Profile settings. | | 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. | | sonobarr_superadmin_password | change-me | Password for the bootstrap admin. Set to a secure value before first launch. | | sonobarr_superadmin_display_name | Super Admin | Friendly display name shown in the UI. | | sonobarr_superadmin_reset | false | Set to true once to reapply the bootstrap credentials on next start. | | 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. |

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_only	false	If true, disables password-based login and redirects all users to the OIDC provider. Warning: If your OIDC provider is down, all users (including admins) will be locked out.

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. Check your provider's documentation to confirm.

ℹ️ 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.

---

Using the app

1. Sign in with the bootstrap admin credentials. Create additional users from the User management page (top-right avatar → User management).
2. Configure Lidarr via the Settings button (top bar gear icon). Provide your Lidarr endpoint and API key.
3. Set up your API keys in your Profile (top-right avatar → Profile). Configure Last.fm, YouTube, and LLM credentials for personalized discovery features.
4. Fetch Lidarr artists with the left sidebar button. Select the artists you want to base discovery on.
5. 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.
6. 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.
7. 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").
• Configure your LLM API key and base URL in your Profile (top-right avatar → Profile → External API Keys). Without valid credentials, the AI assistant remains 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.

Original work © 2024 TheWicklowWolf. Adaptations and ongoing maintenance © 2025 Dodelidoo Labs.