Loups¶

Automated Video Chapter Generation

Powered by Template Matching & OCR

Get Started Documentation GitHub

What is Loups?¶

Loups automatically scans videos with on-screen text overlays to extract information and generate timestamped YouTube chapters. Originally designed for Lights Out HB fastpitch softball games, but works with any video content that has consistent identifying frames or text overlays.

Template Matching¶

Detects specific frames using image templates - your "trigger" for chapter detection

OCR Extraction¶

Reads text from matched frames with confidence-based filtering for accuracy

Smart Timestamps¶

Combines extracted text with video timestamps to create chapter entries

YouTube Ready¶

Exports chapters in YouTube-ready format - copy and paste into descriptions

Thumbnail Extraction¶

SSIM-based automatic thumbnail extraction with first-match strategy

Fast Processing¶

Efficient video frame analysis with progress tracking and quiet mode

Quick Start¶

Get Started in Seconds

# Install from PyPI
pip install loups

# Scan a Lights Out HB game (uses bundled template)
loups game_video.mp4

# Or use your own template for any video
loups -t my_template.png -o chapters.txt video.mp4

Expected output:

Scanning video: game_video.mp4

🥎 Scanning batters...  [Progress updates]

🏆 Scan complete! Found 12 batters in 5.2s

YouTube Chapters:
0:00:00 Game Start
0:01:15 Sarah Johnson #7
0:03:42 Emma Martinez #12
0:05:23 Lily Garcia #9
0:08:14 Olivia Brown #5
...

Use Cases¶

Sports Games Track player at-bats, shifts, appearances

Educational Content Chapter markers for topics or speakers

Podcasts/Interviews Detect guest overlays or topic cards

Gaming Mark level changes or character selections

TV Shows Detect episode titles or scene markers

Any Video With consistent text overlays or frames

Why Loups?¶

Modern & Powerful

Universal - Works with any video content
Accurate - Confidence-based OCR filtering
Fast - Efficient frame processing
Automated - Perfect for batch processing
Cross-Platform - Linux, macOS, Windows

Platform Support

Python 3.13+ required

Linux - Fully tested via CI/CD
macOS - Fully tested via CI/CD
Windows - Fully tested via CI/CD

How It Works¶

graph LR
    A[🎥 Video Input] --> B[🎯 Template Matching]
    B --> C[📝 OCR Extraction]
    C --> D[📋 Chapter Creation]
    D --> E[📤 YouTube Format]

    style A fill:#1a1a1a,stroke:#00ffff,color:#00ffff,stroke-width:3px
    style B fill:#1a1a1a,stroke:#00ffff,color:#00ffff,stroke-width:3px
    style C fill:#1a1a1a,stroke:#00ffff,color:#00ffff,stroke-width:3px
    style D fill:#1a1a1a,stroke:#00ffff,color:#00ffff,stroke-width:3px
    style E fill:#1a1a1a,stroke:#00ffff,color:#00ffff,stroke-width:3px

Template Matching - Scans frames looking for your template image
OCR Text Extraction - Reads visible text from matched frames
Chapter Creation - Combines text with timestamps
Export - Generates YouTube-ready chapter format

Learn more about the process

Open Source¶

Loups is MIT licensed and welcomes contributions!

Made with :heart: for content creators :movie_camera:

Originally created for Lights Out HB fastpitch softball coverage