slsk-batchdl

A batch downloader for Soulseek using Soulseek.NET. Accepts CSV files, Spotify & YouTube urls.

• Download tracks from a csv file:

slsk-batchdl --csv test.csv --artist-col "Artist Name(s)" --track-col "Track Name" --length-col "Duration (ms)" --time-unit ms

You can omit the column names provided they are named predictably (like in this example). Use --print-tracks before downloading to check if everything has been parsed correctly.

• Download spotify likes while skipping existing songs, and create an m3u file:

slsk-batchdl --spotify likes --m3u --skip-existing

You might need to provide an id and secret when using spotify (e.g when downloading a private playlist), which you can get here https://developer.spotify.com/dashboard/applications. Create an app, then select it and add http://localhost:48721/callback as a redirect url in the settings.

• Download the first 10 songs of a youtube playlist:

slsk-batchdl -n 10 --youtube "https://www.youtube.com/playlist?list=PLI_eFW8NAFzYAXZ5DrU6E6mQ_XfhaLBUX"

To include unavailable videos, you will need to provide an api key with --youtube-key. Get it here https://console.cloud.google.com. Create a new project, click "Enable Api" and search for "youtube data", then follow the prompts.

• Search & download a specific song, preferring flac and wav files:

slsk-batchdl "title=MC MENTAL @ HIS BEST,duration=242" --pref-format "flac,wav"

Options:

Usage: slsk-batchdl [OPTIONS]
Options:
  --user <username>              Soulseek username
  --pass <password>              Soulseek password

  --spotify <url>                Download a spotify playlist ("likes" for liked music)
  --spotify-id <id>              Your spotify client id (required for private playlists)
  --spotify-secret <sec>         Your spotify client secret (required for private playlists)

  --youtube <url>                Get tracks from a YouTube playlist
  --youtube-key <key>            Provide an API key to include unavailable uploads

  --csv <path>                   Use a csv file containing track info to download
  --artist-col <column>          Artist or uploader column name
  --title-col <column>           Title or track name column name
  --album-col <column>           Track album column name (optional for more results)
  --length-col <column>          Track duration column name (optional for better accuracy)
  --time-unit <unit>             Time unit in track duration column, ms or s (default: s)
  --yt-desc-col <column>         YT description column name (optional, use with --yt-parse)
  --yt-id-col <column>           Youtube video ID column (optional, use with --yt-parse)
  --yt-parse                     Enable if you have a csv file of YouTube video titles and
                                 channel names; attempt to parse them into title and artist

  -s --single <str>              Search & download a specific track. <str> is a simple
                                 search string, or a comma-separated list of properties:
                                 "title=Song Name,artist=Artist Name,length=215"

  -p --path <path>               Place downloaded files in custom path
  -f --folder <name>             Custom folder name (default: provided playlist name)
  -n --number <maxtracks>        Download at most n tracks of a playlist
  -o --offset <offset>           Skip a specified number of tracks
  --reverse                      Download tracks in reverse order
  --name-format <format>         Name format for downloaded tracks, e.g "{artist} - {title}"
  --m3u                          Create an m3u8 playlist file

  --pref-format <format>         Preferred file format(s), comma-separated (default: mp3)
  --pref-length-tol <tol>        Preferred length tolerance in seconds (default: 3)
  --pref-min-bitrate <rate>      Preferred minimum bitrate (default: 200)
  --pref-max-bitrate <rate>      Preferred maximum bitrate (default: 2200)
  --pref-max-samplerate <rate>   Preferred maximum sample rate (default: 96000)
  --pref-strict-title            Prefer download if filename contains track title
  --pref-strict-artist           Prefer download if filepath contains track artist
  --pref-danger-words <list>     Comma-separated list of words that must appear in either
                                 both search result and track title, or in neither of the
                                 two, case-insensitive (default:"mix, edit, dj, cover")
  --nec-format <format>          Necessary file format(s), comma-separated
  --nec-length-tol <tol>         Necessary length tolerance in seconds (default: 3)
  --nec-min-bitrate <rate>       Necessary minimum bitrate
  --nec-max-bitrate <rate>       Necessary maximum bitrate
  --nec-max-samplerate <rate>    Necessary maximum sample rate
  --nec-strict-title             Only download if filename contains track title
  --nec-strict-artist            Only download if filepath contains track artist
  --nec-danger-words <list>      Comma-separated list of words that must appear in either
                                 both search result and track title, or in neither of the
                                 two. Case-insensitive. (default:"mix, edit, dj, cover")

  --skip-existing                Skip if a track matching nec. conditions is found in the
                                 output folder or your music library (if provided)
  --skip-mode <mode>             "name": Use only filenames to check if a track exists
                                 "name-precise": Use filenames and check nec-cond (default)
                                 "tag": Use tags (slower)
                                 "tag-precise": Use tags and check all nec. cond. (slower)
  --music-dir <path>             Specify to skip downloading tracks found in a music library
                                 Use with --skip-existing
  --skip-not-found               Skip searching for tracks that weren't found on Soulseek
                                 last run
  --remove-ft                    Remove "ft." or "feat." and everything after from the
                                 track names before searching.
  --album-search                 Also search for album name before filtering for track name.
                                 Sometimes helps to find more, but slower.
  --artist-search                Also search for artist, before filtering for track name.
                                 Sometimes helps to find more, but slower.
  --no-artist-search             Also perform a search without artist name if nothing was
                                 found. Only use if the source is imprecise
                                 and the provided "artist" is possibly wrong (yt, sc)
  --no-regex-search <reg>        Also perform a search with a regex pattern removed from the
                                 titles and artist names
  --no-diacr-search              Also perform a search without diacritics
  -d --desperate                 Equivalent to enabling all additional searches
  --yt-dlp                       Use yt-dlp to download tracks that weren't found on
                                 Soulseek. yt-dlp must be available from the command line.

  --search-timeout <ms>          Maximal search time (ms, default: 6000)
  --max-stale-time <ms>          Maximal download time with no progress (ms, default: 50000)
  --concurrent-processes <num>   Max concurrent searches & downloads (default: 2)
  --display <str>                "single" (default): Show transfer state and percentage.
                                 "double": Also show a progress bar. "simple": simple

  --print-tracks                 Do not search, only print all tracks to be downloaded
  --print-results                Do not download, print search results satisfying nec. cond.
  --print-results-full           Do not download, print all search results with full path

Files satisfying pref- conditions will be preferred. Files not satisfying nec- conditions will not be downloaded. For example, --nec-length-tol is set to 3 by default, which means that files whose duration differs from the supplied duration by more than 3 seconds will not be downloaded. Increase it to download e.g a youtube playlist of music videos with intros/outros, or disable it entirely by setting it to 99999.

Supports .conf files: Create a file named slsk-batchdl.conf in the same directory as the exe and write your arguments there, e.g:

--username "fakename"
--password "fakepass"
--pref-format "flac"

Notes:

• The CSV file must be saved with , as field delimiter and " as string delimiter, encoded with UTF8
• --display single and especially double can cause the printed lines to be duplicated or overwritten on some configurations. Use simple if that's an issue. In my testing on Windows, the terminal app seems to be affected by this (unlike the old command prompt).