89 lines
4.0 KiB
Markdown
89 lines
4.0 KiB
Markdown
# Spotify Playlist Downloader
|
|
|
|
A Python script that finds public Spotify playlists for configured users and/or configured playlist URLs, then calls `spotdl` to download each playlist into local folders.
|
|
|
|
## Status and limitations
|
|
|
|
- This is a configuration-driven script, not a command-line interface: it reads `config.json` in its current working directory and accepts no positional arguments.
|
|
- A real run contacts Spotify and shells out to `spotdl`; no offline, dry-run, test, or deployment command is provided.
|
|
- Only public playlists are requested through the Spotify client-credentials flow.
|
|
- The script creates the configured output root with `os.mkdir`, which creates only one directory level. Its parent directory must already exist.
|
|
- The checked-in `config.json` is local-machine configuration. Do not copy its paths or playlist selections as a portable default; replace them with your own values and avoid committing private local settings.
|
|
|
|
## Prerequisites
|
|
|
|
- Python with pip
|
|
- FFmpeg, as required by SpotDL
|
|
- Spotify API client credentials with permission to use the client-credentials flow
|
|
|
|
Install the declared Python dependencies:
|
|
|
|
```bash
|
|
python -m pip install -r requirements.txt
|
|
```
|
|
|
|
This installs `spotdl` and `spotipy`. Ensure the `spotdl` command is available on `PATH` in the same environment that runs the script.
|
|
|
|
Set credentials in the environment; do not put them in `config.json` or commit them:
|
|
|
|
```bash
|
|
export SPOTIPY_CLIENT_ID='your_client_id'
|
|
export SPOTIPY_CLIENT_SECRET='your_client_secret'
|
|
```
|
|
|
|
## Configure playlists
|
|
|
|
Create or edit `config.json` beside `playlist_downloader.py`. `output_root_folder` is required. All other top-level settings are optional.
|
|
|
|
```json
|
|
{
|
|
"output_root_folder": "/path/to/existing-parent/playlists",
|
|
"default_file_type": "mp3",
|
|
"users": ["spotify-user-id"],
|
|
"additional_playlists": [
|
|
"https://open.spotify.com/playlist/playlist-id"
|
|
],
|
|
"excluded_playlists": [
|
|
"https://open.spotify.com/playlist/playlist-to-skip"
|
|
],
|
|
"playlist_options": {
|
|
"https://open.spotify.com/playlist/playlist-id": {
|
|
"file_type": "flac"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
| Key | Behavior |
|
|
| --- | --- |
|
|
| `output_root_folder` | Required root for playlist folders. Its parent must exist. |
|
|
| `default_file_type` | Download format; defaults to `mp3`. |
|
|
| `users` | Spotify users whose public playlists are fetched; defaults to an empty list. |
|
|
| `additional_playlists` | Public playlist URLs to fetch explicitly; defaults to an empty list. |
|
|
| `excluded_playlists` | Playlist URLs to exclude after playlist metadata is collected; defaults to an empty list. |
|
|
| `playlist_options` | Per-playlist options merged over the default options, keyed by playlist URL; defaults to an empty object. |
|
|
|
|
Each selected playlist receives a folder named from Spotify playlist metadata beneath the configured output root. The downloader invokes `spotdl <playlist URL> --format <file type>` from that folder. Treat `default_file_type` and each per-playlist `file_type` as trusted local configuration; do not accept those values from untrusted users or input.
|
|
|
|
## Run
|
|
|
|
From the directory containing `config.json`:
|
|
|
|
```bash
|
|
python playlist_downloader.py
|
|
```
|
|
|
|
The script prints the number of selected playlists and downloads them sequentially. It does **not** use the obsolete `<username> <playlist_root_dir>` arguments or an `additional_playlists.txt` file.
|
|
|
|
## Development and operations
|
|
|
|
No test suite, lint command, packaging metadata, service definition, or deployment configuration is present. Review changes manually and run against a disposable output directory when validating configuration because execution creates directories and downloads media.
|
|
|
|
## Repository layout
|
|
|
|
- `playlist_downloader.py` — configuration loading, playlist selection, and download orchestration
|
|
- `spotify_connection.py` — Spotipy client and playlist lookups
|
|
- `spotdl_connector.py` — output-directory creation and `spotdl` invocation
|
|
- `requirements.txt` — declared Python dependencies
|
|
- `config.json` — local runtime configuration (replace its machine-specific values)
|