From 3c9faaf08e13cc410f8b0159daf4725008293496 Mon Sep 17 00:00:00 2001 From: fiso64 <64778819+fiso64@users.noreply.github.com> Date: Thu, 8 Jun 2023 12:25:13 +0200 Subject: [PATCH] Update README.md --- README.md | 194 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 114 insertions(+), 80 deletions(-) diff --git a/README.md b/README.md index 4ebc2f4..f91834f 100644 --- a/README.md +++ b/README.md @@ -2,88 +2,124 @@ A batch downloader for Soulseek using Soulseek.NET. Accepts CSV files, Spotify & YouTube urls. +- Download tracks from a csv file: ``` -Usage: slsk-batchdl.exe [OPTIONS] -Options: - -p --parent Downloaded music will be placed here - -n --name Folder / playlist name. If not specified, the name of the csv file / spotify / yt playlist is used. - --username Soulseek username - --password Soulseek password - - --spotify Download a spotify playlist. "likes" to download all your liked music. - --spotify-id Your spotify client id (use if the default fails or if playlist private) - --spotify-secret Your spotify client secret (use if the default fails or if playlist private) - - --youtube Get tracks from a YouTube playlist - --youtube-key Provide an API key if you also want to search for unavailable uploads - --no-channel-search Enable to also perform a search without channel name if nothing was found (only for yt). - - --csv Use a csv file containing track info to download - --artist-col Artist or uploader name column - --title-col Title or track name column - --album-col CSV album column name. Optional, may improve searching, slower - --length-col CSV duration column name. Recommended, will improve accuracy - --time-unit Time unit for the track duration column, ms or s (default: s) - --yt-desc-col Description column name. Use with --yt-parse. - --yt-id-col Youtube video ID column (only needed if length-col or yt-desc-col don't exist). Use with --yt-parse. - --yt-parse Enable if you have a csv file of YouTube video titles and channel names; attempt to parse. - - -s --single Search & download a specific track - -a --album Does nothing - - --pref-format Preferred file format (default: mp3) - --pref-length-tol Preferred length tolerance (if length col provided) (default: 3) - --pref-min-bitrate Preferred minimum bitrate (default: 200) - --pref-max-bitrate Preferred maximum bitrate (default: 2200) - --pref-max-samplerate Preferred maximum sample rate (default: 96000) - --pref-danger-words 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 Necessary file format - --nec-length-tolerance Necessary length tolerance (default: 3) - --nec-min-bitrate Necessary minimum bitrate - --nec-max-bitrate Necessary maximum bitrate - --nec-max-samplerate Necessary maximum sample rate - --nec-danger-words 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") - - --album-search Also search for "[Album name] [track name]". Occasionally helps to find more, slower. - --no-diacr-search Also perform a search without diacritics - --skip-existing Skip if a track matching the conditions is found in the output folder or your music library (if provided) - --skip-notfound Skip searching for tracks that weren't found in Soulseek last time - --remove-ft Remove "ft." or "feat." and everything after from the track names. - --remove-strings Comma separated list of strings to remove when searching for tracks. Case insesitive. - --music-dir Specify to also skip downloading tracks which are in your library, use with --skip-existing - --reverse Download tracks in reverse order - --skip-if-pref-failed Skip if preferred versions of a track exist but failed to download. If no pref. versions were found, download as normal. - --create-m3u Create an m3u playlist file - --m3u-only Only create an m3u playlist file with existing tracks and exit - --m3u Where to place created m3u files (--parent by default) - --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-f yt-dlp audio format (default: "bestaudio/best") - - --search-timeout Maximal search time (default: 10000) - --max-stale-time Maximal download time with no progress (default: 60000) - --concurrent-processes Max concurrent searches / downloads (default: 2) - --max-retries Maximum number of users to try downloading from before skipping track (default: 30) - - --slow-output Enable if the progress bars aren't properly updated (bug) -``` -Files satisfying `pref` conditions will be preferred. Files not satisfying `nec` conditions will not be downloaded. - -Download tracks from a csv file and create m3u: -``` -slsk-batchdl.exe -p "C:\Users\fiso64\Music\Playlists" --csv "C:\Users\fiso64\Downloads\test.csv" --username "fakename" --password "fakepass" --artist-col "Artist Name(s)" --track-col "Track Name" --length-col "Duration (ms)" --time-unit "ms" --skip-existing --create-m3u --pref-format "flac" +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 spotify playlist with fallback to yt-dlp and create a m3u: +- Download the first 10 songs of a youtube playlist: ``` -slsk-batchdl.exe --spotify -p "C:\Users\fiso64\Music\Playlists" --m3u "C:\Users\fiso64\Documents\MusicBee\Playlists" --music-dir "C:\Users\fiso64\Music" --username "fakename" --password "fakepass" --skip-existing --pref-format "flac" --yt-dlp -``` -You might need to provide an id and secret when using spotify, 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 youtube playlist: -``` ---youtube "https://www.youtube.com/playlist?list=PLI_eFW8NAFzYAXZ5DrU6E6mQ_XfhaLBUX" -p "C:\Users\fiso64\Music\Playlists" --username "fakename" --password "fakepass" +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 Soulseek username + --pass Soulseek password + + --spotify Download a spotify playlist ("likes" for liked music) + --spotify-id Your spotify client id (required for private playlists) + --spotify-secret Your spotify client secret (required for private playlists) + + --youtube Get tracks from a YouTube playlist + --youtube-key Provide an API key to include unavailable uploads + + --csv Use a csv file containing track info to download + --artist-col Artist or uploader column name + --title-col Title or track name column name + --album-col Track album column name (optional for more results) + --length-col Track duration column name (optional for better accuracy) + --time-unit Time unit in track duration column, ms or s (default: s) + --yt-desc-col YT description column name (optional, use with --yt-parse) + --yt-id-col 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 Search & download a specific track. is a simple + search string, or a comma-separated list of properties: + "title=Song Name,artist=Artist Name,length=215" + + -p --path Place downloaded files in custom path + -f --folder Custom folder name (default: provided playlist name) + -n --number Download at most n tracks of a playlist + -o --offset Skip a specified number of tracks + --reverse Download tracks in reverse order + --name-format Name format for downloaded tracks, e.g "{artist} - {title}" + --m3u Create an m3u8 playlist file + + --pref-format Preferred file format(s), comma-separated (default: mp3) + --pref-length-tol Preferred length tolerance in seconds (default: 3) + --pref-min-bitrate Preferred minimum bitrate (default: 200) + --pref-max-bitrate Preferred maximum bitrate (default: 2200) + --pref-max-samplerate 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 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 Necessary file format(s), comma-separated + --nec-length-tol Necessary length tolerance in seconds (default: 3) + --nec-min-bitrate Necessary minimum bitrate + --nec-max-bitrate Necessary maximum bitrate + --nec-max-samplerate 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 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 "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 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 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 Maximal search time (ms, default: 6000) + --max-stale-time Maximal download time with no progress (ms, default: 50000) + --concurrent-processes Max concurrent searches & downloads (default: 2) + --display "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: ``` @@ -92,8 +128,6 @@ Supports .conf files: Create a file named `slsk-batchdl.conf` in the same direct --pref-format "flac" ``` -## Notes: -- YouTube playlist downloading is unreliable since there are no track name / artist tags +### Notes: - The CSV file must be saved with `,` as field delimiter and `"` as string delimiter, encoded with UTF8 -- 40% of the code was written by ChatGPT -- Sometimes it starts vomiting text in the terminal (I don't know why), use --slow-output if that's an issue. +- `--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).