<!-- 0ab6f78b-28ea-4bf7-8a7d-0e9a7d9c1cf7 -->
---
todos:
  - id: "create-project"
    content: "Create project structure at ~/projects/thumbgen with pyproject.toml, .gitignore, README.md"
    status: pending
  - id: "implement-extract"
    content: "Create extract.py with ffmpeg frame extraction logic"
    status: pending
  - id: "implement-overlay"
    content: "Create overlay.py with Pillow text overlay and gradient"
    status: pending
  - id: "implement-cli"
    content: "Create cli.py with typer command"
    status: pending
  - id: "test-tool"
    content: "Test thumbgen with a sample video"
    status: pending
isProject: false
---
# Thumbgen - Instagram Reel Thumbnail Generator

## Overview

A standalone CLI tool that extracts a frame from a video and overlays styled text (title + artist) to create Instagram reel thumbnails.

## Project Structure

```
~/projects/thumbgen/
├── pyproject.toml
├── README.md
├── .gitignore
└── src/
    └── thumbgen/
        ├── __init__.py
        ├── cli.py          # Typer CLI
        ├── extract.py      # FFmpeg frame extraction
        └── overlay.py      # Pillow text overlay
```

## Dependencies

- `typer` - CLI framework
- `Pillow` - Image processing and text overlay
- `loguru` - Logging

FFmpeg required as system dependency (for frame extraction).

## CLI Interface

```bash
# Basic usage
thumbgen video.mp4 -t "Castle of Glass" -a "Linkin Park"
# Output: video_thumb.png

# With options
thumbgen video.mp4 -t "Numb" -a "Linkin Park" -o cover.png --time 10
```

**Arguments/Options:**
- `video` - Input video file (required)
- `-t, --title` - Song title (required)
- `-a, --artist` - Artist name (required)
- `-o, --output` - Output path (default: `{video_stem}_thumb.png`)
- `--time` - Frame timestamp in seconds (default: middle of video)

## Text Styling

- **Position**: Lower third, left-aligned with padding
- **Title**: Large, bold, white text with shadow
- **Artist**: Smaller, below title, slightly muted
- **Background**: Semi-transparent dark gradient overlay at bottom for readability
- **Font**: System sans-serif (Arial/Helvetica) or bundled font

## Implementation Details

### Frame Extraction (`extract.py`)
- Use ffmpeg to get video duration via ffprobe
- Extract single frame at specified timestamp as PNG bytes
- Default to middle of video if no time specified

### Text Overlay (`overlay.py`)
- Load frame with Pillow
- Draw gradient overlay on bottom third
- Render title and artist with text shadow
- Save as PNG (or JPEG with quality option)
