Add comprehensive documentation and README

- Added detailed docstrings to all functions in the main script - Created comprehensive README.md with setup, usage, and troubleshooting - Includes module-level documentation explaining the tool's purpose - Added complete API reference and printing instructions 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-08-10 21:16:04 +02:00
parent d5d34554f6
commit d839dbe293
2 changed files with 396 additions and 5 deletions
@@ -0,0 +1,179 @@
+# Music Cards Generator
+
+Generate printable DIN A4 sheets with music cards from Spotify playlists. Each card features a QR code linking to the track, along with title, artist(s), and release year information.
+
+## Features
+
+- **3×3 Card Layout**: Creates 9 cards per A4 page (63×88mm each)
+- **QR Code Integration**: Each card contains a scannable QR code linking to the Spotify track
+- **Dual Output Modes**: 
+  - Separate PDFs for fronts and backs
+  - Single interleaved PDF for duplex printing
+- **Professional Design**: Clean layout with cutting guides and proper typography
+- **Customisable**: Adjustable QR code size and optional year display on front
+
+## Installation
+
+### Prerequisites
+- Python 3.9 or higher
+- Spotify Developer Account (for API credentials)
+
+### Install Dependencies
+```bash
+pip install spotipy reportlab qrcode[pil] pillow
+```
+
+### Spotify API Setup
+1. Go to [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
+2. Create a new application
+3. Note your **Client ID** and **Client Secret**
+4. No redirect URI needed for public playlists
+
+## Usage
+
+### Basic Usage (Separate PDFs)
+```bash
+python generate_hitster_cards.py \
+  --playlist "https://open.spotify.com/playlist/YOUR_PLAYLIST_ID" \
+  --client-id YOUR_CLIENT_ID \
+  --client-secret YOUR_CLIENT_SECRET \
+  --out ./cards_out \
+  --max-cards 54
+```
+
+### Single Interleaved PDF (for Duplex Printing)
+```bash
+python generate_hitster_cards.py \
+  --playlist "https://open.spotify.com/playlist/YOUR_PLAYLIST_ID" \
+  --client-id YOUR_CLIENT_ID \
+  --client-secret YOUR_CLIENT_SECRET \
+  --out ./cards_out \
+  --max-cards 54 \
+  --one-pdf
+```
+
+### Command Line Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--playlist` | Spotify playlist URL (required) | - |
+| `--client-id` | Spotify Client ID (required) | - |
+| `--client-secret` | Spotify Client Secret (required) | - |
+| `--out` | Output directory for PDF files | `output_cards` |
+| `--max-cards` | Maximum number of cards to generate | `54` |
+| `--qr-size-mm` | QR code size in millimetres | `35.0` |
+| `--year-on-front` | Show year on card front | `false` |
+| `--one-pdf` | Generate single interleaved PDF | `false` |
+
+## Output Files
+
+### Separate Mode (default)
+- `fronts.pdf`: All card fronts
+- `backs.pdf`: All card backs (same order)
+
+### Interleaved Mode (`--one-pdf`)
+- `cards.pdf`: Alternating front and back pages
+  - Page 1: Fronts of cards 1-9
+  - Page 2: Backs of cards 1-9  
+  - Page 3: Fronts of cards 10-18
+  - Page 4: Backs of cards 10-18
+  - And so on...
+
+## Printing Instructions
+
+### For Best Results
+- **Print Setting**: "Actual size" (no scaling)
+- **Quality**: 300 DPI or higher
+- **Paper**: Standard A4 (210×297mm)
+- **Contrast**: High contrast for better QR code scanning
+
+### Duplex Printing
+When using `--one-pdf` mode:
+1. Print all pages duplex (double-sided)
+2. Use "Flip on Long Edge" setting
+3. Page 1 (fronts) and Page 2 (backs) will align perfectly
+
+### Manual Duplex
+For separate PDFs:
+1. Print `fronts.pdf` first
+2. Reload paper (same orientation)
+3. Print `backs.pdf` on the reverse side
+
+### Cutting
+- Cards include light grey cutting guides
+- Each card is 63×88mm
+- Use a paper cutter or craft knife with ruler
+
+## Card Layout
+
+### Front Side
+- **QR Code**: Links to Spotify track (scannable by any QR reader)
+- **Title**: Track name (bold, up to 3 lines)
+- **Artist(s)**: Artist names (up to 2 lines)
+- **Year** (optional): Small text in bottom-right corner
+
+### Back Side  
+- **Year**: Large centered text
+- **Track Info**: Small "Title — Artist(s)" at bottom
+
+## Limitations
+
+- **Public Playlists Only**: Client credentials flow cannot access private playlists
+- **Standard QR Codes**: These link to open.spotify.com, not proprietary formats
+- **Year Data**: Based on album release date, may differ from original single release
+
+## Troubleshooting
+
+### Common Issues
+
+**"No tracks fetched" Error**
+- Ensure playlist is public
+- Verify playlist URL is correct
+- Check Spotify API credentials
+
+**"Private playlist" (404 Error)**
+- Make playlist public in Spotify, or
+- Use authorisation code flow for private playlists (not currently supported)
+
+**QR Codes Don't Scan**
+- Increase `--qr-size-mm` value (try 40-45mm)
+- Ensure high-contrast printing
+- Check printer DPI settings
+
+**Poor Print Quality**
+- Use 300+ DPI printer setting
+- Select "Actual size" (no scaling)
+- Use high-quality paper
+
+### Getting Help
+
+For issues or questions:
+1. Check that your playlist URL and API credentials are correct
+2. Verify the playlist is public and contains tracks
+3. Try reducing `--max-cards` for testing
+
+## Security Notes
+
+- **Never commit API credentials** to version control
+- Consider using environment variables for credentials:
+  ```bash
+  export SPOTIFY_CLIENT_ID="your_client_id"
+  export SPOTIFY_CLIENT_SECRET="your_client_secret"
+  ```
+- Client secrets are sensitive - rotate if accidentally exposed
+
+## Licence
+
+For personal, non-commercial use only. Not affiliated with or endorsed by Spotify.
+
+## Requirements File
+
+Create a `requirements.txt` file:
+```
+spotipy>=2.22.1
+reportlab>=4.0.4
+qrcode[pil]>=7.4.2
+pillow>=10.0.0
+```
+
+Install with: `pip install -r requirements.txt`