# Guide for this repository

## Project overview
- Goal: Generate printable DIN A4 sheets with 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: music_cards_generator.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 Spotify.

## Key requirements and constraints
- 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.

## Repository structure (expected)
- music_cards_generator.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/).

## How to run locally
- Dependencies:
  - pip install spotipy reportlab qrcode[pil]
- Run (separate files):
  - python music_cards_generator.py --playlist "<playlist_url>" --client-id <CLIENT_ID> --client-secret <CLIENT_SECRET> --out ./cards_out --max-cards 54
- Run (single interleaved file):
  - python music_cards_generator.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.

## Coding standards
- 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.

## Quality checks
- 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.

## Security guidance
- 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.

## Known limitations and non-goals
- These are standard QR codes that link to open.spotify.com for universal compatibility with any QR code scanner.
- 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).

## Common tasks for Claude
- 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.

## Acceptance criteria for changes
- 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.

## Implementation notes
- 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.

## Example prompts for Claude
- ‘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).’

## Testing guidance
- 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.

## Licence and attribution
- Use for personal, non-commercial purposes only.
- Not affiliated with or endorsed by Spotify.