social-card

Generate polished social-share card images from a title + subtitle, with optional background image.

Formats

• og — 1200x630 (Open Graph / Twitter card / link preview)
• square — 1080x1080 (Instagram grid post)
• story — 1080x1920 (Instagram / TikTok story, 9:16)

Usage

# Basic OG card on solid dark
python3 scripts/card.py --title "DEMON 01" --subtitle "out now" --format og --output card.png

# With background image
python3 scripts/card.py --title "Release Friday" --subtitle "pre-save link in bio" \
  --image cover.jpg --format square --output ig.png

# Story format with custom accent
python3 scripts/card.py --title "TONIGHT" --subtitle "live @ 9pm" \
  --format story --accent "#00FFAA" --output story.png

# Light theme
python3 scripts/card.py --title "newsletter #42" --subtitle "this week in shipping" \
  --format og --theme light --output news.png

Flags

• --title (required) — main heading, auto-fits to width, max 3 lines
• --subtitle (optional) — secondary line below title
• --image (optional) — background image path; cover-cropped to fit
• --format — og | square | story (default og)
• --theme — dark (default) | light
• --accent — hex color for the accent bar above the title (default #FF3B30)
• --output (required) — output PNG path
• --font-title (optional) — TTF/OTF path for title font
• --font-body (optional) — TTF/OTF path for subtitle font

Notes

• Auto-installs Pillow on first run.
• Title auto-shrinks and wraps (max 3 lines) to fit the available width.
• Background images get a 70% black gradient overlay in dark theme so the title stays legible.
• Default fonts fall back to Helvetica → DejaVu → PIL default in that order.

Output

Single PNG at the requested resolution. Drop into Twitter/og:image meta tags, IG, TikTok, or a release announcement.