Configuration

MusicSeerr is configured through its web UI at Settings. All settings are saved to the /app/config volume.

The Settings page has the following tabs: Release Preferences, Last.fm, ListenBrainz, Scrobbling, Music Source, Jellyfin, Plex, Navidrome, Lidarr Connection, Library Sync, YouTube, Local Files, Cache, Advanced, Users, and Security.

Lidarr Connection

Lidarr is the core integration. It manages your music library and handles album requests.

After connecting, MusicSeerr syncs your library automatically. You can set the sync frequency to manual, 5 minutes, 10 minutes, 30 minutes, or 1 hour under the Library Sync tab.

Jellyfin

Connect Jellyfin to stream music, browse your Jellyfin library, and report playback progress.

Navidrome

Connect Navidrome to stream music and browse your Navidrome library. MusicSeerr communicates with Navidrome through its Subsonic API.

ListenBrainz

ListenBrainz powers personalised recommendations, trending data, and listening history. It can also receive scrobbles.

Last.fm

Last.fm provides listening data for recommendations and receives scrobbles. Authentication uses OAuth, so you’ll be redirected to Last.fm to authorise the connection.

After saving your API key and secret, use the authentication flow in the Last.fm settings tab to link your account.

Scrobbling

The Scrobbling tab controls whether MusicSeerr reports your listens to external services. You can enable or disable scrobbling independently for Last.fm and ListenBrainz. Both can run at the same time.

When scrobbling is active, MusicSeerr sends now-playing updates at the start of each track and submits the scrobble once the track finishes.

Music Source

The Music Source tab lets you choose which service to use as the primary source for listening data on the Home and Discover pages. Options are ListenBrainz or Last.fm.

Release Preferences

Configure which release types you’re interested in (albums, singles, EPs, etc.) and regional preferences. These affect what shows up in discovery and search results.

YouTube

YouTube integration lets MusicSeerr play tracks that aren’t available through your other sources.

Local Files

Mount your music directory to enable local file browsing and playback.

Advanced Settings

The Advanced and Cache tabs control caching, HTTP timeouts, and batch processing. These rarely need adjustment, but the options are there if you need them.

• Cache TTLs for library, search, metadata, and discovery data
• HTTP connection and request timeouts for external services
• Batch sizes and concurrency for sync operations
• Memory cache limits and cleanup intervals
• Discover Queue behaviour (auto-build, queue size)

User Management

MusicSeerr is a multi-user application. The first account created during setup is an admin. Additional users are managed from Settings > Users (admin only).

Users can manage their own profile (display name, avatar) and view/revoke their own sessions from the profile page.

Security

Settings > Security (admin only) exposes authentication and transport security options.

Password Breach Checking (HIBP)

When enabled, new passwords are checked against the Have I Been Pwned breach database using the k-anonymity API. Only the first 5 characters of the password’s SHA-1 hash are transmitted — the full password never leaves the server. Enabled by default.

For air-gapped or offline installs, you can supply the path to a local copy of the HIBP hash file (download the “ordered by hash” version from haveibeenpwned.com, ~35 GB). When a local path is configured, no outbound network calls are made.

HSTS (Strict-Transport-Security)

Only relevant if you serve MusicSeerr over HTTPS via a reverse proxy. Leave disabled for plain HTTP installs. When behind HTTPS, set a max-age to instruct browsers to always use HTTPS. Start with a shorter value (e.g. 30 days) and increase once confident.

OIDC (OpenID Connect)

Any OIDC provider that supports the authorization code flow works (Authelia, Keycloak, Authentik, Google, etc.).

1. In your provider, create a new OIDC client. Set the redirect URI to https://your-musicseerr-url/api/v1/auth/oidc/callback.
2. In Settings > Security, enter your provider’s Issuer URL, Client ID, and Client Secret.
3. Save — an SSO button will appear on the login page.

OIDC supports PKCE (S256) out of the box, so public clients without a secret work without extra configuration.

Users who sign in via OIDC are created automatically on first login and assigned the User role by default. An admin can promote them from Settings > Users.

Plex SSO

Connect Plex under Settings > Plex. You can sign in with Plex OAuth or paste in a token manually. Once connected, choose the music libraries to include. If you pick more than one, MusicSeerr merges them into a single library view.

Users can also sign in with their Plex account if Plex SSO is enabled. MusicSeerr verifies that the user has access to your Plex server before creating their account.

Environment Variables

Volume Mounts