docs: refresh README

2026-07-27 15:24:01 +02:00
parent ab7fd7390a
commit ece5a408a8
1 changed files with 79 additions and 15 deletions
@@ -1,24 +1,88 @@
 # Spotify Playlist Downloader

-## Requirements
+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.

- Global or local python environment with all packages from `requirements.txt`.
- FFMPEG according to the installation instructions for SpotDL. (https://ffmpeg.org/)
+## Status and limitations

- Spotify-API client with ID and secret for SpotiPy. The following ENV variables have to be set:
+- 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.

-```
-SPOTIPY_CLIENT_ID='your_spotify_client_id'
-SPOTIPY_CLIENT_SECRET='your_spotify_client_secret'
+## 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
 ```

-## Usage
+This installs `spotdl` and `spotipy`. Ensure the `spotdl` command is available on `PATH` in the same environment that runs the script.

-The script has to be run from commandline with `python playlist_downloader.py <username> <playlist_root_dir>`
-All public playlists by the given user will be downloaded.
-If the playlist root does not exist yet, it will be created.
-For each playlist a directory will be created in the playlist root.
-The actual songs from the playlists will be downloaded to their respectively named directories.
+Set credentials in the environment; do not put them in `config.json` or commit them:

-A file called `additional_playlists.txt` can be used to specify additional playlists to download.
-Each playlist has to be added as a new line containing the URI to the public playlist.
+```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)