zotify/README.md

153 lines
7.9 KiB
Markdown
Raw Normal View History

2021-12-25 21:53:43 -07:00
# Zotify
2022-02-14 23:07:45 -07:00
### A highly customizable music and podcast downloader.
2021-12-25 21:53:43 -07:00
<p align="center">
2022-02-12 00:48:27 -07:00
<img src="https://i.imgur.com/hGXQWSl.png" width="50%">
2021-12-25 21:53:43 -07:00
</p>
2022-02-12 00:48:27 -07:00
[Discord Server](https://discord.gg/XDYsFRTUjE)
2021-12-25 21:53:43 -07:00
2022-02-14 23:07:45 -07:00
### Featues
- Downloads at up to 320kbps*
- Downloads directly from the source**
- Downloads podcasts, playlists, liked songs, albums, artists, singles.
2022-02-18 20:25:36 -07:00
- Downloads synced lyrics from the source
2022-02-14 23:07:45 -07:00
- Option to download in real time to appear more legitimate***
- Supports multiple audio formats
- Download directly from URL or use built-in in search
- Bulk downloads from a list of URLs in a text file or parsed directly as arguments
*Free accounts are limited to 160kbps. \
**Audio files are NOT substituted with ones from other sources such as YouTube or Deezer, they are sourced directly. \
***'real time' refers to downloading at the speed it would normally be streamed at (the duration of the track).
2022-02-12 00:48:27 -07:00
### Install
2021-12-25 21:53:43 -07:00
2022-02-12 00:48:27 -07:00
```
Dependencies:
2021-12-25 21:53:43 -07:00
- Python 3.9 or greater
2022-02-14 23:07:45 -07:00
- FFmpeg*
2021-12-25 21:53:43 -07:00
2022-02-12 00:48:27 -07:00
Installation:
2021-12-25 21:53:43 -07:00
2022-02-12 00:48:27 -07:00
python -m pip install https://gitlab.com/team-zotify/zotify/-/archive/main/zotify-main.zip
2021-12-25 21:53:43 -07:00
```
2022-02-14 23:07:45 -07:00
\*Zotify will work without FFmpeg but transcoding will be unavailable.
2021-12-25 21:53:43 -07:00
2022-02-12 00:48:27 -07:00
### Command line usage
2021-12-25 21:53:43 -07:00
```
Basic command line usage:
2022-02-04 02:11:49 -07:00
zotify <track/album/playlist/episode/artist url> 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.
2021-12-25 21:53:43 -07:00
2022-02-12 00:48:27 -07:00
Basic options:
(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
-l, --liked Downloads all the liked songs from your account
-s, --search Searches for specified track, album, artist or playlist, loads search prompt if none are given.
2021-12-25 21:53:43 -07:00
```
2022-02-12 00:48:27 -07:00
### Options
2021-12-25 21:53:43 -07:00
2022-02-04 02:11:49 -07:00
All these options can either be configured in the config or via the commandline, in case of both the commandline-option has higher priority.
2021-12-25 21:53:43 -07:00
Be aware you have to set boolean values in the commandline like this: `--download-real-time=True`
2022-02-04 02:11:49 -07:00
| Key (config) | commandline parameter | Description
2021-12-25 21:53:43 -07:00
|------------------------------|----------------------------------|---------------------------------------------------------------------|
2022-02-14 23:07:45 -07:00
| CREDENTIALS_LOCATION | --credentials-location | The location of the credentials.json
| OUTPUT | --output | The output location/format (see below)
| SONG_ARCHIVE | --song-archive | The song_archive file for SKIP_PREVIOUSLY_DOWNLOADED
| ROOT_PATH | --root-path | Directory where Zotify saves music
| ROOT_PODCAST_PATH | --root-podcast-path | Directory where Zotify saves podcasts
| SPLIT_ALBUM_DISCS | --split-album-discs | Saves each disk in its own folder
2022-02-16 02:00:43 -07:00
| DOWNLOAD_LYRICS | --download-lyrics | Downloads synced lyrics in .lrc format, uses unsynced as fallback.
2022-02-14 23:07:45 -07:00
| MD_ALLGENRES | --md-allgenres | Save all relevant genres in metadata
| MD_GENREDELIMITER | --md-genredelimiter | Delimiter character used to split genres in metadata
| DOWNLOAD_FORMAT | --download-format | The download audio format (aac, fdk_aac, m4a, mp3, ogg, opus, vorbis)
| DOWNLOAD_QUALITY | --download-quality | Audio quality of downloaded songs (normal, high, very-high*)
| TRANSCODE_BITRATE | --transcode-bitrate | Overwrite the bitrate for ffmpeg encoding
2021-12-25 21:53:43 -07:00
| SKIP_EXISTING_FILES | --skip-existing-files | Skip songs with the same name
2022-02-12 00:48:27 -07:00
| SKIP_PREVIOUSLY_DOWNLOADED | --skip-previously-downloaded | Use a song_archive file to skip previously downloaded songs
2022-02-14 23:07:45 -07:00
| RETRY_ATTEMPTS | --retry-attempts | Number of times Zotify will retry a failed request
| BULK_WAIT_TIME | --bulk-wait-time | The wait time between bulk downloads
2021-12-25 21:53:43 -07:00
| OVERRIDE_AUTO_WAIT | --override-auto-wait | Totally disable wait time between songs with the risk of instability
2022-02-12 00:48:27 -07:00
| CHUNK_SIZE | --chunk-size | Chunk size for downloading
| DOWNLOAD_REAL_TIME | --download-real-time | Downloads songs as fast as they would be played, should prevent account bans.
2021-12-25 21:53:43 -07:00
| LANGUAGE | --language | Language for spotify metadata
2022-02-14 23:07:45 -07:00
| PRINT_SPLASH | --print-splash | Show the Zotify logo at startup
| PRINT_SKIPS | --print-skips | Show messages if a song is being skipped
| PRINT_DOWNLOAD_PROGRESS | --print-download-progress | Show download/playlist progress bars
| PRINT_ERRORS | --print-errors | Show errors
2021-12-25 21:53:43 -07:00
| PRINT_DOWNLOADS | --print-downloads | Print messages when a song is finished downloading
| TEMP_DOWNLOAD_DIR | --temp-download-dir | Download tracks to a temporary directory first
2022-02-14 23:07:45 -07:00
*very-high is limited to premium only
2022-02-12 00:48:27 -07:00
### Output format
2021-12-25 21:53:43 -07:00
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}
2022-02-12 00:48:27 -07:00
Bangers/{artist} - {song_name}.{ext}
2021-12-25 21:53:43 -07:00
{artist} - {song_name}.{ext}
{artist}/{album}/{album_num} - {artist} - {song_name}.{ext}
/home/user/downloads/{artist} - {song_name} [{id}].{ext}
~~~~
2022-02-04 02:11:49 -07:00
### Docker Usage - CURRENTLY BROKEN
2021-12-25 21:53:43 -07:00
```
Build the docker image from the Dockerfile:
docker build -t zotify .
Create and run a container from the image:
2022-02-04 02:11:49 -07:00
docker run --rm -u $(id -u):$(id -g) -v "$PWD/zotify:/app" -v "$PWD/config.json:/config.json" -v "$PWD/Zotify Music:/Zotify Music" -v "$PWD/Zotify Podcasts:/Zotify Podcasts" -it zotify
2021-12-25 21:53:43 -07:00
```
2022-02-14 23:07:45 -07:00
### What do I do if I see "Your session has been terminated"?
If you see this, don't worry! Just try logging back in. If you see the incorrect username or password error, reset your password and you should be able to log back in.
2021-12-25 21:53:43 -07:00
### Will my account get banned if I use this tool?
Currently no user has reported their account getting banned after using Zotify.
2022-02-04 02:11:49 -07:00
It is recommended you use Zotify with a burner account.
Alternatively, there is a configuration option labled ```DOWNLOAD_REAL_TIME```, this limits the download speed to the duration of the song being downloaded thus appearing less suspicious.
2021-12-25 21:53:43 -07:00
This option is much slower and is only recommended for premium users who wish to download songs in 320kbps without buying premium on a burner account.
2022-02-14 23:07:45 -07:00
### Disclaimer
Zotify is intended to be used in compliance with DMCA, Section 1201, for educational, private and fair use. \
Zotify contributors are not responsible for any misuse of the program or source code.
2021-12-25 21:53:43 -07:00
### Contributing
Please refer to [CONTRIBUTING](CONTRIBUTING.md)
### Changelog
Please refer to [CHANGELOG](CHANGELOG.md)