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

Add comprehensive documentation and README

Browse Source 
- 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>
This commit is contained in:
Heiko Joerg Schick
2025-08-10 21:16:04 +02:00
parent d5d34554f6
commit d839dbe293
2 changed files with 396 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
generate_hitster_cards.py
+217 -5
View File
@@ -1,4 +1,21 @@
#!/usr/bin/env python3
"""
Music Cards Generator
Generates 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.
The tool creates 3x3 grids of cards (63x88mm each) on A4 pages, suitable for
home printing and cutting. Cards can be generated as separate front/back PDFs
or as a single interleaved PDF for duplex printing.
Usage:
python generate_hitster_cards.py --playlist <URL> --client-id <ID> --client-secret <SECRET>
Requires Spotify Web API credentials for accessing playlist data.
"""
import argparse
import math
import os
@@ -21,11 +38,20 @@ from spotipy.oauth2 import SpotifyClientCredentials
@dataclass
class TrackCard:
"""Represents a single music card with all necessary data.
Attributes:
title: The track title
artists: Comma-separated string of artist names
year: Release year of the track (None if unavailable)
url: Spotify URL for the track
qr_img: PIL Image object containing the QR code
"""
title: str
artists: str
year: Optional[int]
url: str
qr_img: Image.Image # PIL image
qr_img: Image.Image
# ---------- Spotify helpers ----------
@@ -36,6 +62,19 @@ PLAYLIST_REGEXES = [
]
def extract_playlist_id(url: str) -> str:
"""Extract Spotify playlist ID from various URL formats.
Supports both web URLs (open.spotify.com) and Spotify URI format.
Args:
url: Spotify playlist URL or URI
Returns:
The playlist ID string
Raises:
ValueError: If the URL format is not recognized
"""
for rx in PLAYLIST_REGEXES:
m = rx.search(url)
if m:
@@ -43,10 +82,34 @@ def extract_playlist_id(url: str) -> str:
raise ValueError("Unsupported playlist URL. Expected open.spotify.com/playlist/<id> or spotify:playlist:<id>")
def spotify_client(client_id: str, client_secret: str) -> spotipy.Spotify:
"""Create authenticated Spotify client using client credentials flow.
This authentication method only works with public playlists.
Args:
client_id: Spotify application client ID
client_secret: Spotify application client secret
Returns:
Authenticated Spotify client instance
"""
auth = SpotifyClientCredentials(client_id=client_id, client_secret=client_secret)
return spotipy.Spotify(auth_manager=auth)
def fetch_tracks(sp: spotipy.Spotify, playlist_id: str, limit: Optional[int] = None) -> List[dict]:
"""Fetch track data from a Spotify playlist.
Retrieves all tracks from the playlist, handling pagination automatically.
Only returns tracks (not podcasts or other media types).
Args:
sp: Authenticated Spotify client
playlist_id: Spotify playlist ID
limit: Maximum number of tracks to fetch (None for all)
Returns:
List of track dictionaries from Spotify API
"""
items = []
offset = 0
page_size = 100
@@ -69,6 +132,19 @@ def fetch_tracks(sp: spotipy.Spotify, playlist_id: str, limit: Optional[int] = N
return items
def safe_year_from_release_date(release_date: Optional[str]) -> Optional[int]:
"""Safely extract year from Spotify release date string.
Handles various date formats returned by Spotify API:
- 'yyyy' (year only)
- 'yyyy-mm' (year and month)
- 'yyyy-mm-dd' (full date)
Args:
release_date: Release date string from Spotify API
Returns:
Year as integer, or None if parsing fails
"""
if not release_date:
return None
try:
@@ -81,6 +157,19 @@ def safe_year_from_release_date(release_date: Optional[str]) -> Optional[int]:
# ---------- QR code helper ----------
def make_qr_pil(url: str, box_size: int = 8, border: int = 2) -> Image.Image:
"""Generate QR code as PIL Image.
Creates a QR code linking to the provided URL with medium error correction.
The border parameter controls the quiet zone around the QR code.
Args:
url: URL to encode in the QR code
box_size: Size of each QR code box in pixels
border: Width of the border (quiet zone) in boxes
Returns:
PIL Image containing the QR code
"""
qr = qrcode.QRCode(
version=None, # automatic
error_correction=qrcode.constants.ERROR_CORRECT_M,
@@ -98,6 +187,20 @@ def make_qr_pil(url: str, box_size: int = 8, border: int = 2) -> Image.Image:
# ---------- Typography ----------
def wrap_text(text: str, max_width: float, font_name: str, font_size: float, canv: canvas.Canvas) -> List[str]:
"""Wrap text to fit within specified width using greedy line-breaking.
Uses ReportLab's stringWidth to measure text accurately for the given font.
Args:
text: Text to wrap
max_width: Maximum line width in points
font_name: ReportLab font name (e.g., 'Helvetica', 'Helvetica-Bold')
font_size: Font size in points
canv: ReportLab Canvas for measuring text width
Returns:
List of text lines that fit within the specified width
"""
# Simple greedy line-wrapping
words = text.split()
lines = []
@@ -126,8 +229,16 @@ MARGIN_LR = (210 * mm - COLS * CARD_W) / 2.0
MARGIN_TB = (297 * mm - ROWS * CARD_H) / 2.0
def grid_position(index: int) -> Tuple[int, int, int]:
"""
Returns (page_index, col, row) for a zero-based card index.
"""Calculate page and grid position for a card index.
Converts a linear card index into page number and grid coordinates
for the 3x3 card layout.
Args:
index: Zero-based card index
Returns:
Tuple of (page_index, col, row) where col and row are 0-based
"""
per_page = COLS * ROWS
page = index // per_page
@@ -137,11 +248,31 @@ def grid_position(index: int) -> Tuple[int, int, int]:
return page, col, row
def card_origin(col: int, row: int) -> Tuple[float, float]:
"""Calculate the bottom-left origin point for a card at grid position.
Uses ReportLab's coordinate system where (0,0) is bottom-left of page.
Args:
col: Column index (0-2)
row: Row index (0-2)
Returns:
Tuple of (x, y) coordinates in points
"""
x = MARGIN_LR + col * CARD_W
y = PAGE_H - MARGIN_TB - (row + 1) * CARD_H
return x, y
def draw_cut_border(c: canvas.Canvas, x: float, y: float, w: float, h: float):
"""Draw a light grey border around a card for cutting guides.
Args:
c: ReportLab Canvas
x: X coordinate of bottom-left corner
y: Y coordinate of bottom-left corner
w: Width of the rectangle
h: Height of the rectangle
"""
c.setLineWidth(0.3)
c.setStrokeColor(colors.lightgrey)
c.rect(x, y, w, h, stroke=1, fill=0)
@@ -149,6 +280,22 @@ def draw_cut_border(c: canvas.Canvas, x: float, y: float, w: float, h: float):
c.setLineWidth(1.0)
def draw_card_front(c: canvas.Canvas, x: float, y: float, card: TrackCard, qr_size_mm: float, show_year_on_front: bool):
"""Draw the front side of a music card.
The front contains:
- QR code linking to the Spotify track
- Track title (bold, up to 3 lines)
- Artist names (up to 2 lines)
- Optional year in bottom-right corner
Args:
c: ReportLab Canvas
x: X coordinate of card bottom-left corner
y: Y coordinate of card bottom-left corner
card: TrackCard with all the card data
qr_size_mm: Size of QR code in millimetres
show_year_on_front: Whether to show year on front
"""
draw_cut_border(c, x, y, CARD_W, CARD_H)
pad = 4 * mm
qr_size = qr_size_mm * mm
@@ -181,6 +328,18 @@ def draw_card_front(c: canvas.Canvas, x: float, y: float, card: TrackCard, qr_si
c.drawRightString(x + CARD_W - pad, y + pad, str(card.year))
def draw_card_back(c: canvas.Canvas, x: float, y: float, card: TrackCard):
"""Draw the back side of a music card.
The back contains:
- Large year text centered in the middle
- Small title and artist info at the bottom
Args:
c: ReportLab Canvas
x: X coordinate of card bottom-left corner
y: Y coordinate of card bottom-left corner
card: TrackCard with all the card data
"""
draw_cut_border(c, x, y, CARD_W, CARD_H)
pad = 6 * mm
c.setFillColor(colors.black)
@@ -199,6 +358,18 @@ def draw_card_back(c: canvas.Canvas, x: float, y: float, card: TrackCard):
c.drawCentredString(x + CARD_W / 2.0, base_y - i * line_height, line)
def build_cards(tracks: List[dict], qr_size_mm: float) -> List[TrackCard]:
"""Convert Spotify track data into TrackCard objects.
Processes each track to extract title, artists, year, and URL,
then generates a QR code for each valid track.
Args:
tracks: List of track dictionaries from Spotify API
qr_size_mm: Size for QR codes (used for parameter consistency)
Returns:
List of TrackCard objects ready for PDF generation
"""
cards: List[TrackCard] = []
for t in tracks:
title = (t.get("name") or "").strip()
@@ -212,6 +383,15 @@ def build_cards(tracks: List[dict], qr_size_mm: float) -> List[TrackCard]:
return cards
def paginate_draw(c: canvas.Canvas, cards: List[TrackCard], draw_fn):
"""Draw cards across multiple pages using the provided drawing function.
Handles pagination automatically, creating new pages as needed.
Args:
c: ReportLab Canvas
cards: List of TrackCard objects to draw
draw_fn: Function to draw individual cards (signature: fn(canvas, x, y, card))
"""
per_page = COLS * ROWS
total_pages = math.ceil(len(cards) / per_page) or 1
for page in range(total_pages):
@@ -225,6 +405,18 @@ def paginate_draw(c: canvas.Canvas, cards: List[TrackCard], draw_fn):
c.showPage()
def generate_pdfs(cards: List[TrackCard], out_dir: str, show_year_on_front: bool, qr_size_mm: float):
"""Generate separate PDF files for card fronts and backs.
Creates two PDF files:
- fronts.pdf: All card fronts
- backs.pdf: All card backs (in same order)
Args:
cards: List of TrackCard objects
out_dir: Output directory path
show_year_on_front: Whether to show year on front of cards
qr_size_mm: QR code size in millimetres
"""
os.makedirs(out_dir, exist_ok=True)
fronts_path = os.path.join(out_dir, "fronts.pdf")
backs_path = os.path.join(out_dir, "backs.pdf")
@@ -242,8 +434,20 @@ def generate_pdfs(cards: List[TrackCard], out_dir: str, show_year_on_front: bool
cb.save()
def generate_pdf_interleaved(cards: List[TrackCard], out_dir: str, show_year_on_front: bool, qr_size_mm: float):
"""
Produce one PDF: odd pages = fronts, even pages = backs, for each 3x3 page of cards.
"""Generate a single interleaved PDF for duplex printing.
Creates cards.pdf where:
- Odd pages contain card fronts (pages 1, 3, 5, ...)
- Even pages contain corresponding card backs (pages 2, 4, 6, ...)
This format is suitable for duplex printing where each sheet contains
9 complete cards (front and back).
Args:
cards: List of TrackCard objects
out_dir: Output directory path
show_year_on_front: Whether to show year on front of cards
qr_size_mm: QR code size in millimetres
"""
os.makedirs(out_dir, exist_ok=True)
out_path = os.path.join(out_dir, "cards.pdf")
@@ -276,6 +480,14 @@ def generate_pdf_interleaved(cards: List[TrackCard], out_dir: str, show_year_on_
print(f"Generated interleaved PDF: {os.path.abspath(out_path)}")
def main():
"""Main entry point for the music cards generator.
Parses command-line arguments, fetches playlist data from Spotify,
and generates PDF files with music cards.
Raises:
SystemExit: If playlist is empty, inaccessible, or no valid cards can be created
"""
parser = argparse.ArgumentParser(description="Generate DIN A4 music cards from a Spotify playlist.")
parser.add_argument("--playlist", required=True, help="Spotify playlist URL (public).")
parser.add_argument("--client-id", required=True, help="Spotify CLIENT_ID.")