KevinMidboe/spotify-downloader
1
0
Fork 0
mirror of https://github.com/KevinMidboe/spotify-downloader.git synced 2025-10-29 18:00:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

[WIP] Move detailed information to wiki pages (#308)

Browse Source 
* 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
2018-07-26 09:32:33 -07:00
committed by GitHub
parent 55908e3097
commit 2f49cc230a
1 changed files with 28 additions and 284 deletions
Download Patch File Download Diff File Expand all files Collapse all files

312
README.md
View File

@@ -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 <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/)
[![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 <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
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)