music-cards/README.md

# 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 music_cards_generator.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 music_cards_generator.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`