feat(slskd): add Soulseek (slskd) release source, building on #1335 (#1428)

## Add Soulseek (slskd) as a release source, building on #1335

This is @dskvr's work from #1335 rebased onto current `main`, with my
changes on top. #1335 has been quiet since 2026-09-13 and I needed the
changes below, so I carried it forward instead of starting over. Their
two commits are the first two in this branch with their authorship
intact, and the source plugin, handler, API client, settings tab, tests,
`ReleaseProtocol.SOULSEEK`, test client compose file and frontend bits
are all theirs. I haven't changed how a search turns into releases
beyond what is listed here.

If @dskvr would rather keep #1335 alive and take these as commits on
their branch, I can do that instead and close this.

### What I changed

**Downloads survive other apps using the same slskd.** The handler found
its files by listing slskd's downloads, and another app on the same
instance (SoulSync here) sends `DELETE
/transfers/downloads/all/completed` after each of its batches. Once that
ran, a finished download no longer appeared in the list and the task
never saw it complete, even though the files were on disk. With the new
`SLSKD_ISOLATE_DOWNLOADS` setting (on by default) each task:

- enqueues one batch (`POST /transfers/downloads/batches`) into its own
folder, `<SLSKD_DESTINATION_PREFIX>/<task id>`
- polls each transfer by id, which slskd still answers after the list
has been cleared
- decides it is done from the files on disk (sizes, not names), with the
`/events` log as a fallback when the transfers are gone and the files
aren't visible yet
- copies out of that folder, and removes it only if
`SLSKD_KEEP_COMPLETED` is off and the import worked

With isolation off the handler behaves as it did in #1335. If the batch
endpoint isn't there (404/405) it falls back to the original per-file
enqueue.

**Source changes.** m4b/m4a files are their own release next to loose
chapter files, so auto-download can prefer one file over a chapter set.
Results from the query variants are merged per peer. The folder text is
exposed as `extra["author"]` and `extra["title_raw"]`, which is what
auto-download's strict match and pack detection read. `is_available()`
also needs an API key now.

**Smaller fixes.** Cancelling while files are still being located now
removes the transfer records it created. In the settings tab, a cleared
form field is no longer replaced by the saved value when testing the
connection. The new settings are in `docs/environment-variables.md`.

### Testing

`tests/slskd` has 192 passing and 6 live tests that skip without an
instance. I wrote the new tests first and checked the handler and source
rules by breaking them and confirming a test failed. Ruff is clean. On
the whole suite the only failures are 4 in `tests/download` that import
`seleniumbase`, which isn't installed in my environment, and they fail
the same on `main`.

I've been running this on my own deployment against slskd 0.26.0 behind
a VPN, with SoulSync active on a second instance. A search returned a
couple hundred results from about 70 peers, an epub came down and was
imported, and auto-download fetched five audiobooks as single m4b files.
That is a day of use, so I don't know how it behaves on other slskd
versions or on Windows path mappings.

---------

Co-authored-by: sandwich <dskvr@users.noreply.github.com>
Co-authored-by: sandwich <299465+dskvr@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
authored and GitHub committed 2026-10-20 01:33:12 -04:00
1 parent 5669b0686a
commit bb1655238a
22 files changed
+5434 -2

No files matched your search

+124
View File
@@ -16,6 +16,7 @@ This document lists all configuration options that can be set via environment va
- [Advanced](#advanced)
- [Prowlarr](#prowlarr)
- [Newznab](#newznab)
- [Soulseek (slskd)](#soulseek-slskd)
- [AudiobookBay](#audiobookbay)
- [Libgen Search](#libgen-search)
- [IRC](#irc)
@@ -1498,6 +1499,129 @@ Automatically retry search without category filtering if no results are found
</details>
## Soulseek (slskd)
| Variable | Description | Type | Default |
|----------|-------------|------|---------|
| `SLSKD_ENABLED` | Enable searching and downloading books through slskd | boolean | `false` |
| `SLSKD_URL` | Base URL of the slskd web interface | string | _none_ |
| `SLSKD_API_KEY` | An API key from slskd's configuration (web.authentication.api_keys) with the readwrite role | string (secret) | _none_ |
| `SLSKD_DOWNLOAD_PATH` | Where slskd's completed downloads folder is mounted inside Shelfmark. Leave empty when both containers see it at the same path, or use Settings > Advanced > Remote Path Mappings with client 'slskd'. | string | _none_ |
| `SLSKD_ISOLATE_DOWNLOADS` | Download into a folder of its own inside slskd's downloads folder (needs slskd 0.26 or newer). Other apps using the same slskd cannot mix files with it or lose track of it when they clear slskd's list of finished transfers, and Shelfmark confirms a download by the files on disk. | boolean | `true` |
| `SLSKD_DESTINATION_PREFIX` | The folder, inside slskd's downloads folder, that holds one folder per download. It must not climb out of slskd's downloads folder. | string | `shelfmark` |
| `SLSKD_KEEP_COMPLETED` | Leave the finished files (and their transfer records) in slskd after Shelfmark copies them to your library, so they stay shared with other Soulseek users. Turn off to delete them once imported. | boolean | `true` |
| `SLSKD_SEARCH_TIMEOUT` | How long a Soulseek search collects peer responses. Longer waits find more peers but make every search slower. | number | `15` |
| `SLSKD_RESPONSE_LIMIT` | Stop a search early once this many peers have answered | number | `100` |
| `SLSKD_QUEUE_TIMEOUT_MINUTES` | Give up when the peer has not started sending within this long. Set to 0 to wait indefinitely. | number | `60` |
| `SLSKD_REMOVE_COMPLETED` | Clear the transfer from slskd's download list after Shelfmark imports it. Applies when each download does not get its own folder. | boolean | `true` |
<details>
<summary>Detailed descriptions</summary>
#### `SLSKD_ENABLED`
**Enable Soulseek source**
Enable searching and downloading books through slskd
- **Type:** boolean
- **Default:** `false`
#### `SLSKD_URL`
**slskd URL**
Base URL of the slskd web interface
- **Type:** string
- **Default:** _none_
#### `SLSKD_API_KEY`
**API Key**
An API key from slskd's configuration (web.authentication.api_keys) with the readwrite role
- **Type:** string (secret)
- **Default:** _none_
#### `SLSKD_DOWNLOAD_PATH`
**Downloads Path**
Where slskd's completed downloads folder is mounted inside Shelfmark. Leave empty when both containers see it at the same path, or use Settings > Advanced > Remote Path Mappings with client 'slskd'.
- **Type:** string
- **Default:** _none_
#### `SLSKD_ISOLATE_DOWNLOADS`
**Give each download its own folder**
Download into a folder of its own inside slskd's downloads folder (needs slskd 0.26 or newer). Other apps using the same slskd cannot mix files with it or lose track of it when they clear slskd's list of finished transfers, and Shelfmark confirms a download by the files on disk.
- **Type:** boolean
- **Default:** `true`
#### `SLSKD_DESTINATION_PREFIX`
**Download Folder**
The folder, inside slskd's downloads folder, that holds one folder per download. It must not climb out of slskd's downloads folder.
- **Type:** string
- **Default:** `shelfmark`
#### `SLSKD_KEEP_COMPLETED`
**Keep finished files in slskd**
Leave the finished files (and their transfer records) in slskd after Shelfmark copies them to your library, so they stay shared with other Soulseek users. Turn off to delete them once imported.
- **Type:** boolean
- **Default:** `true`
#### `SLSKD_SEARCH_TIMEOUT`
**Search Wait (seconds)**
How long a Soulseek search collects peer responses. Longer waits find more peers but make every search slower.
- **Type:** number
- **Default:** `15`
- **Constraints:** min: 3, max: 120
#### `SLSKD_RESPONSE_LIMIT`
**Max Peer Responses**
Stop a search early once this many peers have answered
- **Type:** number
- **Default:** `100`
- **Constraints:** min: 10, max: 1000
#### `SLSKD_QUEUE_TIMEOUT_MINUTES`
**Queue Timeout (minutes)**
Give up when the peer has not started sending within this long. Set to 0 to wait indefinitely.
- **Type:** number
- **Default:** `60`
- **Constraints:** min: 0, max: 1440
#### `SLSKD_REMOVE_COMPLETED`
**Remove completed transfers from slskd**
Clear the transfer from slskd's download list after Shelfmark imports it. Applies when each download does not get its own folder.
- **Type:** boolean
- **Default:** `true`
</details>
## AudiobookBay
| Variable | Description | Type | Default |