Video to Chapters (with Transcript)

AI-powered Python library and CLI that automatically generates timestamped chapter summaries for video content.

Features

• Automatic transcript generation (with speaker labels) using AssemblyAI
• Cheap local scene detection (SSIM + histogram comparison) to find chapter boundaries
• Google Gemini used only where it adds value: describing detected scene changes and writing chapter titles/summaries
• Chapter segmentation based on scene changes and speaker turns
• Export formats for YouTube, Vimeo, Spotify, Markdown, SRT, and JSON

Requirements

• Python 3.13+
• ffmpeg / ffprobe on your PATH
• API keys for AssemblyAI and Google Gemini (see .env.example)

Installation

uv tool install video-to-chapters-with-transcript

Or for development:

git clone https://github.com/hbmartin/video-to-chapters-with-transcript
cd video-to-chapters-with-transcript
uv sync

Usage

# Process a video end-to-end (transcript, scene detection, chapters)
video-to-chapters process video.mp4

# Choose an output format and save to a file
video-to-chapters process video.mp4 --format youtube --output chapters.txt

# List previously processed videos
video-to-chapters list

# Show chapters for an already-processed video without reprocessing
video-to-chapters show --video-id 1

# Re-segment with a different scene-change threshold (reuses cached AI summaries)
video-to-chapters regenerate --threshold 0.6

Run video-to-chapters --help for all commands and options.

Configuration

Copy .env.example to .env and fill in your API keys:

ASSEMBLYAI_API_KEY=...
GEMINI_API_KEY=...

License

MIT