mirror/sonobarr
1
0
Fork 0
mirror of https://github.com/Dodelidoo-Labs/sonobarr.git synced 2025-12-23 22:17:45 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
sonobarr/README.md
Beda Schmid 67c6baf19b Update Readme for v0.10.0 
Update readme
2025-11-04 10:27:11 -03:00

15 KiB
Raw Permalink Blame History

Sonobarr

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

Release Container License

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.

Sonobarr logo

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.
  • 🛡️ 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            │
                                └──────────────────────┘
  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, Last.fm API key, Lidarr API key.

  1. 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). This keeps every file the container writes accessible to you: 
    mkdir -p sonobarr && cd sonobarr
sudo chown -R 1000:1000 .
  2. 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
  3. Open .env and populate at least these keys: 
    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

Optional – enables the AI assistant modal (any OpenAI-compatible endpoint)

openai_api_key=sk-...

openai_api_base=https://api.openai.com/v1

> All keys in `.env` are lowercase by convention; the app will happily accept uppercase equivalents if you prefer exporting variables.
4. Start Sonobarr:
```bash
docker compose up -d
  1. 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.
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.
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.

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

Local development

See CONTRIBUTING.md

Tests

Currently relying on manual testing. Contributions adding pytest coverage, especially around the data handler and settings flows, are very welcome.

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 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)
  3. Fetch Lidarr artists with the left sidebar button. Select the artists you want to base discovery on.
  4. 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.
  5. 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.
  6. 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

Login Window Profile Settings User Admin Configuration Configuration AI Assist Artist Suggestions Pre Hear

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.

Reference in New Issue View Git Blame Copy Permalink