diff --git a/README.md b/README.md index aed534e9..0d10a019 100644 --- a/README.md +++ b/README.md @@ -37,26 +37,78 @@ Python packages: Basic command line usage: python zspotify Downloads the track, album, playlist or podcast episode specified as a command line argument. If an artist url is given, all albums by specified artist will be downloaded. Can take multiple urls. -Extra command line options: - -p, --playlist Downloads a saved playlist from your account +Different usage modes: + (nothing) Download the tracks/alumbs/playlists URLs from the parameter + -d, --download Download all tracks/alumbs/playlists URLs from the specified file + -p, --playlist Downloads a saved playlist from your account -ls, --liked-songs Downloads all the liked songs from your account - -s, --search Loads search prompt to find then download a specific track, album or playlist + -s, --search Loads search prompt to find then download a specific track, album or playlist + +Extra command line options: -ns, --no-splash Suppress the splash screen when loading. - -Options that can be configured in zs_config.json: - ROOT_PATH Change this path if you don't like the default directory where ZSpotify saves the music - ROOT_PODCAST_PATH Change this path if you don't like the default directory where ZSpotify saves the podcasts - - SKIP_EXISTING_FILES Set this to false if you want ZSpotify to overwrite files with the same name rather than skipping the song - - MUSIC_FORMAT Can be "mp3" or "ogg", mp3 is required for track metadata however ogg is slightly higher quality as it is not transcoded. - - FORCE_PREMIUM Set this to true if ZSpotify isn't automatically detecting that you are using a premium account - - ANTI_BAN_WAIT_TIME Change this setting if the time waited between bulk downloads is too high or low - OVERRIDE_AUTO_WAIT Change this to true if you want to completely disable the wait between songs for faster downloads with the risk of instability + --config-location Use a different zs_config.json, defaults to the one in the program directory ``` +### Options: + +All these options can either be configured in the zs_config or via the commandline, in case of both the commandline-option has higher priority. +Be aware you have to set boolean values in the commandline like this: `--download-real-time=True` + +| Key (zs-config) | commandline parameter | Description +|------------------------------|----------------------------------|---------------------------------------------------------------------| +| ROOT_PATH | --root-path | directory where ZSpotify saves the music +| ROOT_PODCAST_PATH | --root-podcast-path | directory where ZSpotify saves the podcasts +| SKIP_EXISTING_FILES | --skip-existing-files | Skip songs with the same name +| SKIP_PREVIOUSLY_DOWNLOADED | --skip-previously-downloaded | Create a .song_archive file and skip previously downloaded songs +| DOWNLOAD_FORMAT | --download-format | The download audio format (aac, fdk_aac, m4a, mp3, ogg, opus, vorbis) +| FORCE_PREMIUM | --force-premium | Force the use of high quality downloads (only with premium accounts) +| ANTI_BAN_WAIT_TIME | --anti-ban-wait-time | The wait time between bulk downloads +| OVERRIDE_AUTO_WAIT | --override-auto-wait | Totally disable wait time between songs with the risk of instability +| CHUNK_SIZE | --chunk-size | chunk size for downloading +| SPLIT_ALBUM_DISCS | --split-album-discs | split downloaded albums by disc +| DOWNLOAD_REAL_TIME | --download-real-time | only downloads songs as fast as they would be played, can prevent account bans +| LANGUAGE | --language | Language for spotify metadata +| BITRATE | --bitrate | Overwrite the bitrate for ffmpeg encoding +| SONG_ARCHIVE | --song-archive | The song_archive file for SKIP_PREVIOUSLY_DOWNLOADED +| CREDENTIALS_LOCATION | --credentials-location | The location of the credentials.json +| OUTPUT | --output | The output location/format (see below) +| PRINT_SPLASH | --print-splash | Print the splash message +| PRINT_SKIPS | --print-skips | Print messages if a song is being skipped +| PRINT_DOWNLOAD_PROGRESS | --print-download-progress | Print the download/playlist progress bars +| PRINT_ERRORS | --print-errors | Print errors +| PRINT_DOWNLOADS | --print-downloads | Print messages when a song is finished downloading + +### Output format: + +With the option `OUTPUT` (or the commandline parameter `--output`) you can specify the output location and format. +The value is relative to the `ROOT_PATH`/`ROOT_PODCAST_PATH` directory and can contain the following placeholder: + +| Placeholder | Description +|-----------------|-------------------------------- +| {artist} | The song artist +| {album} | The song album +| {song_name} | The song name +| {release_year} | The song release year +| {disc_number} | The disc number +| {track_number} | The track_number +| {id} | The song id +| {track_id} | The track id +| {ext} | The file extension +| {album_id} | (only when downloading albums) ID of the album +| {album_num} | (only when downloading albums) Incrementing track number +| {playlist} | (only when downloading playlists) Name of the playlist +| {playlist_num} | (only when downloading playlists) Incrementing track number + +Example values could be: +~~~~ +{playlist}/{artist} - {song_name}.{ext} +{playlist}/{playlist_num} - {artist} - {song_name}.{ext} +Liked Songs/{artist} - {song_name}.{ext} +{artist} - {song_name}.{ext} +{artist}/{album}/{album_num} - {artist} - {song_name}.{ext} +/home/user/downloads/{artist} - {song_name} [{id}].{ext} +~~~~ + ### Docker Usage ```