# 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)