mirror of
https://github.com/KevinMidboe/spotify-downloader.git
synced 2025-10-29 18:00:15 +00:00
[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
This commit is contained in:
Ritiek Malhotra
GitHub
312
README.md
312
README.md
@@ -23,7 +23,7 @@
|
|||||||
- Release date
|
- Release date
|
||||||
- And more...
|
- 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!
|
That's how your music library will look like!
|
||||||
|
|
||||||
@@ -31,302 +31,47 @@ That's how your music library will look like!
|
|||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
- **This tool supports only Python 3**, Python 2 compatibility was dropped
|
**This tool works with only Python 3**.
|
||||||
because of the way it deals with unicode.
|
|
||||||
If you need to use Python 2 though, check out the (old) `python2` branch.
|
|
||||||
|
|
||||||
- Note: `play` and `lyrics` commands have been deprecated in the current branch
|
Python 2 compatibility was dropped because of the way it deals with unicode (2020 is coming soon too).
|
||||||
since they were not of much use and created unnecessary clutter.
|
If you still need to use Python 2 - check out the (outdated)
|
||||||
You can still get them back by using `old` branch though.
|
[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
|
$ python3 spotdl.py --song https://open.spotify.com/track/2DGa7iaidT5s0qnINlwMjJ
|
||||||
$ git clone https://github.com/ritiek/spotify-downloader
|
$ python3 spotdl.py --song "ncs - spectre"
|
||||||
$ cd spotify-downloader
|
|
||||||
$ pip install -U -r requirements.txt
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Important:** if you have installed both Python 2 and 3, the `pip` command
|
For downloading playlist and albums, you need to first load all the tracks into text file and then pass
|
||||||
could invoke an installation for Python 2. To see which Python version `pip`
|
this text file to `--list` argument. Here is how you would do it for a playlist
|
||||||
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:
|
|
||||||
|
|
||||||
```
|
```
|
||||||
$ 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.
|
||||||
|
|
||||||
```
|
Check out the [Available options](https://github.com/ritiek/spotify-downloader/wiki/Available-options)
|
||||||
$ brew install ffmpeg --with-libmp3lame --with-libass --with-opus --with-fdk-aac
|
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.
|
The wiki page [Instructions for Downloading Songs](https://github.com/ritiek/spotify-downloader/wiki/Instructions-for-Downloading-Songs)
|
||||||
For more info see https://trac.ffmpeg.org/wiki/CompilationGuide.
|
contains detailed information about different available ways to download tracks.
|
||||||
|
|
||||||
### Windows
|
## FAQ
|
||||||
|
|
||||||
Assuming you have Python 3
|
Check out our [FAQ wiki page](https://github.com/ritiek/spotify-downloader/wiki/FAQ)
|
||||||
([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.
|
for more info.
|
||||||
|
|
||||||
- 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 <playlist_name>.txt
|
|
||||||
(default: None)
|
|
||||||
-b ALBUM, --album ALBUM
|
|
||||||
load tracks from album URL into <album_name>.txt
|
|
||||||
(default: None)
|
|
||||||
-u USERNAME, --username USERNAME
|
|
||||||
load tracks from user's playlist into
|
|
||||||
<playlist_name>.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 `<playlist_name>.txt`
|
|
||||||
|
|
||||||
- Then you can simply run `python3 spotdl.py --list=<playlist_name>.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 `<album_name>.txt`
|
|
||||||
|
|
||||||
- Then you can simply run `python3 spotdl.py --list=<album_name>.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 <your_username>`, 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 `<playlist_name>.txt`.
|
|
||||||
|
|
||||||
- Run `python3 spotdl.py --list=<playlist_name>.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/)
|
|
||||||
[](https://hub.docker.com/r/ritiek/spotify-downloader)
|
|
||||||
[](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 <arguments>`.
|
|
||||||
|
|
||||||
- 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
|
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
@@ -350,4 +95,3 @@ Please support the artists by buying their music.
|
|||||||
## License
|
## License
|
||||||
|
|
||||||
[](https://github.com/ritiek/spotify-downloader/blob/master/LICENSE)
|
[](https://github.com/ritiek/spotify-downloader/blob/master/LICENSE)
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user