From 2f49cc230a275cd3ae3c79f1439ecee15fb08cbd Mon Sep 17 00:00:00 2001 From: Ritiek Malhotra Date: Thu, 26 Jul 2018 09:32:33 -0700 Subject: [PATCH] [WIP] Move detailed information to wiki pages (#308) * Move detailed information to wiki pages * Remove help usage and add an FAQ section * Update README.md * Update README.md * Downloading playlists and albums --- README.md | 312 +++++------------------------------------------------- 1 file changed, 28 insertions(+), 284 deletions(-) diff --git a/README.md b/README.md index cff5e85..2ef43d3 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ - Release date - And more... -- Works straight out of the box and does not require to generate or mess with your API keys. +- Works straight out of the box and does not require to generate or mess with your API keys (already included). That's how your music library will look like! @@ -31,302 +31,47 @@ That's how your music library will look like! ## Installation -- **This tool supports only Python 3**, Python 2 compatibility was dropped -because of the way it deals with unicode. -If you need to use Python 2 though, check out the (old) `python2` branch. +**This tool works with only Python 3**. -- Note: `play` and `lyrics` commands have been deprecated in the current branch -since they were not of much use and created unnecessary clutter. -You can still get them back by using `old` branch though. +Python 2 compatibility was dropped because of the way it deals with unicode (2020 is coming soon too). +If you still need to use Python 2 - check out the (outdated) +[python2](https://github.com/ritiek/spotify-downloader/tree/python2) branch. -### Debian-like GNU/Linux & macOS +spotify-downloader works with all major distributions and even on low-powered devices such as a Raspberry Pi. + +Check out the [Installation](https://github.com/ritiek/spotify-downloader/wiki/Installation) wiki page +for OS-specific instructions to get spotify-downloader working on your system. + +## Usage + +For the most basic usage, downloading tracks is as easy as ``` -$ cd -$ git clone https://github.com/ritiek/spotify-downloader -$ cd spotify-downloader -$ pip install -U -r requirements.txt +$ python3 spotdl.py --song https://open.spotify.com/track/2DGa7iaidT5s0qnINlwMjJ +$ python3 spotdl.py --song "ncs - spectre" ``` -**Important:** if you have installed both Python 2 and 3, the `pip` command -could invoke an installation for Python 2. To see which Python version `pip` -refers to, try `pip -V`. If it turns out `pip` is your Python 2 pip, try -`pip3 install -U -r requirements.txt` instead. - -You'll also need to install FFmpeg for conversion -(use `--avconv` if you'd like to use that instead): - -Debian-like GNU/Linux: +For downloading playlist and albums, you need to first load all the tracks into text file and then pass +this text file to `--list` argument. Here is how you would do it for a playlist ``` -$ sudo apt-get install ffmpeg +$ python3 spotdl.py --playlist https://open.spotify.com/user/nocopyrightsounds/playlist/7sZbq8QGyMnhKPcLJvCUFD +INFO: Writing 62 tracks to ncs-releases.txt +$ python3 spotdl.py --list ncs-releases.txt ``` -macOS: +Run `python3 spotdl.py --help` to get a list of all available options in spotify-downloader. -``` -$ brew install ffmpeg --with-libmp3lame --with-libass --with-opus --with-fdk-aac -``` +Check out the [Available options](https://github.com/ritiek/spotify-downloader/wiki/Available-options) +wiki page for the list of currently available options with their description. -If it does not install correctly, you may have to build it from source. -For more info see https://trac.ffmpeg.org/wiki/CompilationGuide. +The wiki page [Instructions for Downloading Songs](https://github.com/ritiek/spotify-downloader/wiki/Instructions-for-Downloading-Songs) +contains detailed information about different available ways to download tracks. -### Windows +## FAQ -Assuming you have Python 3 -([preferably v3.6 or above to stay away from Unicode errors](https://stackoverflow.com/questions/30539882/whats-the-deal-with-python-3-4-unicode-different-languages-and-windows)) already installed and in PATH. - -- Download and extract the [zip file](https://github.com/ritiek/spotify-downloader/archive/master.zip) -from master branch. - -- Download FFmpeg for Windows from [here](http://ffmpeg.zeranoe.com/builds/). -Copy `ffmpeg.exe` from `ffmpeg-xxx-winxx-static\bin\ffmpeg.exe` to PATH -(usually C:\Windows\System32\) or just place it in the root directory extracted -from the above step. - -- Open `cmd` and type `pip install -U -r requirements.txt` to install dependencies. -The same note about `pip` as for Debian, Ubuntu, Linux & Mac applies. - -## Instructions for Downloading Songs - -**Important:** as like with `pip`, there might be no `python3` command. -This is most likely the case when you have only Python 3 but not 2 installed. -In this case try the `python` command instead of `python3`, -but make sure `python -V` gives you a `Python 3.x.x`! - -- For all available options, run `python3 spotdl.py --help`. - -``` -usage: spotdl.py [-h] - (-s SONG | -l LIST | -p PLAYLIST | -b ALBUM | -u USERNAME | -V) - [-m] [-nm] [-a] [-f FOLDER] [--overwrite {force,prompt,skip}] - [-i {.webm,.m4a}] [-o OUTPUT_EXT] [-ff FILE_FORMAT] - [-sf SEARCH_FORMAT] [-dm] [-d] [-mo] [-ns] - [-ll {INFO,WARNING,ERROR,DEBUG}] [-c CONFIG] - -Download and convert tracks from Spotify, Youtube etc. - -optional arguments: - -h, --help show this help message and exit - -s SONG, --song SONG download track by spotify link or name (default: None) - -l LIST, --list LIST download tracks from a file (default: None) - -p PLAYLIST, --playlist PLAYLIST - load tracks from playlist URL into .txt - (default: None) - -b ALBUM, --album ALBUM - load tracks from album URL into .txt - (default: None) - -u USERNAME, --username USERNAME - load tracks from user's playlist into - .txt (default: None) - -V, --version show version and exit (default: False) - -m, --manual choose the track to download manually from a list of - matching tracks (default: False) - -nm, --no-metadata do not embed metadata in tracks (default: False) - -a, --avconv use avconv for conversion (otherwise defaults to - ffmpeg) (default: False) - -f FOLDER, --folder FOLDER - path to folder where downloaded tracks will be stored - in (default: Music) - --overwrite {force,prompt,skip} - change the overwrite policy (default: prompt) - -i {.webm,.m4a}, --input-ext {.webm,.m4a} - preferred input format .m4a or .webm (Opus) (default: - .m4a) - -o OUTPUT_EXT, --output-ext OUTPUT_EXT - preferred output format .mp3, .m4a (AAC), .flac, etc. - (default: .mp3) - -ff FILE_FORMAT, --file-format FILE_FORMAT - file format to save the downloaded track with, each - tag is surrounded by curly braces. Possible formats: - ['track_name', 'artist', 'album', 'album_artist', - 'genre', 'disc_number', 'duration', 'year', - 'original_date', 'track_number', 'total_tracks', - 'isrc'] (default: {artist} - {track_name}) - -sf SEARCH_FORMAT, --search-format SEARCH_FORMAT - search format to search for on YouTube, each tag is - surrounded by curly braces. Possible formats: - ['track_name', 'artist', 'album', 'album_artist', - 'genre', 'disc_number', 'duration', 'year', - 'original_date', 'track_number', 'total_tracks', - 'isrc'] (default: {artist} - {track_name} lyrics) - -dm, --download-only-metadata - download tracks only whose metadata is found (default: - False) - -d, --dry-run show only track title and YouTube URL, and then skip - to the next track (if any) (default: False) - -mo, --music-videos-only - search only for music videos on Youtube (works only - when YouTube API key is set (default: False) - -ns, --no-spaces replace spaces with underscores in file names - (default: False) - -ll {INFO,WARNING,ERROR,DEBUG}, --log-level {INFO,WARNING,ERROR,DEBUG} - set log verbosity (default: INFO) - -c CONFIG, --config CONFIG - path to config.yml file (otherwise load it from same - directory as spotdl.py) (default: None) -``` - -### Download by Name - -For example - -- We want to download Fade by Alan Walker, -simply run `python3 spotdl.py --song "alan walker fade"`. - -- The script will automatically look for the best matching song and -download it in the folder `Music/` placed in the root directory of the code base. - -- It will now convert the song to an mp3 and try to fix meta-tags -and album-art by looking up on Spotify. - -### Download by Spotify Link (Recommended) - -For example - -- We want to download the same song (i.e: Fade by Alan Walker) but using -Spotify Link this time that looks like `https://open.spotify.com/track/2lfPecqFbH8X4lHSpTxt8l`, -you can copy it from your Spotify desktop or mobile app by right clicking -or long tap on the song and copy HTTP link. - -- Run `python3 spotdl.py --song https://open.spotify.com/track/2lfPecqFbH8X4lHSpTxt8l`, -it should download Fade by Alan Walker. - -- Just like before, it will again convert the song to an mp3 but since we used -a Spotify HTTP link, the script is guaranteed to fetch the correct meta-tags and album-art. - -### Download by File - -For example - -- We want to download `Fade by Alan Walker`, `Sky High by Elektromania` -and `Fire by Elektromania` just using a single command. - -Let's suppose, we have the Spotify link for only `Fade by Alan Walker` and -`Fire by Elektromania`. - -No problem! - -- Just make a `list.txt` in the same folder as the script and add all the -songs you want to download, in our case it is - -(if you are on Windows, just edit `list.txt` - -i.e `C:\Python36\spotify-downloader-master\list.txt`) - -``` -https://open.spotify.com/track/2lfPecqFbH8X4lHSpTxt8l -elektromania sky high -https://open.spotify.com/track/0fbspWuEdaaT9vfmbAZr1C -``` - -- Now pass `--list=list.txt` to the script, i.e `python3 spotdl.py --list=list.txt` -and it will start downloading songs mentioned in `list.txt`. - -- You can stop downloading songs by hitting `ctrl+c`, the script will automatically -resume from the song where you stopped it the next time you want to download -the songs present in `list.txt`. - -- Songs that are already downloaded will prompt you to overwrite or skip. This behavior can be changed by -passing `--overwrite {prompt,skip,force}`. - -### Download by Playlist Link - -- You can copy the Spotify URL of the playlist and pass it in `--playlist` option. -Note: This method works for public as well as private playlists. - -For example - -- `python3 spotdl.py --playlist https://open.spotify.com/user/nocopyrightsounds/playlist/7sZbq8QGyMnhKPcLJvCUFD` - -- The script will load all the tracks from the playlist into `.txt` - -- Then you can simply run `python3 spotdl.py --list=.txt` -to download all the tracks. - -### Download by Album Link - -- You can copy the Spotify URL of the album and pass it in `--album` option. - -For example - -- `python3 spotdl.py --album https://open.spotify.com/album/499J8bIsEnU7DSrosFDJJg` - -- The script will load all the tracks from the album into `.txt` - -- Then you can simply run `python3 spotdl.py --list=.txt` -to download all the tracks. - -### Download by Username - -- You can also load songs using Spotify username if you don't have the playlist URL. -(Open profile in Spotify, click on the three little dots below name, -"Share", "Copy to clipboard", paste last numbers or text into command-line: -`https://open.spotify.com/user/0123456790`) - -- Try running `python3 spotdl.py -u `, it will (only) show all your -public playlists (which excludes collaborative and private playlists). - -- Once you select the one you want to download, the script will load all the tracks -from the playlist into `.txt`. - -- Run `python3 spotdl.py --list=.txt` to download all the tracks. - -### Specify the Target Directory - -If you don't want to download all the songs to the `Music/` folder relative to the -`spotdl.py` script, you can use the `-f`/`--folder` option. -E.g. `python3 spotdl.py -s "adele hello" -f "/home/user/Music/"`. -This works with both relative and absolute paths. - -## Config File - -At first run, this tool will generate a `config.yml` in root directory -of the code base with default options. You can then modify `config.yml` -to override any default options. - -Also note that config options are overridden by command-line arguments. - -If you want to use custom `.yml` configuration instead of the default one, you can use `-c`/`--config` option. -E.g. `python3 spotdl.py -s "adele hello" -c "/home/user/customConfig.yml"` - -## Set YouTube API Key - -By default this tool will scrape YouTube to fetch for matching video tracks. -However, you can optionally use YouTube API for faster response time. -To do this, [generate your API key](https://developers.google.com/youtube/registering_an_application) -and then set it in your `config.yml`. - -## [Docker Image](https://hub.docker.com/r/ritiek/spotify-downloader/) -[![Docker automated build](https://img.shields.io/docker/automated/jrottenberg/ffmpeg.svg)](https://hub.docker.com/r/ritiek/spotify-downloader) -[![Docker pulls](https://img.shields.io/docker/pulls/ritiek/spotify-downloader.svg)](https://hub.docker.com/r/ritiek/spotify-downloader) - -We also provide the latest docker image on [DockerHub](https://hub.docker.com/r/ritiek/spotify-downloader/). - -- Pull (or update) the image with `docker pull ritiek/spotify-downloader`. - -- Run it with `docker run --rm -it -v $(pwd):/music ritiek/spotify-downloader `. - -- The container will download music and write tracks in your current working directory. - -**Example - Downloading a Playlist** - -``` -$ docker run --rm -it -v $(pwd):/music ritiek/spotify-downloader -p https://open.spotify.com/user/nocopyrightsounds/playlist/7sZbq8QGyMnhKPcLJvCUFD -$ docker run --rm -it -v $(pwd):/music ritiek/spotify-downloader -l ncs-releases.txt -``` - -## Vagrant box - -If you have struggle setting this up in a Vagrant box, [**@csimpi**](https://github.com/csimpi) has posted very detailed instructions [here](https://github.com/ritiek/spotify-downloader/issues/294#issuecomment-400155361). - -## Exit Codes - -- `0` - Success -- `1` - Unknown error -- `2` - Command line error (e.g. invalid args) -- `3` - `KeyboardInterrupt` -- `10` - Invalid playlist URL -- `11` - Playlist not found +Check out our [FAQ wiki page](https://github.com/ritiek/spotify-downloader/wiki/FAQ) +for more info. ## Contributing @@ -350,4 +95,3 @@ Please support the artists by buying their music. ## License [![License](https://img.shields.io/github/license/ritiek/spotify-downloader.svg)](https://github.com/ritiek/spotify-downloader/blob/master/LICENSE) -