Guide for this repository

Project overview

Goal: Generate printable DIN A4 sheets with ‘Hitster-style’ music cards from a Spotify playlist. Front shows a QR code plus the title and artist(s); back shows the release year and small text.
Current core: generate_hitster_cards.py uses Spotify’s Web API, generates QR codes and PDF pages with 3 × 3 cards per A4 (each 63 × 88 millimetres).
Outputs:
- Separate files mode: fronts.pdf and backs.pdf.
- Interleaved mode: cards.pdf with alternating pages (odd fronts, even backs) via --one-pdf.
Scope: Personal, non-commercial use; not affiliated with Hitster or Spotify.

Paper and layout:
- DIN A4 (210 × 297 millimetres), 3 × 3 grid, card size 63 × 88 millimetres, light grey cut borders.
- QR code prominently on the front; title and artist(s) centred below; optional year on front controlled by --year-on-front.
- Back shows the year large and the small label ‘Title — Artist(s)’ near the bottom.
Spotify data:
- Client credentials flow for public playlists; album.release_date is used to derive the year.
- For private or collaborative playlists, switch to authorisation code flow with scopes playlist-read-private and playlist-read-collaborative.
British English:
- Use ‘-ise’ spellings, ‘metre’, ‘colour’, etc., and metric units. Keep mm for dimensions.
Security and privacy:
- Never log or hard-code Client Secret. Do not commit credentials. Suggest environment variables where possible.
- Treat user-provided playlist URLs as sensitive until published by the user.

generate_hitster_cards.py — main script with CLI.
CLAUDE.md — this file.
Optionally:
- README.md — quick start and printing notes.
- requirements.txt — minimal deps: spotipy, reportlab, qrcode[pil], pillow.
- .gitignore — exclude virtual environments, IDE files, and output folders (e.g. cards_out/).

Dependencies:
- pip install spotipy reportlab qrcode[pil]
Run (separate files):
- python generate_hitster_cards.py --playlist "<playlist_url>" --client-id <CLIENT_ID> --client-secret <CLIENT_SECRET> --out ./cards_out --max-cards 54
Run (single interleaved file):
- python generate_hitster_cards.py --playlist "<playlist_url>" --client-id <CLIENT_ID> --client-secret <CLIENT_SECRET> --out ./cards_out --max-cards 54 --one-pdf
Printing:
- ‘Actual size’ (no scaling), high-contrast, 300 dpi or better.
- Duplex: odd pages are fronts, even pages are the backs of the same set of 9 cards.

Language: Python 3.9+.
Style: PEP 8, type hints for new/changed functions, small pure functions where practical.
Names: descriptive, avoid abbreviations unless standard (e.g. url, id).
Errors: raise SystemExit with clear messages for user-facing errors. Catch and describe common Spotify API errors (404 for private playlists, 429 for rate limiting).
Logs/prints: keep output concise and user-focused; avoid printing secrets or full tokens.
Units: represent page and card geometry in millimetres using reportlab’s mm unit.

Run static checks (if configured): flake8, black, and mypy are welcome but optional. Keep the script runnable without extra tooling.
Manual test:
- Use a known public playlist; verify fronts.pdf/backs.pdf or cards.pdf render 3 × 3 cards aligned.
- Test QR codes with the phone Camera app; they should open in Spotify via open.spotify.com.

Do not expose CLIENT_SECRET (rotate if leaked).
Consider reading credentials from environment variables (SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET) if adding features.
Avoid copying full API payloads to logs; redact where necessary.

The Hitster iPhone app will not scan these QR codes; they are standard QR codes to open.spotify.com, not Hitster’s proprietary format.
Album.release_date year may differ from an original single’s first release in some catalogues.
Client credentials flow cannot read private playlists; that requires user login (authorisation code flow).

Add duplex alignment options:
- --mirror-backs to mirror the horizontal order for long-edge flips.
- --rotate-backs to rotate back pages by 180 degrees if printers invert one side.
Improve robustness:
- Detect and explain 404 (private playlist) and 429 (rate limited) with actionable suggestions.
- Fallback when album.release_date is partial; parse ‘yyyy-mm’ and ‘yyyy-mm-dd’ safely.
Enhancements:
- --qr-size-mm default tuning; expose --qr-border (quiet zone) and document recommended values.
- Optional Spotify Codes rendering (secondary image) for scanning inside the Spotify app.
- Read CLIENT_ID/SECRET from environment variables if flags are not provided.
- CSV import/export of track metadata before PDF generation.
Developer ergonomics:
- Factor drawing code for fronts/backs into reusable helpers with explicit geometry.
- Add minimal unit tests for helpers like wrap_text and safe_year_from_release_date.

No secrets are logged or stored.
The default 3 × 3 layout remains 63 × 88 millimetres per card on DIN A4.
Existing flags continue to work; new flags have clear help text and sensible defaults.
User-facing errors are clear, with next-steps guidance.
Printing remains predictable; interleaved mode alternates fronts then backs.

QR code generation:
- Library: qrcode with ERROR_CORRECT_M; default border (quiet zone) 2; allow configuration via a CLI flag if modified.
Spotify API:
- With client credentials, support only public playlists. For private playlists, use authorisation code flow with scopes playlist-read-private and playlist-read-collaborative and a Redirect URI (e.g. http://localhost:8080/callback).
PDF layout:
- Use reportlab A4, mm units, consistent margins, and a light grey cut border. Keep text centred and wrapped.

‘Add a --mirror-backs flag that mirrors the column order on back pages for long-edge duplex printing. Update CLI help, implement, and explain how to use it.’
‘Detect 404 from playlist_items and print a friendly message explaining that the playlist is likely private, with steps to make it public or switch to user authorisation.’
‘Introduce --qr-border to control the QR quiet zone (default 2). Update make_qr_pil accordingly and document its impact on scan reliability.’
‘Allow reading SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET from the environment when flags are omitted. Keep explicit flags taking precedence.’
‘Add a minimal README.md with quick start, printing tips, and security notes (no secrets in logs).’

Use a short public playlist for quick iteration.
Generate one page (max-cards 9) and print on plain paper to validate duplex alignment.
Scan QR codes with a phone’s Camera app to confirm correctness of links.