Edison/music-cards
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Heiko Joerg Schick
2025-08-10 20:44:24 +02:00
commit bea985066a
4 changed files with 420 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+113
View File
@@ -0,0 +1,113 @@
# 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.
## 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)
- 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/).
## How to run locally
- 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.
## 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
- 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).
## 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 Hitster or Spotify.