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:

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:

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.

{
  "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:

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)

4.0 KiB Raw Permalink Blame History