music-cards/CLAUDE.md

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.