Where configuration lives
Synthseek has two configuration surfaces, and the split is deliberate.
Settings, in the application, holds everything you might reasonably change: credentials, engine tuning, behaviour switches. It lives in the database, applies live without a restart, and is the source of truth.
Environment variables hold bootstrap values only: where the database is, what port to listen on, which folders to use, the secret that signs sessions. These cannot live in the database, because they are needed before the database is open.
Settings, by section
General
Available to every member.
| Setting | What it does |
|---|---|
| Theme | Synthseek, Midnight, or Ocean. |
| Language | English, Español, Deutsch, or Français. Switches in place. |
| API keys | Create and revoke keys for assistant connections. Shown once at creation. |
| MCP | The public URL of your instance, and connection guidance for assistants. |
Members
Administrators only. Covered on the Users and Permissions page. The approval gate lives here too:
| Setting | Default | What it does |
|---|---|---|
| Require approval for members | Off | Hold a plain member’s requests until an administrator approves them. |
Profile
Your own account. Username, email, password, avatar, connected accounts.
Updates
The patch notes timeline, and whether a newer version is available.
Integrations
Administrators only.
slskd. URL, API key, connection status, and the banned-peer list.
Download sources. Enable, disable, and prioritise slskd and yt-dlp. The yt-dlp tuning is on the Download Sources page.
Plex. Connection status, a reconnect button that signs you in at plex.tv and lets you pick a server, and the server URL that sign-in resolved, shown read-only. Plus two independent behaviour switches:
| Setting | Default | What it does |
|---|---|---|
| Library scan | On | Ask Plex to rescan after an import. |
| Playlist sync | On | Create and reconcile playlists on Plex. |
And how mirrored playlists are named:
| Setting | Default | What it does |
|---|---|---|
| Playlist username affix | Off | Prefix or suffix a media server playlist with its owner’s username. |
| Separator | _ | The character between the name and the affix. |
Lidarr. URL, API key, and the quality and metadata profiles available for delegation.
Metadata and artwork. All optional, all free:
| Key | What it unlocks |
|---|---|
| AcoustID | Verifying a download by its audio, and identifying a track for tagging when other methods cannot. The most valuable one. |
| Last.fm | Similar artists, global charts, and your scrobble history. |
| fanart.tv | High quality artist images. |
| MusicBrainz contact email | A higher rate limit against MusicBrainz. |
| Songlink | A higher rate limit for cross-platform link imports. |
| Discogs | Additional metadata depth on the content detail views. |
Library sources. Connect Spotify to import your existing library. Requires a Spotify client ID and a public base URL, since the OAuth callback comes back over the internet.
Engine
Administrators only. Most cards have a reset to defaults.
Queue
| Setting | Default | Range |
|---|---|---|
| Maximum queue size | 1000 | 10 to 10000 |
| Concurrent searches | 3 | 1 to 10 |
| Concurrent pending imports | 6 | 1 to 20 |
Timeouts
| Setting | Default | Range |
|---|---|---|
| Search phase | 15 seconds | 5s to 120s |
| Download phase | 20 minutes | 1m to 60m |
| Import phase | 5 minutes | 30s to 60m |
| Peer unresponsive | 2 minutes | 15s to 15m |
| Queue wait, active peer | 8 minutes | 30s to 30m |
| Queue wait, idle peer | 12 minutes | 30s to 60m |
Import
| Setting | Default | What it does |
|---|---|---|
| Metadata confidence threshold | 50 | How closely a file’s tags must match your request before it is accepted. Raise it to reject more, lower it to accept more. |
The Download Engine page covers what happens to a file these checks refuse.
Quality
| Setting | Default | What it does |
|---|---|---|
| Upgrades enabled | On | Allow replacing a library file with a better copy. |
| Recycle bin retention | 30 days | How long a replaced file stays recoverable. 1 to 365. |
Alongside them, what the recycle bin currently holds, and a button to empty it.
Quarantine
| Setting | Default | What it does |
|---|---|---|
| AcoustID identity gate | On | Fingerprint the audio and identify it before import, so a file whose tags look right but whose contents are something else is refused. Needs an AcoustID key. |
| Auto-ban after failed attempts | 0, meaning off | Ban a peer after this many failures. |
Below them, the list of current entries with the reason for each, and a link to the banned-peer list. A quarantined pairing stays excluded until you remove that entry, clear the list, or approve the held file it came from. Reasons are: wrong file, verification failed, fingerprint mismatch, tag mismatch, duration mismatch, and tags unreadable.
Wanted
| Setting | Default | Range |
|---|---|---|
| Enabled | Off | |
| Attempts per run | 10 | 1 to 50 |
| Maximum attempts per track | 8 | 1 to 20 |
Smart search
Custom mood keywords, which extend the built-in mood classification with terms of your own.
Jobs
Administrators only. Covered on the Operations page.
Logs
Administrators only. Covered on the Operations page. The log level lives here:
| Setting | Default | What it does |
|---|---|---|
| Log level | INFO | Applied live, no restart. |
Settings that live outside Settings
Two live where you use them rather than in a settings section.
| Setting | Default | Where |
|---|---|---|
| Review queue retention | 14 days | The footer of the review queue on the Requests screen. 1 to 365. |
| Per-request format, bitrate, matching, speed, source | See Features | The request window, stored on the request itself. |
Environment variables
Required
| Variable | What it is |
|---|---|
AUTH_SECRET | Signs sessions. At least 32 characters. Generate with openssl rand -base64 48. Changing it logs everyone out. |
Container identity and paths
| Variable | Default | What it is |
|---|---|---|
PUID | 1000 | The user Synthseek runs as. Must own your mounted folders. |
PGID | 1000 | The group Synthseek runs as. |
WEB_UI_PORT | 4400 | The port the web interface listens on. |
DATABASE_URL | file:/data/db/synthseek.db | Where the database lives. |
DOWNLOADS_COMPLETE_PATH | /downloads | Where slskd puts completed downloads. Must be writable. |
MUSIC_LIBRARY_PATH | /music | Your organised library. Read-only is a supported degraded mode. |
LOGS_PATH | /data/logs | Where logs are written. |
IMPORTS_PATH | /data/imports | Staging for drag-and-drop uploads. |
RECYCLE_BIN_PATH | /data/recycle | Where replaced files go. |
ARTWORK_CACHE_PATH | /data/artwork-cache | Disk cache for proxied artwork. |
Sessions and cookies
| Variable | Default | What it is |
|---|---|---|
SESSION_DURATION_HOURS | 720 | Thirty days. Range 1 to 8760. |
COOKIE_NAME | synthseek_session | The session cookie name. |
COOKIE_SECURE | false | Set true when behind an HTTPS reverse proxy. |
PLEX_CLIENT_IDENTIFIER | synthseek | Advertised during Plex sign-in. |
Public reachability
| Variable | What it is |
|---|---|
PUBLIC_BASE_URL | The public HTTPS address this instance is reachable at. Required for assistant connectors and for the Spotify OAuth callback, both of which call back over the internet. Leave empty for local-only use. |
Bootstrap credentials
These exist for one situation: upgrading a 1.x instance, where environment variables were the only way to configure anything. On the first boot after the upgrade each one is copied into Settings, and from then on Settings is the source of truth and the variable is never read again. Keep them for that one boot, then remove them.
A fresh install needs none of them. The setup wizard collects the same values and writes them to the same place. Leave them out, because setting either slskd variable also records the instance as an upgrade from before 2.0.0 rather than a new one.
SLSKD_API_URL, SLSKD_API_KEY, PLEX_URL, PLEX_TOKEN, LASTFM_API_KEY, FANART_API_KEY, ACOUSTID_API_KEY, MUSICBRAINZ_CONTACT_EMAIL, SONGLINK_API_KEY.
Tagging
| Variable | Default | What it is |
|---|---|---|
ENABLE_BEETS_IMPORT | true | Whether to tag and file at all. False leaves files in the downloads folder. |
USE_MUSIC_BRAINZ | true | Identify tracks against MusicBrainz when tagging. |
USE_ACOUSTIC_ID | true | Identify tracks by their audio when tagging. |
BEETS_COMMAND | beet | Path to the beets executable. |
BEETS_CONFIG | /data/config/beets-config.yaml | Path to the beets configuration. A default is created on first boot, and an updated example is written alongside it on every boot. |
FPCALC_PATH | fpcalc | Path to the fingerprinting binary. |
One-shot migration
Only when upgrading an existing single-user 1.x instance. Set these on the first boot so your existing library gets an owner, then remove them.
ADMIN_MIGRATION_EMAIL, ADMIN_MIGRATION_USERNAME, ADMIN_MIGRATION_PASSWORD.
The container refuses to start with a clear message if existing data is present and these are missing.