Sockseek
Sockseek is a command-line downloader for Soulseek. Point it at a search query, Spotify or YouTube playlist, CSV file, or any other supported input; it searches the network, ranks candidate files using your preferences, and downloads the best match (automatically or interactively). It is scriptable and 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 another Soulseek client, use 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
[!NOTE]
Sockseek does not share your music folders yet. To keep the Soulseek network healthy, it's good to share your collection with a regular client like Nicotine+ or slskd.
By the way, the upcoming version 4.0 implements a full Soulseek client, including sharing and a UI.
Common workflows
Download a song
Use the --song/-s flag:
sockseek "Song Title" -s
sockseek "Artist - Song Title" -s
The hyphen - determines what part of the input is the artist and title, which can be important for ranking and filtering (see also search string syntax).
Download an album
String inputs are treated as album downloads by default:
sockseek "Album Title"
sockseek "Artist - Album Title"
As in the song case, prefer to separate artist from album title with - when providing both in the query.
Download an album interactively
Add the --interactive/-t flag to pick albums before downloading:
sockseek "Artist - Album Title" -t
Download a playlist
Download playlists from streaming services or local list files like so:
sockseek "https://www.youtube.com/playlist?list=blah"
sockseek "https://open.spotify.com/playlist/id"
sockseek "/path/to/tracks.csv"
See input types for all supported sources. It's a good idea to check the metadata of the first few tracks before downloading your 10'000 song megalist:
sockseek "your-input" -n 20 --print jobs-full
Download all albums by an artist interactively
Aggregate mode (-g) can group results by album, giving you several folder choices for each one. Albums which are shared the most are sorted first. In interactive mode (-t), you can pick which albums to download and which particular version to use. Run it like this:
sockseek "artist=Artist Name" -gt
Note that this may also include compilations the artist appeared in.
Prefer lossless, but accept other formats
You can make it prefer lossless files while still accepting other formats when no lossless version exists, like this:
sockseek "Artist - Album Title" --pref-format flac,wav
To ban lossy files altogether, use --format instead of --pref-format. Note that format lists are unordered; flac,wav is equivalent to wav,flac and does not change the sorting. See file conditions for more information about ranking and filtering downloads.
Skipping existing items
For multi-item inputs like YouTube or Spotify playlists and CSV or list files, Sockseek automatically writes an index file next to the downloads, which means that successfully downloaded tracks and albums will be skipped on next runs. If you want a shared index, use the --index-path option or config field.
Sockseek can also skip items found in a music library, without any pre-existing index files:
sockseek "playlist.csv" --skip-music-dir "path/to/music"
More examples
More niche examples can be found here.
About failed or incorrect downloads
Sockseek searches the Soulseek P2P network. Sources like Spotify and YouTube are only used as metadata sources; no audio is downloaded from them. It usually does a good job downloading items, provided they actually exist on the network. The results returned by Soulseek of course depend on spelling, peers, etc. Read this section if you're dealing with missing or incorrect downloads.
Index
Input types
The input type is usually determined automatically. You can also manually set it with --input-type.
The following input types are supported:
CSV file
A path to a local CSV file listing songs or albums.
In the CSV file, rows with a track title are song downloads, and rows without a title are treated as album downloads. Only a title or album column is required in the CSV file (extra info may improve search results). If the columns have common names (like '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.
See CSV options for all options.
YouTube
A YouTube playlist URL.
The default method to retrieve playlists might not reliably return all videos. If you're having issues, 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).
See YouTube options for all options.
Spotify
Spotify inputs support:
- Public and private playlist URLs
- Album URLs
- Liked songs, with
sockseek spotify-likes
- Liked albums, with
sockseek spotify-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, you can export the Spotify playlist
with a Spotify-to-CSV converter and pass the CSV file to Sockseek instead.
See Spotify options for all options.
Using Credentials
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 action that requires auth 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 it 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 (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
Bandcamp inputs support:
- Track URLs
- Album URLs
- Artist URLs, to download all albums by the artist.
- Wishlist URLs, to download all albums on the wishlist.
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
MusicBrainz inputs support:
/release/... URLs/release-group/... URLs, where it picks the most common version of the album./collection/... URLs, to download a list of albums.
SoundCloud
SoundCloud inputs support:
- Track URLs
- Public and private playlist URLs
Requires a SoundCloud OAuth token, passed with --soundcloud-token, also for public items.
When a track has no publisher artist, the artist is taken from titles like "Artist - Title", falling back to the uploader's name.
Getting the OAuth token
- Log in to https://soundcloud.com in your browser.
- Open the developer tools (F12) and go to the Storage tab (Application in Chrome).
- Under Cookies > https://soundcloud.com, copy the value of
oauth_token.
Pass it with --soundcloud-token, or put it in your config file:
soundcloud-token = <your-token>
Soulseek Link
A direct path to a shared item starting with slsk://.
Paths ending in / are treated as album/folder downloads.
Search string
A string input is a name of the track, album, or artist to search for. They come in these forms:
-
Arbitrary search queries (like what you would type in the Soulseek search bar), e.g. sockseek "blah blah".
This is equivalent to sockseek "album=blah blah" by default, and to sockseek "title=blah blah" when using -s/--song mode.
-
An artist-album or artist-song combination, separated by a hyphen with spaces -:
sockseek "Artist - Album" downloads an albumsockseek "Artist - Song" -s downloads a song
It's always better to split the artist from song/album like this when you want to provide an artist due to ranking and filtering.
This is equivalent to sockseek "artist=Artist, album=Album" in the first case, and to sockseek "artist=Artist, title=Song" in the second case.
-
A comma-separated list of properties, like title=Song Name, artist=Artist Name, length=215.
With an album field (and no title) it's treated as an album download. With a title field it's treated as a song download (even if it includes an album field).
Accepted fields are:
- Song title
title
- Artist name
artist
- Album name
album
- Song
length (in seconds)
Notes:
- You can combine the second and third form, e.g.
Artist - Song, length=123 is the same as artist=Artist, title=Song, length=123 in --song mode.
- You can use
"artist=Artist, title=Song" --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
A path to a local text file listing items of any supported input type. List inputs must be manually activated with --input-type=list.
Each line in the list file must be of this form:
Any input type conditions (optional) pref. conditions (optional)
Here is an example list file:
"Artist - Album" "strict-album=true; album-track-count>=13" "br >= 320"
# Treat string input as song download with the s: prefix
s:"Artist - Song" strict-title=true
# 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. Lines starting with # are treated as comments and ignored.
Download modes
Sources usually decide for themselves whether they contain songs or albums. String inputs are treated as albums by default. There are four main download modes:
Song
Song mode is the default for playlists from streaming platforms and CSV song lists, and downloads one file per item. Use -s/--song for string/list input that should be treated as a song search.
Example:
sockseek "Artist - Song Name" -s
Album
In Album mode, Sockseek downloads whole folders. It is the default for string inputs and album sources such as Spotify/Bandcamp album links and CSV album rows. Use -t to pick interactively.
Example:
sockseek "Artist - Album Name" -t
See Album options for album-specific options.
Album Aggregate
Album aggregate mode is activated when -g/--aggregate is enabled for album inputs. In this mode, Sockseek will attempt to group folders returned by Soulseek and download one of each distinct album, starting with the one shared by the most peers.
Note that --min-shares-aggregate is set to 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 -t/--interactive.
Example:
sockseek "artist=Artist Name" -gt
See Aggregate options for aggregate options.
Song Aggregate
Song aggregate mode is enabled with --aggregate --song (or -gs for short). Sockseek will attempt to group files returned by Soulseek and download one of each distinct song, starting with the one shared by the most peers.
As in album aggregate mode, --min-shares-aggregate is set to 2 by default, meaning that songs shared by only one user will be ignored. This mode is useful for downloading all songs by an artist available on Soulseek.
Example:
sockseek "artist=Artist Name" -gs
See Aggregate options for aggregate options.
Daemon / remote mode
Preparing the stage for v4, which adds a full Soulseek client & UI and is currently under development.
Right now, daemon mode exposes the download engine for remote CLI use.
Start it:
sockseek daemon
It uses the same config/profile system as the CLI. By default, it listens on localhost only on port 5030. You can add --server-ip 0.0.0.0 to listen for all IPs, and configure the port with --server-port.
Once the daemon is running, use --remote <url> to run the CLI against it:
sockseek "Artist - Title" --remote http://127.0.0.1:5030
See daemon and remote mode options.
Configuration
Config Location
Sockseek will look for a file named sockseek.conf in the following locations:
~/.config/sockseek/sockseek.conf (Any platform)%APPDATA%\sockseek\sockseek.conf (Windows only)$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
Sockseek supports configuration profiles:
[lossless]
pref-format = flac,wav
To activate the above profile, use --profile lossless. This will apply all of its options. Your manual CLI options still take precedence.
To list all configured profiles, run --profile help.
Auto-profiles
Profiles can be activated automatically based on a few simple conditions. For example:
# 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"|"soundcloud"|"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. By contrast, conditions without the pref prefix are mandatory. For example, --format flac will reject non-flac files entirely.
Note: Format conditions are UNORDERED! --pref-format mp3,flac is the same as flac,mp3.
The default required conditions accept common 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
# Prefer files whose paths contain the supplied title and album.
# Changing these is not recommended.
pref-strict-title = true
pref-strict-album = true
For album downloads, conditions like format, bitrate and sample rate operate based on coverage: 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 the conditions.
See the options reference for all filtering and ranking options.
Conditions can also be supplied as a semicolon-delimited string with --cond and --pref, e.g.:
--cond "br>=320; format=mp3,ogg; sr<96000; album-track-count>=8"
For debugging, you can run a song search with --print results-full to reveal the sorting logic.
Note on availability of metadata
Some info may be unavailable depending on the client used by the peer (like the bitrate). This is why if you set a --min-bitrate, Sockseek will still accept any file with unknown bitrate as a precaution.
To reject all files where one or more of the checked properties is null (unknown), use --strict-conditions.
This flag should be used with care: It's easy to accidentally exclude all files from users with
certain clients. For example, because the standard Soulseek client does not broadcast the bitrate,
enabling --strict-conditions and setting a --min-bitrate will effectively exclude all files shared by users with the standard client(!). Even if you don't add a required min-bitrate, this option will still result in all those shares getting ranked at the bottom due to the default pref- bitrate checks above.
Name format
Sockseek can format the downloaded filenames using --name-format <yourformat>. Variables enclosed in {} will be replaced by the corresponding file tag value.
Name format supports subdirectories as well as conditional expressions like {tag1|tag2} - If
tag1 is null, use tag2 (can be chained). Examples:
{artist} - {title}
Always name it 'Artist - Title'. Because some files on Soulseek are untagged, the
following is generally preferred:{artist( - )title|filename}
Everything inside round parentheses () inside braces {} is treated as a raw string and ignored in the null check. Here, if artist and title are both not null, name it 'Artist - Title', otherwise use the original filename.{albumartist(/)album(/)track(. )title|(missing-tags/)slsk-foldername(/)slsk-filename}
Sort files into artist/album folders if all tags are present, otherwise put them in
the 'missing-tags' folder.
Available variables
The following values are read from the downloaded file's tags:
artist First artist
artists Artists, joined with '&'
albumartist First album artist
albumartists Album artists, joined with '&'
title Track title
album Album name
year Track year
track Track number
disc Disc number
length Track length (in seconds)
The following values are taken from the input source (CSV file data, Spotify, etc):
sartist Source artist
stitle Source track title
salbum Source album name
slength Source track length
uri Track URI
snum Source item number (1-indexed, including offset)
row/line Line number (1-indexed, only for CSV or list input)
Other variables:
type Track type
state Track state
failure-reason Reason for failure if any
is-audio If track is audio (true/false)
artist-maybe-wrong If artist might be incorrect (true/false)
slsk-filename Soulseek filename without extension
slsk-foldername Soulseek folder name
extractor Name of the extractor used
input Input string
item-name Name of the playlist/source
default-folder Default Sockseek folder name
bindir Base application directory
outputdir Output directory (--output-dir)
configdir Active config file directory
path Download file path (or folder if album)
path-noext Download file path without extension
ext File extension
On-Complete Actions
The --on-complete option allows executing commands after a track or album is downloaded. Multiple actions can be chained using the + prefix (note the space after +).
Syntax: --on-complete [options] -- command
Hint: You can use --mock-files-dir to test your commands (see Testing Options).
Every on-complete command must include the -- delimiter. Sockseek options go before it; everything after it is the command passed to the OS.
When passing an on-complete action on the command line, quote the whole value so the delimiter is part of the --on-complete argument:
--on-complete "when=success scope=album -- notify-send \"Downloaded\" \"{path}\""
Options
when= omitted - Same as when=completedwhen=completed - Execute on success or fail, if the item wasn't skippedwhen=success - Execute only for successful downloadswhen=failure - Execute for failed or partially successful downloadswhen=skipped - Execute for skipped jobswhen=already-exists - Execute only for already-existing skipped jobswhen=not-found-last-time - Execute only for not-found-last-time skipped jobswhen=cancelled - Execute only for cancelled jobswhen=any - Execute for every terminal outcomescope=track - Execute only for track-level completionsscope=album - Execute only for album-level completionshidden - Hide the command windowshell - Use shell executelock - Serialize this action across jobsupdate-index - Read stdout as success;new_path, failed, or ignored;new_path to update the track/album entry in the index and playlist. failed clears the stored path; ignored;new_path leaves the state unchanged and updates only the path.
Variables
The available variables are the same as in name-format, with the following additions:
{exitcode} - Previous command's exit code{stdout} - Previous command's stdout{stderr} - Previous command's stderr{first-exitcode} - First command's exit code{first-stdout} - First command's stdout{first-stderr} - First command's stderr
Sockseek captures stdout/stderr for ordinary on-complete commands, so chained commands can use output variables from the previous ones. Commands launched with shell cannot use stdout/stderr.
For album-only (scope=album) actions, tag-based variables such as {title}, {artist}, and {album} are read from the first audio file in the album.
Examples
Send a Linux desktop notification for album downloads:
on-complete = when=success scope=album -- notify-send "Downloaded: {album}" "{path}"
Search album art with Cover Fetcher:
on-complete = when=success scope=album hidden -- cmd /c start "" "path\to\CoverFetcher.exe" --from-dir "{path}"
Queue downloaded audio files in foobar2000:
on-complete = when=success hidden -- cmd /c if {is-audio}==true start "" "path\to\foobar2000.exe" /immediate /add "{path}"
Convert downloaded audio files to MP3 on Windows (requires ffmpeg):
# Check if file is audio and not already MP3
on-complete = when=success hidden -- cmd /c if "{is-audio}"=="true" if /i not "{ext}"==".mp3" if not exist "{path-noext}.mp3" echo true
# Convert to MP3 if check passed
on-complete = + when=success hidden -- cmd /c if /i "{stdout}"=="true" (ffmpeg -i "{path}" -q:a 0 "{path-noext}.mp3" && echo success)
# Delete original and update index if conversion succeeded
on-complete = + when=success hidden update-index -- cmd /c if /i "{stdout}"=="success" (del "{path}" & echo "ignored;{path-noext}.mp3")
Shortcuts & interactive mode
CLI Shortcuts
You can use these at any time while things are searching or downloading:
c cancel specific job by id or all jobs
t try next candidate for a job id
i get detailed info about job by id
CLI Interactive Prompt Shortcuts
Interactive mode for albums can be enabled with -t/--interactive. It allows you to pick the desired folder or download only specific files from it, rather than automatically downloading the best match.
Key bindings:
Up/p previous folder
Down/n next folder
Enter/d download selected folder
y download folder and disable interactive mode
r retrieve all files in the folder
s/q/Esc skip current album
Q/S skip current and all remaining new album prompts
h print this help text
d:1,2,3 download specific files
d:start-end download a range of files
f filter folders containing files matching query
cd .. load parent folder
cd subdir go to subfolder
More Examples
Given a playlist of songs, download the albums
When album metadata is available and you have a playlist of songs, you can use the --upgrade-to-album option to download albums instead of songs:
sockseek "https://open.spotify.com/playlist/id" --upgrade-to-album
Album downloads are of course deduplicated; you won't get many copies of an album just because you have 20 tracks from the same album in the playlist.
Use yt-dlp as fallback
Sockseek can fall back to downloading song playlists from YouTube using yt-dlp (must be installed separately) when no items are found on Soulseek. It runs a YouTube search first, unless your input is a YouTube playlist, in which case it just downloads directly by ID. Use --yt-dlp (and --yt-dlp-argument if needed):
sockseek "your-song-playlist" --yt-dlp
You can also use any custom downloader as fallback with on-complete actions.
Retrieving deleted YouTube item names
YouTube inputs support the experimental --get-deleted option, which attempts to browse the web archive to find deleted video names in a playlist:
bash "https://youtube.com/playlist/id" --get-deleted
Show artist songs which you don't have
Song aggregate mode can be used in combination with --skip-music-dir to show all songs by an artist on Soulseek which are not in your music library:
sockseek "artist=MC MENTAL" -s -g --skip-music-dir "path/to/music" --print results
Remove the --print results part to download those songs.
Create an automatic wishlist downloader
You can easily build a wishlist downloader. Create a file named wishlist.txt, and add some items with list file syntax:
"Artist - Some Album"
"Artist - Album With Conditions" strict-album=true;album-track-count>=5
"Another Album" banned-users=user-sharing-bad-files
"Album With Pref. Conditions" format=mp3,flac format=flac
s:"MC MENTAL - MC MENTAL @ HIS BEST, length=242"
Add a profile to your sockseek.conf:
[wishlist]
# Will look for wishlist.txt in the same folder as your sockseek.conf
input = {configdir}/wishlist.txt
input-type = list
log-file = {configdir}/wishlist.log
# The index will keep track of successfully downloaded items to skip
# them in the next runs:
index-path = {configdir}/wishlist-index.csv
# Uncomment this line to remove successfully downloaded items from
# wishlist.txt directly:
# remove-from-source = true
# Add some global conditions for your wishlist, if you want:
format = flac,mp3
min-bitrate = 200
# To keep searching for a flac version of "Album With Pref. Conditions"
# in the above list even after an mp3 version has been downloaded, make
# it check the local version:
# skip-check-pref-cond = true
# Note that this requires the downloaded files to remain in the same
# spot or for the index to be updated after any moves, e.g. via
# on-complete update-index.
Now set up a cron job (on Linux) scheduled task (on Windows) to periodically run Sockseek with the following option:
sockseek --profile wishlist
You can also just manually run it, for example in interactive mode (-t).
Tips
Rate limits
The Soulseek server bans users for 30 minutes if too many searches are performed within a short timespan. Sockseek has a search limiter which can be adjusted with --searches-per-time and --searches-renew-time (when the limit is reached, the status of the downloads will be 'Waiting'). By default it is configured to allow up to 34 searches every 220 seconds.
Why are some of my downloads wrong or missing?
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.
It downloaded a wrong song or album.
To tighten matching for song downloads, add one or more strict filters:
sockseek "https://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 filter 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. You can also add --strict-album to require the album name in the folder path.
It didn't find a song or album.
This usually means one of two things:
- Your searches are non-standard, like an uncommon artist spelling. You can try cleaning them up with options like
--regex and --remove-ft. See also the next section.
- Whatever you're looking for is just not available on Soulseek.
For songs, there is also the possibility of a 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.
Use --print results-full to inspect what Soulseek returned without downloading anything.
Searching
- It's always best to provide the least input necessary to uniquely identify an album or song.
- Sometimes including the artist can be undesirable (e.g. "Various Artists"). For spotify or bandcamp inputs, you can remove the artist name with
--regex A:.*.
- Use
--remove-ft to remove "feat." or "ft." artists
- You can download an entire album based on the name of one of its songs by searching for that name in album mode:
"artist=ARTIST, title=SONG TITLE" --album.
- When searching for a single song with a string input, you can provide the album name in addition. The album name will not be included in the query, but search results containing it will be preferred (due to pref-strict-album).
- When dealing with YouTube playlists you may want to remove any text in parentheses (like (Video)), as well as "Official" and "Lyrics" with
--regex "[\[\(].*?[\]\)]|(?i:lyrics)|(?i:official)"
Speeding things up
The following options will make it go faster, but may decrease search result quality or cause instability:
--fast-search skips waiting until the search completes and downloads as soon as a file matching the preferred conditions is found (songs only)--search-timeout decrease to make searches end faster at the possible cost of fewer results--concurrent-jobs controls how many leaf jobs can run at once (default: 20)--concurrent-searches controls how many Soulseek searches can run at once (default: 2)--concurrent-extractors controls how many inputs can be extracted at once (default: 4)--max-stale-time is set to 30 seconds by default, Sockseek will wait a long time before giving up on a file once it's chosen.
Testing Options
You can test almost any aspect of the search and downloading logic with --mock-files-dir and pointing it to a local directory containing audio files. This directory will then be used instead of searching and downloading from Soulseek. Example:
sockseek "Artist - Album" -t --mock-files-dir /path/to/dir
If you plan to use a large music library, you might want to add --mock-files-no-read-tags to improve the initial loading performance. But note that reading tags is required when filtering by metadata such as length or bitrate.
Options reference
Most used flags at a glance:
-s, --song Treat string input as song search
-t, --interactive Pick from album results before downloading
-g, --aggregate Download distinct songs/albums from grouped results
-o, --output-dir <path> Download directory
--pref-format <formats> Preferred formats for ranking, e.g. flac,wav. Unordered.
--format <formats> Required accepted formats. Unordered.
--album-track-count <count> Required number of audio files when downloading albums
--skip-music-dir <path> Skip tracks already in a music library
--profile <names> Apply configuration profile(s)
--name-format <format> Organize files using a path template
--strict-title/artist/album Require title in filename, artist in path, album in folder path
--upgrade-to-album Upgrade song-shaped source results to album jobs
Required Arguments
<input> A URL, search string, Soulseek link, or path to a local
CSV/list file. Run `--help input` to view the accepted inputs.
Can also be passed with -i, --input <input>
--user <username> Soulseek username
--pass <password> Soulseek password
General Options
-o, --output-dir <path> Download directory
--input-type <type> [csv|youtube|spotify|bandcamp|string|list|soulseek|
musicbrainz] (default: auto)
-s, --song Song mode for string input
--name-format <format> Name format for downloaded tracks. See `--help name-format`
--invalid-replace-str <str> Replacement string for invalid path characters (default: space)
-n, --number <maxtracks> Download the first n tracks of a playlist
--offset <offset> Skip a specified number of tracks
-r, --reverse Download tracks in reverse order
-c, --config <path> Set config file location. Set to 'none' to ignore config
--no-config Ignore any config file
--profile <names> Configuration profile(s) to use. See `--help config`.
--concurrent-jobs <num> Max concurrent leaf jobs (default: 20)
--concurrent-searches <num> Max concurrent Soulseek searches (default: 2)
--concurrent-extractors <num> Max concurrent input extractors (default: 4)
--write-playlist Create an m3u playlist file in the output directory
--playlist-path <path> Override default path for m3u playlist file
--write-index Create/update the Sockseek index (default when using
compatible inputs)
--no-write-index Do not create/update the Sockseek index
--index-path <path> Override default path for Sockseek index
--no-incomplete-ext Save files with their final name instead of a temporary
`.incomplete` extension.
--no-skip-existing Do not skip downloaded tracks
--skip-mode-output-dir <mode> How to match files in the output dir: name|tag|index
(default: index)
--skip-check-cond Check file conditions when skipping existing files. If the
local candidate does not exist or does not satisfy the
required conditions, the item will not be skipped.
--skip-check-pref-cond Check preferred conditions when skipping existing files
--skip-music-dir <path> Also skip downloading tracks found in a music library
--skip-mode-music-dir <mode> How to match files in --skip-music-dir: name|tag
(default: name)
--skip-not-found Skip searching for tracks that weren't found on Soulseek
during the last run.
--listen-port <port> Port for incoming connections (default: 49998)
--no-listen Disable the incoming connection listener
--connect-timeout <ms> Timeout used when logging in to Soulseek (default: 20000ms)
--user-description <desc> Optional description text for your Soulseek account
--shared-files <int> Number of files you share on Soulseek (default: 0)
--shared-folders <int> Number of folders you share on Soulseek (default: 0)
--on-complete <command> Run a command when a download completes. See `--help
on-complete`
Daemon / Remote Options
sockseek daemon Start the HTTP/SignalR daemon instead of running a download
--server-ip <ip> IP/interface for the daemon HTTP API (default: 127.0.0.1)
--server-port <port> Port for the daemon HTTP API (default: 5030)
--remote <url> Use an existing daemon instead of running locally
--detach With --remote, submit and print the workflow ID without waiting
Search Options
--fast-search Begin downloading as soon as a file satisfying the preferred
conditions is found. Only for song downloads.
--fast-search-delay <ms> Delay before accepting fast-search candidates (default: 300)
--fast-search-min-up-speed <n> Minimum upload speed for fast-search candidates (default: 1)
--remove-ft Remove 'feat.' and everything after before searching
--remove-brackets Remove square-bracketed text from track titles before search
--extract-artist Extract artist/title from titles like "Artist - Title"
--parse-title <template> Parse title fields with placeholders like {artist} - {title}
--regex <regex> Remove a regexp from all track titles and artist names.
Optionally specify a replacement regex after a semicolon.
Add 'T:', 'A:' or 'L:' at the start to only apply this to
the track title, artist, or album respectively. Prefix with
'+ ' to append a regex rule instead of replacing prior rules.
--artist-maybe-wrong Performs an additional search without the artist name.
Useful for sources like SoundCloud where the "artist"
could just be an uploader. Note that when downloading a
YouTube playlist via URL, this option is set automatically
on a per-track basis, so it is best kept off in that case.
--fallback-level <0-3> Try simpler searches when no results are found.
0: normal searches only
1: retry with the first artist, without feat./ft. credits
2: also try each remaining artist (default)
3: also try broader searches for artist/album/title only and
relax length requirements.
--max-fallback-attempts <num> Maximum fallback searches when no results are found (def: 8)
-d, --desperate Equivalent to --fallback-level 3
--no-remove-special-chars Keep special characters in Soulseek search terms
--max-retries <num> Max download retries per item (default: 10)
--unknown-error-retries <num> Extra retries for unknown/transient errors (default: 2)
--fails-to-downrank <num> Number of fails to downrank a user's shares (default: 1)
--fails-to-ignore <num> Number of fails to ban/ignore a user's shares (default: 2)
--yt-dlp Use yt-dlp to download songs that weren't found on
Soulseek. yt-dlp must be available from the command line.
Works on any input containing songs; albums not supported.
Runs a YouTube search and downloads the first result. For
YouTube inputs, downloads directly by ID instead.
--yt-dlp-argument <str> The command line arguments when running yt-dlp. Default:
"{id}" -f bestaudio/best -ci -o "{savepath-noext}.%(ext)s" -x
Available vars are: {id}, {savedir}, {savepath},
{savepath-noext}.
Note that -x causes yt-dlp to download webms in case ffmpeg
is unavailable.
--search-timeout <ms> Max search time in ms (default: 5000)
--max-stale-time <ms> Max download time without progress in ms (default: 30000)
--searches-per-time <num> Max searches per time interval. Higher values may cause
30-minute bans, see `--help notes`. (default: 34)
--searches-renew-time <sec> Controls how often available searches are replenished.
See `--help notes`. (default: 220)
Spotify Options
--spotify-id <id> Spotify client ID
--spotify-secret <secret> Spotify client secret
--spotify-token <token> Spotify access token
--spotify-refresh <token> Spotify refresh token
--remove-from-source Remove downloaded tracks from source playlist
YouTube Options
--youtube-key <key> YouTube Data API key
--get-deleted Attempt to retrieve titles of deleted videos from wayback
machine. Requires yt-dlp.
--deleted-only Only retrieve & download deleted music.
Bandcamp Options
--from-html <path> Read Bandcamp page HTML from a local file
SoundCloud Options
--soundcloud-token <token> SoundCloud OAuth token
CSV File Options
--artist-col <name> Artist column name
--title-col <name> Track title column name
--album-col <name> Album column name
--length-col <name> Track length column name
--album-track-count-col <name> Album track count column name (sets --album-track-count)
--yt-desc-col <name> YouTube description column (improves --yt-parse)
--yt-id-col <name> YouTube video id column (improves --yt-parse)
--time-format <format> Time format in Length column of the CSV file (e.g h:m:s.ms
for durations like 1:04:35.123). Default: s
--yt-parse Enable if the CSV contains YouTube video titles and channel
names; attempt to parse them into title and artist names.
--remove-from-source Remove downloaded tracks from source CSV file
Filtering & Ranking Options
--format <formats> Required file format(s). Comma-separated, unordered. See
also --pref-format for soft preferences.
--length-tol <sec> Length tolerance in seconds, -1 to disable (default: 3)
--min-bitrate <rate> Minimum file bitrate
--max-bitrate <rate> Maximum file bitrate
--min-samplerate <rate> Minimum file sample rate
--max-samplerate <rate> Maximum file sample rate
--min-bitdepth <depth> Minimum bit depth
--max-bitdepth <depth> Maximum bit depth
--strict-title Require track title in filename
--strict-artist Require artist in path. When the input artist contains
multiple artists split by ;, requires one only.
--strict-album Require album in folder path
--banned-users <list> Comma-separated list of users to ignore
--allowed-users <list> Comma-separated list of users to allow
--cond <conditions> Semicolon-delimited required conditions
--pref-format <formats> Preferred format(s) for ranking. Use --format to require
formats strictly. Comma-separated, unordered. (def.: mp3)
--pref-length-tol <sec> Preferred length tolerance, -1 to disable (default: 3)
--pref-min-bitrate <rate> Preferred minimum bitrate (default: 200)
--pref-max-bitrate <rate> Preferred maximum bitrate (default: 2500)
--pref-min-samplerate <rate> Preferred minimum sample rate
--pref-max-samplerate <rate> Preferred maximum sample rate (default: 48000)
--pref-min-bitdepth <depth> Preferred minimum bit depth
--pref-max-bitdepth <depth> Preferred maximum bit depth
--pref-strict-title Prefer filenames containing the track title
--pref-strict-artist Prefer file paths containing artist name
--pref-strict-album Prefer folder paths containing album name
--pref-banned-users <list> Comma-separated list of users to downrank
--pref-allowed-users <list> Comma-separated list of users to prefer
--pref <conditions> Semicolon-delimited preferred conditions
--strict-conditions Skip files with missing properties instead of accepting by
default; if --min-bitrate is set, ignores any files with
unknown bitrate. Warning: Available props depend on client
Album Download Options
-a, --album Album mode for string input and string lines in list files.
--upgrade-to-album Upgrade song-shaped sources such as CSV song rows or Spotify
playlist tracks into album jobs when possible.
-t, --interactive Interactively select folders. See --help shortcuts.
--album-track-count <num> Specify the exact number of tracks in the album. Add a + or
- for inequalities, e.g '5+' for five or more tracks.
Spotify/Bandcamp inputs automatically set album-track-count
to n+.
--strict-album-quality Require every audio file in an album folder to satisfy
required quality conditions such as --format, bitrate, sample
rate, and bit depth. By default mixed-quality folders are
ranked by coverage.
--min-album-track-count <num> Minimum number of tracks in an album folder
--max-album-track-count <num> Maximum number of tracks in an album folder
--extract-max-track-count Set maximum album track count from extracted sources
--album-track-count-max-retries Max retries when album track count fails (default: 5)
--album-art <option> Retrieve additional images after downloading the album:
'default': No additional images
'largest': Download from the folder with the largest image
'most': Download from the folder containing the most images
--album-art-only Only download album art for the provided album; implies
album-art=largest when album-art is default
--browse-folder Automatically browse user shares to get all files in the
selected album folder (default)
--no-browse-folder Do not automatically browse user shares to get all files in
the folder
--incomplete-album-action <a> What to do with completed album files when the album
does not complete. Values: 'move' to move to {configured
output dir}/failed (default), 'move:<path>' to move to a
custom path, 'delete' to delete them, or 'keep' to leave
them where they are.
Aggregate Download Options
-g, --aggregate Aggregate download mode: Find and download all distinct
songs associated with the provided artist, album, or title.
--aggregate-length-tol <tol> Max length tolerance in seconds to consider two tracks or
albums equal. (Default: 3)
--min-shares-aggregate <num> Minimum number of shares of a track or album for it to be
downloaded in aggregate mode. (Default: 2)
--relax-filtering Slightly relax file filtering in aggregate mode to include
more results
Printing & Debug Options
-v, --verbose Print extra debug info
-vv, --trace Print trace-level debug info
--debug Alias for --verbose
--log-file <path> Write debug info to a specified file
--no-progress Disable progress bars/percentages, only simple printing
--progress-json Print progress events as JSON lines
--print <option> Print jobs or search results instead of downloading:
'jobs': Print input jobs after extraction/preprocessing
'jobs-full': Print extended information about input jobs
'results': Print search results satisfying file conditions
'results-full': Print search results including full paths.
'json': Print first result in json format
'json-all': Print json of all results in sorted order
'link': Print first result slsk:// link
'index': Print Sockseek index as formatted json
'index-failed': Print failed downloads from Sockseek index
--print-jobs Alias for --print jobs
--print-jobs-full Alias for --print jobs-full
--print-results Alias for --print results
--print-results-full Alias for --print results-full
--print-link Alias for --print link
--print-json Alias for --print json
--print-json-full Alias for --print json-all
--mock-files-dir <path> Directory containing files to simulate download results
--mock-files-no-read-tags Only read filenames when simulating (much faster)
--mock-files-slow Simulate slow mock-file downloads and folder browses
--mock-files-fail-downloads <n> Simulate n failed mock-file downloads
CLI Notes
- Flags can be explicitly disabled by setting them to false, e.g.
--interactive false.
- Single-character flags can be combined, e.g.
-at for -a -t.
- Acronyms of two- and
--three-word-flags like --twf are also accepted. E.g. --Mbr for --max-bitrate.
Docker
Docker documentation has moved to docs/docker.md.
