Getting started
Do I need a Soulseek account? Only for slskd, which needs one. Synthseek talks only to slskd’s HTTP API and holds no Soulseek credentials of its own.
Do I need any API keys to start? No. The music catalog needs none. Everything else is optional. An AcoustID key is free and is the one worth getting, because without it Synthseek cannot verify by listening that a downloaded file really is what you asked for.
Can I run it without slskd? Yes. slskd comes first by default, but any other source you enable can deliver, and the yt-dlp fallback is on from the start. The setup wizard still asks for slskd, and lets you continue past a failed connection test.
Does it work on a Raspberry Pi?
There is an arm64 image, built and smoke tested natively.
Permissions and paths
Startup warns that /downloads or /music is not accessible.
The user Synthseek runs as, set by PUID and PGID, does not own those folders on the host. The container log names the offending path and the ownership fix, and downloads, or the music meant for that library path, wait until you apply it. Synthseek takes ownership of its own /data volume at boot, and never changes ownership or permissions on your music and downloads volumes.
My library is on a NAS or an external drive and mounts read-only. Synthseek still boots and browsing works, and it says so at startup. Imports into the library will fail while it stays read-only, so fix the ownership before requesting anything.
The container used to crash with a chown error on /music.
Fixed in 1.2.1. Your music and downloads volumes are no longer chowned recursively; instead the folders are probed at boot and a clear diagnostic is emitted. Boot is also instant on large libraries, since nothing walks them.
Downloads
Everything is stuck at queued and nothing downloads. Check whether the queue is paused first. Pausing is in memory, so a restart clears it, and pending work drains automatically on boot. If it is not paused, check that your download sources are reachable, from their panels under Download sources.
A track says “not found”. No enabled source had a candidate that passed scoring. Turn on the wanted sweep to have Synthseek keep trying on its own, with attempts spaced further apart the longer a track stays missing.
A track says “wrong file”. What arrived positively contradicted what you asked for, and Synthseek refused to put it in your library. The file is in the review queue, where you can listen to it and decide. That exact source and file pairing is excluded from future searches, so the retry looks elsewhere.
A track says “storage problem”. The problem is on your machine, not the source. Usually a full disk or a downloads folder that stopped being writable. These failures do not consume retry budget, so once you fix the underlying problem the tracks are still waiting.
A track says it timed out. A step ran out of the time it was given, so nothing was settled about that track either way. It is retried automatically. If it keeps happening on the same tracks, raise that timeout. Each source’s own timeouts are in its panel under Download sources, and the download and import timeouts are under Download engine.
Downloads were working and now nothing gets through. Check the queue is not paused, then check the review queue. If verification is rejecting everything, something is systematically wrong with what is arriving. Each held file in the review queue shows why it was rejected, which will tell you what is going on.
Can I stop the yt-dlp fallback? Yes. Settings, then Download sources. You can also choose which sources to try, and in what order, per request.
Library and imports
Files downloaded but nothing appears in my library.
Filing may be disabled, in which case files stay in the downloads folder. Check both ENABLE_LIBRARY_IMPORT and the older ENABLE_BEETS_IMPORT, since either one set to false turns it off. Otherwise check the log for the import phase.
An artist appears twice in my library. Two causes. A past bug stored names in a simplified form, and updating merges those. More often, two programs are writing into the same music root under different naming conventions, typically Lidarr using MusicBrainz spelling and Synthseek using the catalog’s. Check which program created each folder before treating it as a bug.
Can I import music I already have? Yes, three ways. Drag files or zip archives in. Connect a library source such as Spotify and import from it. Or import a playlist file in JSPF, XSPF, or Exportify CSV.
Does a quality upgrade delete my old file?
No. It is moved to a recycle bin under /data before the replacement is imported, and that move is verified before anything else happens. You can see what the bin is holding and put any of it back from Settings, then Maintenance, then Recycle bin. The bin empties itself after thirty days by default.
Playlists and media servers
My Plex playlist has fewer tracks than Synthseek shows. Three possible causes, covered in detail on the Integrations page: the tracks are not scanned into Plex yet, the titles did not match, or Plex genuinely holds a different version. Reconciling again fixes the first two.
Will syncing remove tracks I added to a server’s playlist by hand? Not on its own. Sync only adds. The one exception is a playlist kept in sync with its source: a track removed there is removed from the server’s copy too.
I renamed a playlist on my media server. Will Synthseek fight me? No. Renames flow both ways. Whichever side changed most recently wins, and Synthseek tracks a baseline so it can tell a remote rename from a local one.
Listening
How do I actually listen to my library? In the web app itself, through your media server, or straight from Synthseek with any Subsonic-compatible app. The web app needs nothing turned on: press play on a track in your library. For a music app, turn on Music players in Settings, then Apps & API keys. Create a credential, then paste the address, your username and that credential into the app.
Does the web player pick up where I left off? Yes, and not only in the browser. Your queue and your position are kept on the server, so a reload brings them back where you stopped. It is the same queue your Subsonic app uses, so you can leave a queue on your phone and find it in the browser. Favourites are the same mark in both, and what you play can be sent on to Last.fm or ListenBrainz once you connect one.
Do I need a media server for that? No. That is the point of it. A media server remains useful for everything else it does, but it is no longer the only way to hear what Synthseek downloaded.
Can my music app change things in Synthseek, or only play them? It can change things, and that is deliberate. Favourites, playlists, what you played and the queue you left behind are all written back. The app and the web app agree with each other instead of each keeping a private copy. Three limits are worth knowing. Favourites are per person, so yours are invisible to everyone else on the instance. What you are playing right now is not: any music app on the instance can see who is listening to what, which is how the Subsonic protocol defines that feature. And deleting a playlist from a music app deletes the playlist only. The tracks stay in your library, even the ones downloaded for that playlist that live nowhere else. Deleting the music itself is a web app action, where you are asked to confirm it.
Some tracks do not show up in my music app. A track is offered when Synthseek has its file on record, or when a connected media server holds it. Music you copied into the library folder yourself is found by the library scan and then identified in small batches, after which it behaves like any other track. A file it cannot recognise waits under Settings, then Library, then Scan, behind Review files, where you can match it to an album or a song. Synthseek works out where each existing track’s file is by scanning the library, on its schedule or whenever you start a scan yourself. Anything it has not placed yet stays out of the list until it has. A track whose file was moved or deleted stays listed until Synthseek records its new location. Until then it fails when you press play, unless a connected media server holds it. The Music players card shows how many tracks your music app can play and how many it cannot.
Playback takes a while to start on some albums. By default files are served exactly as they are, and a lossless track can be forty megabytes or more. The wait is your network moving the file rather than the server thinking. If your app offers a streaming-quality or bitrate setting, use it: Synthseek converts on the fly to what you asked for. A converted track weighs about a megabyte per minute at 128 kbps, however large the original was. A five-minute lossless track arrives as roughly five megabytes instead of twenty-seven or more. The one limit is that converted playback cannot be seeked mid-track. The progress bar still moves, you just cannot drag it. Original-quality playback seeks normally.
Users
How do I add my household? Settings, then Members & access. Add local accounts, or import from your Plex server.
Can I stop people downloading anything they like? Turn on approval for members. Their requests are held until an administrator approves them. Promote the people you trust to the trusted role so they bypass it. To limit how much rather than what, set download quotas.
Can members see each other’s settings? No. Administrator sections are hidden entirely.
Assistants
My assistant cannot connect.
It almost always needs PUBLIC_BASE_URL set to a public HTTPS address. Cloud-hosted assistants call back over the internet and cannot reach a local address.
Can an assistant see my API keys or passwords? No. An assistant only ever sees secret values masked, settings tools included.
Can an assistant act on someone else’s library? No. A connection is scoped to the member who created it, with their role’s permissions.
Upgrading
What should I do before a major upgrade?
Back up /data. Synthseek takes its own snapshot before any schema change and validates the migration on a copy first, but a backup you control is a different guarantee.
A migration failed. Is my data gone?
A snapshot is written to /data/backups before any schema change, so you can always go back. Where there was room for a copy-validated upgrade, your live database was never modified and the failed copy is kept for inspection. Either way you get the snapshot and the last twenty lines of the migration log in the startup output.
I am on 1.x. What do I need to do?
See the upgrade notes at the top of the 2.0.0 entry on the Patch Notes page. In short: keep your integration environment variables for one boot so they migrate into Settings, and set the three ADMIN_MIGRATION_* variables so your existing data gets an owner.
Privacy
Does Synthseek call home? No. It makes no requests to any Synthseek-operated service. Beyond the services you configured, it uses keyless ones by default for catalog, artwork, metadata, and lyrics. It checks the public container registry for new versions, fetches the public patch-notes file, and refreshes the bundled yt-dlp from the Python package index. While the yt-dlp fallback, SoundCloud or the Internet Archive is enabled, it reaches the sites it downloads from.
Where does my data live?
In SQLite, under /data, on your machine. Nothing is stored elsewhere.