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

pip install spotipy reportlab qrcode[pil] pillow

Spotify API Setup

1. Go to Spotify Developer 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)

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)

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:

  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