schihei
ff42d5fddc
- Renamed generate_hitster_cards.py to music_cards_generator.py - Updated all documentation references to use the new filename - Removed remaining Hitster references from the filename - Script name now matches the Music Cards branding 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
114 lines
7.0 KiB
Markdown
114 lines
7.0 KiB
Markdown
# 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.
|