Sockseek
Sockseek is a command-line downloader for Soulseek. Point it at a search string, Spotify playlist, YouTube playlist, CSV file, Bandcamp page, MusicBrainz release, or Soulseek link; it searches the network, ranks candidate files using your preferences, and downloads the best match (automatically or interactively). It is scriptable, configurable, and can run either as a one-shot CLI tool or as a persistent daemon.
This project was formerly named sldl (and slsk-batchdl before that). See here for why it was renamed to something dumb.
Quick Start
Download a release for your OS from the releases page.
Create a config file named sockseek.conf in one of these locations:
- Linux/macOS/Windows:
~/.config/sockseek/sockseek.conf
- Windows:
%APPDATA%\sockseek\sockseek.conf
Minimal config:
username = your-soulseek-username
password = your-soulseek-password
output-dir = path/to/your/download/folder
# Sockseek prefers mp3 by default. To prefer FLAC (will still
# fall back to mp3 if unavailable):
# pref-format = flac
If you're running a persistent Soulseek client, use Sockseek with a separate Soulseek account to avoid connection problems.
Download your first song:
sockseek "Artist - Song Title" -s
Or download an album interactively (-t):
sockseek "Artist - Album Title" -t
If a download is wrong or missing, see When downloads are wrong or missing.
[!NOTE]
Sockseek does not share your music folders yet. To keep the Soulseek network healthy, please also share your collection with a regular client like Nicotine+ or slskd.
Daemon mode is the path toward longer-running client features, but sharing is not implemented yet.
Common workflows
Download a song
sockseek "Song Title" --song
sockseek "Artist - Song Title" --song
The hyphen - determines what part of the input is the artist and title, which can be important for ranking and filtering. See Search string.
Download an album automatically
sockseek "Album Title"
sockseek "Artist - Album Title"
Again, prefer to separate artist from album title with - when providing both.
Download an album interactively
sockseek "Artist - Album Title" -t
Download a playlist
sockseek "https://www.youtube.com/playlist?list=blah"
Check the tracks before downloading a 5000-item long megalist:
sockseek "input" -n 10 --print jobs-full
Download all albums by an artist interactively
sockseek "artist=Artist Name" -agt
Groups the albums and sorts by popularity; may also include compilations.
sockseek "Artist - Album Title" --pref-format flac,wav
Skip tracks already in your music library
sockseek "playlist.csv" --skip-music-dir "path/to/music"
For multi-item inputs such as YouTube or Spotify playlists and CSV or list files, Sockseek also writes an _index.csv file next to the download output. Re-running the same input uses that index to skip items that were already downloaded, even without --skip-music-dir. Use --index-path to choose a shared or custom index location.
For more examples, see Examples.
When downloads are wrong or missing
Sockseek searches the Soulseek peer-to-peer network -- Spotify, YouTube, and similar inputs are used only as metadata sources to drive the search, not as audio sources. Most of the time, if the file you want exists on Soulseek, Sockseek will find and download it correctly.
The default settings favor recall over precision: when the correct file is available in results, it will almost always be ranked first. The tradeoff is that if it's absent and something else loosely passes the filters, that something else gets downloaded. The options below let you control where you fall on that spectrum.
A wrong song or album gets downloaded.
To tighten song matching, add one or more strict filters:
sockseek "https://open.spotify.com/playlist/blah" --strict-title --strict-artist
These require that the file path contains the song title and artist name (case-insensitive).
For album downloads, the cleanest guard is usually the expected track count:
sockseek "Artist - Album" --album-track-count 10
Use inequalities like 10+ or 12- when expanded or incomplete editions are acceptable. --strict-album requires the album name in the folder path, but track count tends to be cleaner.
A song or album isn't found at all.
Two common causes:
- Length mismatch. When using Spotify or YouTube as input, the reported length can differ from the actual file on Soulseek (like from a CD rip) by more than the default 3-second tolerance. Try
--length-tol 10, or --length-tol -1 to disable length filtering entirely.
- Naming differences. The Soulseek network returned no results for the query. Options like
--remove-ft or --regex can help clean it up.
Use --print results-full to inspect what Soulseek returned without downloading anything.
Index
The input type is usually determined automatically. You can also manually set it with --input-type.
The following input types are accepted:
CSV file
Path to a local CSV file. Use a CSV file containing track information to download a list of
songs or albums. Only the title or album column is required, but extra info may improve search
result ranking. If the columns have common names ('Artist', 'Title', 'Album', 'Length', etc)
then it's not required to manually specify them, otherwise you must provide at least --title-col or --album-col.
CSV rows determine their own shape: rows with a track title are song downloads, and rows
without a title are album downloads.
YouTube
A YouTube playlist URL. Download songs from a YouTube playlist.
Note: The default method to retrieve playlists might not reliably return all videos. To get all
videos, you can use the official API by providing a key with --youtube-key. A key can
be obtained at https://console.cloud.google.com. Create a new project, click 'Enable API' and
search for 'YouTube Data', then follow the prompts.
Spotify
Any playlist or album URL, or spotify-likes for your liked songs, or spotify-albums for liked albums.
Spotify API access now requires your own Spotify developer application for all Spotify inputs,
including public playlists. Spotify also requires the owner of that application to have an
active Spotify Premium subscription. If you do not have Premium, export the Spotify playlist
with a Spotify-to-CSV converter and pass the CSV file to Sockseek instead.
Using Credentials
Click to expand
Create a Spotify application at https://developer.spotify.com/dashboard/applications with a redirect URL http://127.0.0.1:48721/callback. The Spotify account that owns the application must have an active Premium subscription. Obtain an application ID and secret from the created application dashboard.
For public playlists and albums, pass the application credentials:
sockseek "https://open.spotify.com/playlist/id" --spotify-id 123456 --spotify-secret 123456
For private playlists, liked songs, liked albums, or --remove-from-source, start Sockseek with the obtained credentials and an authorized action to trigger the Spotify app login flow:
sockseek spotify-likes --spotify-id 123456 --spotify-secret 123456 -n 1 --print jobs
Sockseek will try to open a browser automatically but will fall back to logging the login flow URL to output. After login flow is complete Sockseek will output a token and refresh token and finish running the current command.
To skip requiring login flow every time Sockseek is used the token and refresh token can be provided to Sockseek (hint: store this info in the config file to make commands less verbose):
sockseek spotify-likes --spotify-id 123456 --spotify-secret 123456 --spotify-refresh 123456 --spotify-token 123456 -n 1 --pt
spotify-token access is only valid for 1 hour. spotify-refresh will enable Sockseek to renew access every time it is run (and can be used without including spotify-token)
Bandcamp
A Bandcamp track, album, or artist URL. Download a single track, an album, or an artist's
entire discography. Also accepts wishlist URLs. Extraction might fail due to Cloudflare; download the HTML to a local file and point Sockseek to it using --from-html in case of issues.
MusicBrainz
A MusicBrainz.org URL for a release, release group, or collection.
- A
/release/... URL is treated as a single album download with a strict track count.
- A
/release-group/... URL is also treated as a single album download. It tries to pick the most common version of the album. Sets the minimum album track count to the chosen release track count, and no maximum track count unless --extract-max-track-count is set.
- A
/collection/... URL is treated as a list of albums, downloading each release contained within the collection.
Soulseek Link
A direct path starting with slsk://. Paths ending in / are album/folder downloads;
file paths are direct single-file downloads unless --album is explicitly requested.
Search string
Name of the track, album, or artist to search for. The input can either be an arbitrary
search string (like what you would type in the Soulseek search bar), or a comma-separated
list of properties of the form title=Song Name, artist=Artist Name, length=215.
The following properties are accepted: title, artist, album, length (in seconds),
artist-maybe-wrong, album-track-count.
String input accepts a shorthand for track and album downloads: The input ARTIST - TITLE
is parsed as artist=ARTIST, album=TITLE by default, and as
artist=ARTIST, title=TITLE when run with --song.
Keyed string input is more explicit: artist=ARTIST, title=TITLE is treated as a song
download by default. Use --album if you want title= to act as an album search hint,
i.e. you want to search for an album by the name of one of its tracks.
List file
List input must be manually activated with --input-type=list. The input must be a path to a text
file containing lines of the following form:
# Any input type conditions (optional) pref. conditions (optional)
"Artist - Album" "format=mp3; br>128" "br >= 320"
# String album input:
"Artist - Album" strict-album=true;album-track-count=13
# String song input:
s:"Artist - Song" strict-title=true
# Album search using a song-title hint:
a:"artist=Artist, title=Song"
# Any other input type is also accepted:
path/to/tracks.csv
https://www.youtube.com/playlist?list=blah
The conditions are added on top of the configured conditions and can be omitted.
For string lines, unprefixed entries use the configured download mode: album by default, or song
mode when --song / song = true is set.
Download modes
Structured sources such as CSV rows, Spotify, YouTube, Bandcamp, MusicBrainz, and Soulseek links
usually decide for themselves whether they contain songs or albums. String inputs are treated as
albums by default.
Use --upgrade-to-album when a structured source gives you song entries but you want album jobs instead,
such as downloading the albums represented by a Spotify song playlist or a CSV of tracks.
Song
Downloads a single file for string input and string lines inside list files. Song mode is the default
for playlists from streaming platforms and CSV song lists. Use -s/--song for string/list input that
should be treated as a song search. To restore the pre-3.0 default behavior globally, add
song = true to your config file.
Album
Sockseek will search for the album and download an entire folder including non-audio
files. Album mode is the default for string input and string lines inside list files. It is
also used by album-shaped sources such as Spotify/Bandcamp album links and CSV rows without
a track title. Use -t to pick
interactively. See Shortcuts & interactive mode.
Album Aggregate
Activated when -g/--aggregate is enabled for album-shaped input. Sockseek will group shares and
download one of each distinct album, starting with the one shared by the most users. Note
that --min-shares-aggregate is 2 by default, meaning that albums shared by only one user
will be ignored. Album-aggregate mode can be used to determine the most common version of a particular album,
or download the most popular (or all) albums by an artist. It's recommended to pair it with --interactive. See Example for more details.
Song Aggregate
With --aggregate --song (or -gs for short), Sockseek performs an ordinary search for the input, then attempts to
group the results into distinct songs. Note that --min-shares-aggregate is 2 by default, meaning that
songs shared by only one user will be ignored.
Daemon / remote mode
Daemon mode is the first step toward running Sockseek as a persistent Soulseek client rather than a one-shot downloader.
Right now it exposes the download engine for remote CLI use; future releases may expand it with long-running client features such as sharing.
Run sockseek daemon to start the HTTP/SignalR daemon. It uses the same config/profile system as the
CLI and listens on 127.0.0.1:5030 by default.
Once the daemon is running, use --remote <url> to run the CLI as a thin client against it:
sockseek daemon --server-ip 0.0.0.0 --server-port 5030
sockseek "Artist - Title" --remote http://127.0.0.1:5030
For HTTP API, SignalR, and client integration notes, see docs/api.md.
Configuration
Config Location
Sockseek will look for a file named sockseek.conf in the following locations:
~/.config/sockseek/sockseek.conf%APPDATA%\sockseek\sockseek.conf (Windows)$XDG_CONFIG_HOME/sockseek/sockseek.conf{sockseek executable dir}/sockseek.conf
Use --config <path> to choose a config file, --config none or --no-config to skip config loading.
Syntax
Example config file:
username = your-username
password = your-password
pref-format = flac
fast-search = true
Lines starting with # will be treated as comments. Tildes in paths are expanded as the user
directory (even on Windows). Path settings also support {bindir} for the Sockseek binary directory
and {configdir} for the directory containing the active config file.
Configuration profiles
Profiles are supported:
[lossless]
pref-format = flac,wav
To activate the above profile, run --profile lossless. To list all available profiles,
run --profile help.
Profiles can be activated automatically based on a few simple conditions:
# never automatically cancel album downloads in interactive mode
[no-stale]
profile-cond = interactive && download-mode == "album"
max-stale-time = 9999999
# download to another location for YouTube
[youtube]
profile-cond = input-type == "youtube"
output-dir = ~/downloads/sockseek-youtube
The following operators are supported for use in profile-cond: &&, ||, ==, !=, !{bool}.
The following variables are available:
input-type ("youtube"|"csv"|"string"|"bandcamp"|"spotify"|"list"|"soulseek"|"musicbrainz"|"none")
download-mode ("normal"|"song"|"aggregate"|"album"|"album-aggregate")
album (bool)
aggregate (bool)
interactive (bool)
progress-json (bool)
no-progress (bool)
File conditions
pref-* options change how results are ranked; they never filter anything out. --pref-format flac
means Sockseek will prefer flac when available, but will still download mp3 if no flac is found.
To reject non-flac files entirely, use --format flac instead.
Format lists are unordered: pref-format = flac,mp3 does not prioritize flac over mp3; both are
treated as equally preferred.
The default required conditions accept common audio formats and enforce the source length when
both source and file length are known:
format = mp3,flac,ogg,m4a,opus,wav,aac,alac
length-tol = 3
The default preferred conditions are:
pref-format = mp3
pref-length-tol = 3
pref-min-bitrate = 200
pref-max-bitrate = 2500
pref-max-samplerate = 48000
pref-strict-title = true
pref-strict-album = true
In other words, by default, Sockseek will
- accept common audio files with no length metadata, or whose length differs from the supplied length by no more than 3 seconds
- prefer mp3 files with bitrate between 200 and 2500 kbps.
Moreover, it will prefer files whose paths contain the supplied title and album.
Changing the last two preferred conditions is not recommended.
In album mode, required album-track conditions (format, bitrate, sample rate, bit depth)
rank or reject whole folders instead of removing individual tracks. A folder with 9 FLAC files
and 1 MP3 is preferred over a mostly-MP3 folder, and the selected folder is still downloaded as
a whole. Use --strict-album-quality to require every audio file in the folder to satisfy those
track conditions. Here --format means the acceptable format of primary audio tracks; it does
not select ancillary files such as PDFs or logs. In default mixed-quality mode, coverage is based on the folder contents
Sockseek has seen so far; if a later folder browse reveals hidden files, the coverage can change,
but the folder is still treated as a whole. In strict mode, Sockseek retrieves the full folder when
needed and rejects the candidate before download if hidden files break the required quality
conditions.
Run a song search with --print results-full to reveal the sorting logic.
Conditions can also be supplied as a semicolon-delimited string with --cond and --pref, e.g
--cond "br>=320; format=mp3,ogg; sr<96000". Folder conditions can be included too, such as
album-track-count>=8 or required-track-title=Intro.
Some info may be unavailable depending on the client used by the peer. If (e.g) --min-bitrate
is set, then Sockseek will still accept any file with unknown bitrate. To reject all files where one
or more of the checked properties is null (unknown), enable --strict-conditions.
This flag should be used with care: It's easy to accidentally exclude all files from users with
cert
Sockseek — консольный загрузчик для пиринговой сети Soulseek. Вы указываете ему строку поиска, плейлист Spotify или YouTube, CSV-файл, страницу Bandcamp, релиз MusicBrainz или ссылку Soulseek, а он ищет по сети, ранжирует файлы-кандидаты по вашим предпочтениям и скачивает лучшее совпадение автоматически или интерактивно.