Advanced download tool for Soulseek, soon a client.
Advanced download tool for Soulseek, soon a client.
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.
Download a release for your OS from the releases page.
Create a config file named sockseek.conf in one of these locations:
~/.config/sockseek/sockseek.conf%APPDATA%\sockseek\sockseek.confMinimal 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 = flacIf 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" -sOr download an album interactively (-t):
sockseek "Artist - Album Title" -tIf 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.
sockseek "Song Title" --song
sockseek "Artist - Song Title" --songThe hyphen - determines what part of the input is the artist and title, which can be important for ranking and filtering. See Search string.
sockseek "Album Title"
sockseek "Artist - Album Title"Again, prefer to separate artist from album title with - when providing both.
sockseek "Artist - Album Title" -tsockseek "https://www.youtube.com/playlist?list=blah"Check the tracks before downloading a 5000-item long megalist:
sockseek "input" -n 10 --print jobs-fullsockseek "artist=Artist Name" -agtGroups the albums and sorts by popularity; may also include compilations.
sockseek "Artist - Album Title" --pref-format flac,wavsockseek "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.
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-artistThese 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 10Use 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-tol 10, or --length-tol -1 to disable length filtering entirely.--remove-ft or --regex can help clean it up.Use --print results-full to inspect what Soulseek returned without downloading anything.
The input type is usually determined automatically. You can also manually set it with --input-type.
The following input types are accepted:
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.
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.
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.
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 123456For 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 jobsSockseek 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 --ptspotify-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)
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.
A MusicBrainz.org URL for a release, release group, or collection.
/release/... URL is treated as a single album download with a strict track count./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./collection/... URL is treated as a list of albums, downloading each release contained within the collection.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.
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 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=blahThe conditions are added on top of th
No open issues yet, or sync has not completed.