Download Sources

How sources work

A download source is an adapter. Synthseek asks each enabled source, from the top of the list down, whether it can supply a track, and takes the first one that delivers something that passes verification.

Seven sources ship today, listed in their default order.

All of them live under Settings, then Download sources. Drag a source to change the order. You can also choose which sources to try, and in what order, per request. Disabling a source moves the tracks it was fetching on to their next source, if they have one.

slskd

slskd is a Soulseek daemon with an HTTP API. It is the primary download source, and Synthseek drives it entirely through that API. Synthseek never speaks the Soulseek protocol itself and holds no Soulseek credentials.

Setting up slskd

1. Run slskd and complete its own setup, including your Soulseek account.
2. In slskd, go to Settings, then Options, then Web, and note or generate an API key.
3. Note the URL slskd’s web interface is reachable at from inside the Synthseek container. On the same Docker network this is typically http://slskd:5030.
4. In Synthseek, go to Settings, then Download sources, then Slskd. Enter the URL and the API key, and test the connection.

The shared downloads folder

slskd and Synthseek must agree on one folder.

• In slskd, this is the complete downloads directory.
• In Synthseek, this is the /downloads volume.

Both must point at the same place on the host, and the user Synthseek runs as, set by PUID and PGID, must be able to write to it. This is the most common cause of a working slskd connection that still cannot import anything.

slskd settings

Under Settings, then Download sources, then Slskd:

The same panel holds the Soulseek timeouts from the Configuration page, and Auto-ban after N failures, which bans a peer after repeated failed downloads. It is off at 0.

Another Subsonic server

Synthseek can download original files from another server that speaks the Subsonic API, such as a friend’s Navidrome or Synthseek. It is off until you set it up, and it connects to one server.

Setting it up

1. Ask the server’s owner for an account. On a Synthseek server, the owner turns on Music players and makes you a member. You then create a credential under Settings, then Apps & API keys, and use it as the API key.
2. In Synthseek, go to Settings, then Download sources, then Subsonic server. Enter the address, then the API key, or a username and password.
3. Test the connection, turn the source on and save.

For a Synthseek server the address ends in /api/v1/subsonic. For Navidrome it is usually the server itself, such as http://navidrome:4533. An address that points back at this Synthseek is refused. Downloading from a Synthseek server leaves no plays on it.

Subsonic server settings

Usenet

Usenet is another acquisition source, and it works differently enough from the per-track sources to be worth a paragraph before the setup steps. Nobody publishes single tracks on Usenet: material is posted as a whole release, so a request fetches the entire album and takes the track it needs out of it.

That has two consequences you will notice. Requesting an album downloads one release instead of hunting each track separately, which is where Usenet is at its best. And requesting a single track, if you allow it, downloads the album that track belongs to.

Because of that, Usenet is offered only for album requests unless you say otherwise, and it is off until you configure it.

What you need

Usenet needs two things Synthseek does not provide, the same way it does not provide your Soulseek account:

• A Usenet provider and an indexer. The indexer is what Synthseek searches; it must speak the Newznab API, which most do.
• SABnzbd, reachable from the Synthseek container, doing the actual downloading.

Setting it up

1. In your indexer, find your API key.
2. In SABnzbd, go to Config, then General, and note the API key there.
3. Point SABnzbd’s completed-downloads folder at the same /downloads volume Synthseek uses. This is the same requirement the slskd section describes above, and the same thing goes wrong when it is missed: downloads succeed and nothing is ever imported.
4. In Synthseek, go to Settings, then Download sources, then Usenet. Enter both addresses and both keys.

Usenet settings

Single-track requests

Off by default. While it is off, Usenet is offered only when you request an album.

Turning it on lets Usenet serve any request, at the cost the section above describes: one song means downloading its album. To keep that from being pure waste, the downloaded album stays on disk for the time set in Keep unused albums for, so another track from it costs nothing. Settings, then Maintenance, then Downloaded albums lists them.

When a release does not deliver

Usenet does not always hand over what its name promised, and Synthseek treats the outcomes differently on purpose.

A release that arrives with files but without the track you asked for is a bad release. It is remembered so the same one is not tried again for that track, and so is one SABnzbd reports it could not repair or complete. A release that arrives with nothing readable is NOT blamed, because a very recent post can still be spreading between servers. Those are retried later instead. And when the downloads folder itself cannot be read, nothing is blamed at all, because that is a problem on your side rather than the release’s.

Whatever Usenet cannot deliver falls through to your other enabled sources in the usual order.

Torrent

Torrent fetches whole album releases, the way Usenet does. It searches an indexer that speaks the Torznab API, such as Prowlarr or Jackett, and downloads through qBittorrent 5.0 or later. It is off until you set it up. Like Usenet, it serves only album requests unless you allow single tracks.

Setting it up

1. In Prowlarr or Jackett, note the indexer’s Torznab address and its API key.
2. In qBittorrent, turn on the web interface. Create an API key (qBittorrent 5.2 or later), or use its username and password.
3. Make qBittorrent save the synthseek category to the same /downloads volume Synthseek uses.
4. In Synthseek, go to Settings, then Download sources, then Torrent. Enter both addresses and the keys, and test the connection.

Downloading and seeding

Every album goes to qBittorrent as soon as it is found, and qBittorrent’s own queue settings decide how many download at once. Time an album spends in that queue does not count toward Give up after, only toward Wait in the queue for up to. Your request shows each album’s progress while it downloads.

Synthseek imports a copy of the track it needs and leaves the release seeding. A finished torrent is deleted with its files after the time you set, but only once qBittorrent has stopped seeding it. Your share limits in qBittorrent decide when that is. When a torrent stops making progress, the tracks that arrived are kept and the next source is tried for the rest. The peers see qBittorrent’s address, not Synthseek’s.

Torrent settings

The yt-dlp fallback

When the sources above it cannot deliver a track, Synthseek can fall back to yt-dlp. It is bundled in the container and enabled by default.

Video platforms change often enough to break a downloader that stands still, so the bundled yt-dlp does not stand still. The container refreshes it on every start, and if downloads start being refused while it is running, it refreshes it again without waiting for a restart. Both refreshes need outbound network access and say what they did in the log, including when they could not reach the package index. A refresh cannot invent a fix that has not been published yet, so downloads can still fail for a while after a platform change.

The fallback is deliberately conservative, because a video platform holds a great deal that is not the recording you asked for. Candidates are ranked rather than taken in the order they arrive, and one has to resemble the track you asked for on more than one count before it is accepted. How many candidates are considered, and how much slack the matching is given, are settings.

Everything downloaded through the fallback goes through exactly the same verification as anything else. It is not a trusted path.

yt-dlp settings

SoundCloud

Synthseek can also look for a track on SoundCloud, through the same bundled yt-dlp. It needs no account, and it is off until you turn it on.

Most of what SoundCloud returns for a well-known song is somebody else’s version of it: remixes, covers, sped-up or slowed edits. Synthseek skips the ones it recognises. Tracks SoundCloud offers only as a short preview, or only behind its own DRM, are left out of the search.

SoundCloud settings

The Internet Archive

Synthseek can also look for a track in the Internet Archive’s free music. It needs no account, and it is off until you turn it on.

It searches only the collections you allow in the settings below. Netlabel releases are albums independent labels published under free licences. Live recordings come from bands that let fans tape their concerts, so they are rarely the studio version. Community uploads are music anyone uploaded, and nobody checks who owns it.

A download is checked against the checksum the Internet Archive publishes for it, when there is one. When the release states its licence, the request page links to it.

Internet Archive settings

Delegating to Lidarr

Rather than downloading through a source, a request can be handed to Lidarr, which then manages it in its own catalog. Lidarr is set up at the bottom of the same page. See the Integrations page.