sldl

A smart and configurable downloader for Soulseek. Built with Soulseek.NET.

Features

• Accepts various input sources like CSV files, Spotify or YouTube URLs, or standard text queries
• Can download individual songs, playlists, albums, or full artist discographies
• Intelligently selects the best album or song based on user configuration and heuristics
• For those who don't trust full auto downloading, album downloads can be interactive. The best results will be listed first.
• Special "aggregate" modes which can list all distinct songs or albums by a given artist available on Soulseek, sorted by popularity
• Can skip downloading songs or albums found in a given music directory
• Configuration profiles and auto profiles
• Arbitratry name formatting for downloaded files
• On-complete commands that can run when a download succeeds or fails

Setup

1. Head to the releases page and get an appropriate release for your system.
2. Put your soulseek username and password in the configuration file.
3. Try it:

   sldl "Artist - Your Favorite Album" -at
   

   This will search for the album and show an interactive UI for result selection.
   For more examples, see the usage examples section.

Important

[!NOTE] sldl doesn't share your music folders by itself. To keep the Soulseek network healthy over the long term, please also share your collection using a regular client like Nicotine+ or slskd.

[!NOTE] Because it's not possible to run the same account on two separate clients simultaneously, it is recommended to use sldl with a separate Soulseek account to avoid connection problems.

Index

• Options
• Input types
  • CSV file
  • YouTube
  • Spotify
  • Bandcamp
  • MusicBrainz
  • Soulseek Link
  • Search string
  • List file
• Download modes
  • Normal
  • Album
  • Aggregate
  • Album Aggregate
• Configuration
• File conditions
• Name format
• On-Complete Actions
• Shortcuts & interactive mode
• Examples
• Notes
• Tips
• Docker

Options

<!-- sldl-help:start(main) -->

Required Arguments

<input>                         A url, search string, or path to a local CSV 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

-p, --path <path>               Download directory
--input-type <type>             [csv|youtube|spotify|bandcamp|string|list] (default: auto)
--name-format <format>          Name format for downloaded tracks. See `--help name-format`
    
-n, --number <maxtracks>        Download the first n tracks of a playlist
-o, --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
--profile <names>               Configuration profile(s) to use. See `--help config`.
--concurrent-downloads <num>    Max concurrent downloads for normal mode (default: 2)
--write-playlist                Create an m3u playlist file in the output directory
--playlist-path <path>          Override default path for m3u playlist file
--no-incomplete-ext             Save files with their final name instead of a temporary
                                `.incomplete` extension.
    
--no-skip-existing              Do not skip downloaded tracks
--no-write-index                Do not create a file indexing all downloaded tracks
--index-path <path>             Override default path for sldl index
--skip-check-cond               Check file conditions when skipping existing files
--skip-check-pref-cond          Check preferred conditions when skipping existing files  
--skip-music-dir <path>         Also skip downloading tracks found in a music library by
                                comparing filenames. Not 100% reliable.
--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)
--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`

Search Options

--fast-search                   Begin downloading as soon as a file satisfying the preferred
                                conditions is found. Only for normal download mode.
--remove-ft                     Remove 'feat.' and everything after before searching
--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.
--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.
-d, --desperate                 Tries harder to find the desired track by searching for the
                                artist/album/title only, then filtering. (slower search)
--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 tracks that weren't found on
                                Soulseek. yt-dlp must be available from the command line.
--yt-dlp-argument <str>         The command line arguments when running yt-dlp. Default:
                                "{id}" -f bestaudio/best -cix -o "{savepath}.%(ext)s"
                                Available vars are: {id}, {savedir}, {savepath} (w/o ext).
                                Warning: If you change the -o parameter, sldl won't be able
                                to index the downloaded files.
                                Note that -x causes yt-dlp to download webms in case ffmpeg
                                is unavailable.

--search-timeout <ms>           Max search time in ms (default: 6000)
--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 search`. (default: 34)
--searches-renew-time <sec>     Controls how often available searches are replenished.
                                See `--help search`. (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.

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

File Condition Options

--format <formats>              Accepted file format(s), comma-separated, without periods
--length-tol <sec>              Length tolerance in seconds
--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 <dept