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
Settings has two groups. You holds what each member sets for themselves. This server holds what administrators set for everyone, and members do not see it. Changelog sits at the bottom for everyone.
The search box at the top of the sidebar finds settings by name and opens the page each one lives on. Ctrl+K, or Cmd+K on a Mac, opens the same search with a few common actions.
Account
Your username, email, avatar and password, and how much of your download quota you have used.
Appearance & language
| Setting | What it does |
|---|---|
| Theme | Synthseek, Midnight, or Ocean. |
| Language | English, Español, Deutsch, or Français. Switches in place. |
Connected accounts
Your own accounts on Spotify, Plex, Navidrome and Jellyfin, which Synthseek uses on your behalf. Each server’s row also offers to count your plays on that server.
Listening & discovery
Your Last.fm and ListenBrainz connections, which send what you play to them, and the discovery mixes each one brings to Discover. Administrators also set the Last.fm API key and shared secret here, which every member’s Last.fm connection uses.
Apps & API keys
| Setting | What it does |
|---|---|
| Music players | Turns the Subsonic API on or off, admin only, and shows the address and username a music app needs. Off by default. |
| Convert on the fly | Sends a smaller stream when a music app asks for one, admin only. On by default. |
| AI assistants | The public URL of your instance, and connection guidance for assistants. |
| API keys | Create and revoke keys for assistant connections. Shown once at creation. |
Each member creates and revokes their own credentials here; only an admin can turn the Subsonic API on.
Overview
Administrators only. What needs attention on this server, which services are connected, the setup steps still open, and the state of the background jobs. Each item links to the page that handles it.
Members & access
Administrators only. Covered on the Users and Permissions page. The approval gate and the download quotas live here too:
| Setting | Default | What it does |
|---|---|---|
| Require approval for members | Off | Hold a plain member’s requests until an administrator approves them. |
| Tracks per member | 0 | New tracks a member can request within the window. 0 is no limit. |
| Window | 7 days | The rolling number of days the track quota counts over. |
| Storage per member | 0 GB | Space a member’s music can take. 0 is no limit. |
| Whole library | 0 GB | Downloads stop once the library reaches this size. 0 is no limit. |
Notifications
Available to every member. Each member sets up their own destinations and picks what each one receives.
Everyone can send to Discord, ntfy and Telegram. Administrators can also send JSON to a webhook, or reach other services through an Apprise server. A member picks from their own downloads, their discovery mixes and their account. Administrators also get members, library, maintenance and system notifications, and can include every member’s downloads.
Messages are written in the member’s language.
On Discord, ntfy and Telegram, a download notice shows the cover art when there is one. Once PUBLIC_BASE_URL is an HTTPS address, every notification on those three also links to the page it is about.
| Setting | Default | What it does |
|---|---|---|
| ntfy server for members | Empty | Administrators only. A second ntfy server members may use. Without it, members use ntfy.sh. |
Download sources
Administrators only. Enable, disable, and order slskd, another Subsonic server, Usenet, torrent, yt-dlp, SoundCloud and the Internet Archive. Synthseek tries them from the top down. The tuning of each is on the Download Sources page.
Lidarr, at the bottom of the page, takes a request instead of downloading it: URL, API key, and the quality and metadata profiles available for delegation.
Download engine
Administrators only. Most cards have a reset to defaults.
Queue & concurrency
| Setting | Default | Range |
|---|---|---|
| Max size | 1000 | 10 to 10000 |
| Max concurrent searches | 3 | 1 to 10 |
| Max pending imports | 6 | 1 to 20 |
Timeouts
| Setting | Default | Range |
|---|---|---|
| Download phase | 20 minutes | 1m to 60m |
| Import phase | 5 minutes | 30s to 60m |
The Soulseek timeouts are with the rest of slskd’s settings, under Download sources:
| Setting | Default | Range |
|---|---|---|
| Search phase | 15 seconds | 5s to 120s |
| 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 |
|---|---|---|
| Allow quality upgrades | On | Allow replacing a library file with a better copy. |
Wanted sweep
| Setting | Default | Range |
|---|---|---|
| Enable wanted sweep | Off | |
| Tracks per sweep | 10 | 1 to 50 |
| Max sweep attempts | 8 | 1 to 20 |
Smart search
Custom mood keywords, which extend the built-in mood classification with terms of your own.
Library
Administrators only, in three tabs. Covered on the Operations page.
Paths & rules lists the folders Synthseek keeps your music in. The first one comes from MUSIC_LIBRARY_PATH. You can add more, turn one off, and choose the default, which takes music that matches no rule. A folder you add has to be mounted into the container first, like /music. Each path has its own settings:
| Setting | Default | What it does |
|---|---|---|
| Track naming | {albumartist}/{album}/<Disc {disc:02d}>/{track:02d} - {title} | The folders and filename every track is given when it is filed. |
| Rules | None | The rules that send music to this path. |
Rules lists the conditions a request can match, such as who asked for it, its genre or its release year. When several match, the one higher in the list is tried first.
Scan shows what the last library scan found, and the files it could not recognise, behind Review files.
Sources is where members’ libraries come from. Connect Spotify to import an existing library. It requires a Spotify client ID and a public base URL, since the OAuth callback comes back over the internet. Members can also import playlists from your media servers, through the account each one links under Connected accounts.
| Setting | Default | What it does |
|---|---|---|
| Check for changes every | 30 minutes | How often followed playlists and saved albums on other services are checked. 5 to 1440 minutes. |
Media & playback
Administrators only. Plex, Navidrome and Jellyfin, plus the order the player tries them in when Synthseek has no file for a track. A connected server is a place to play from, with no switch of its own.
Plex shows its 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 behaviour switches:
| Setting | Default | What it does |
|---|---|---|
| Media server rescan | On | Ask Plex to rescan after an import. |
| Sync playlists to Plex | On | Create and reconcile playlists on Plex. |
And how playlists mirrored to Plex are named:
| Setting | Default | What it does |
|---|---|---|
| Username affix | Off | Prefix or suffix a Plex playlist with its owner’s username. |
| Separator | _ | The character between the name and the affix. |
Navidrome (URL, username, password) and Jellyfin (URL, API key) each have a test button and a switch to sync playlists to that server. The switch starts off.
Metadata
Administrators only. 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. |
| fanart.tv | High quality artist images. |
| MusicBrainz contact email | A higher rate limit against MusicBrainz. |
| Songlink | A higher rate limit when turning a link from another platform, such as Spotify, into a track. |
| Discogs | Additional metadata depth on the content detail views. |
The Last.fm key and shared secret are under Listening & discovery. The key brings similar artists, global charts, and your scrobble history; the secret lets members send plays to Last.fm.
Maintenance
Administrators only. Six tabs, each holding the list it is about and, for most, the setting that governs it. Every tab carries a live count. The sidebar shows a dot on Maintenance while any tab but Downloaded albums has something waiting.
Review
The files held back because they failed verification, with the reason for each. Nothing arrives until you approve or discard. Its retention is set from the footer of the review queue.
Duplicates
Tracks with more than one copy on disk. Copies it can prove identical wait under Safe to resolve until the library scan settles them, or until you resolve them yourself. What it cannot prove waits under Needs review.
Recycle bin
| Setting | Default | What it does |
|---|---|---|
| Retention period | 30 days | How long a replaced file stays recoverable. 1 to 365. |
Alongside it, what the bin currently holds, the files it is keeping, a Restore on each one, and a button to empty it.
Downloaded albums
The albums Usenet and torrent fetched whole that are still on disk. Each shows its size and when it expires, and you can delete one or all of them.
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 audio is by a different artist is refused. Needs an AcoustID key. |
| Auto-ban threshold | 0, meaning off | Ban a peer after this many failures. Shown here, and changed with slskd’s settings under Download sources. |
Below them, the list of current entries with the reason for each, and the Banned uploaders 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, tags do not match, duration mismatch, and tags unreadable.
System status
What is limiting Synthseek right now, such as a folder it cannot write to or a music catalog that is not answering, with the fix for each. A problem clears on its own once it is fixed, and while any remains, admins see a notice at the top of Settings.
System
Administrators only, in two tabs, Jobs and Logs. Both are covered on the Operations page. The log level lives under Logs:
| Setting | Default | What it does |
|---|---|---|
| Level | INFO | Applied live, no restart. |
Changelog
The patch notes timeline, and whether a newer version is available.
Settings that live outside Settings
Two live where you use them rather than in a settings section.
| Setting | Default | Where |
|---|---|---|
| Keep for, in the review queue | 14 days | The footer of the review queue, on the Requests screen or under Maintenance. 1 to 365. |
| Per-request format, bitrate, matching, speed, sources | See Features | The request window, stored on the request itself. |
Environment variables
Required
| Variable | What it is |
|---|---|
AUTH_SECRET | Signs sessions, and encrypts the credentials music apps use. At least 32 characters. Generate with openssl rand -base64 48. Changing it logs everyone out, and any music-app credential stops working in apps that log in with the token-and-salt scheme, which most older ones do. Apps that send the credential directly keep working. Create a new credential after changing it. |
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 your download clients put completed downloads. Must be writable. |
MUSIC_LIBRARY_PATH | /music | Your first library path. Read-only is a supported degraded mode, in which imports and reorganising fail. |
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. |
HELD_IMPORTS_PATH | /data/held-imports | Where files held for review wait. |
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. Discord, ntfy and Telegram notifications link back to it. 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_LIBRARY_IMPORT | true | Whether to tag and file at all. Replaces ENABLE_BEETS_IMPORT, which is still honoured: either one set to false leaves files in the downloads folder. |
USE_ACOUSTIC_ID | true | Identify tracks by their audio when tagging. |
BEETS_COMMAND | beet | Path to the beets executable, used only for the presence check behind the Beets CLI row in Settings. |
BEETS_CONFIG | /data/config/beets-config.yaml | Path to a Beets configuration, read only to find the database of an existing Beets library and pick up its MusicBrainz identities. A default is created on first boot. |
FPCALC_PATH | fpcalc | Path to the fingerprinting binary. |
RSGAIN_PATH | rsgain | Path to the binary that measures how loud each track is, so playback can even out the volume between them. |
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.