Quick Start

Get started with Loups in minutes!

---

5-Minute Quickstart

---

Basic Usage

Lights Out HB Games

For Lights Out HB fastpitch softball games, Loups includes a bundled template:

loups game_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
...

Any Other Video

For other videos, provide your own template:

loups -t my_template.png video.mp4

---

Save Results to File

Save chapters in YouTube-ready format:

loups -o chapters.txt video.mp4

The chapters.txt file will contain:

0:00:00 Game Start
0:01:15 Sarah Johnson #7
0:03:42 Emma Martinez #12
0:05:23 Lily Garcia #9
...

YouTube Integration

Copy the contents of chapters.txt directly into your YouTube video description!

YouTube will automatically create clickable chapter markers.

---

Common Examples

Process with Custom Template

loups -t ~/templates/scoreboard.png -o chapters.txt game.mp4

Quiet Mode (No Progress Display)

Perfect for automation and batch processing:

loups -q -o chapters.txt video.mp4

Enable Logging

Debug detection issues with logging:

# Default log location (loups.log)
loups --log video.mp4

# Custom log location
loups --log /path/to/debug.log video.mp4

# Enable debug level logging
loups --log --debug video.mp4

---

Extract Thumbnails

Dedicated Thumbnail Command

# Extract thumbnail with default template
loups video.mp4 thumbnail

# Use custom thumbnail template
loups video.mp4 thumbnail --thumbnail-template title_screen.png

# Specify output location
loups video.mp4 thumbnail --thumbnail-output ./thumb.jpg

Extract During Chapter Scan

loups --extract-thumbnail --thumbnail-output thumb.jpg -o chapters.txt video.mp4

How Thumbnail Extraction Works

1. Scans video frames from beginning using SSIM
2. Stops at first frame exceeding similarity threshold
3. Saves matched frame as JPEG
4. Only scans first N seconds (default: 120s)

---

Important Notes

Option Order Matters

Options must come BEFORE the video path:

Correct Wrong

loups -o chapters.txt -t template.png video.mp4

loups video.mp4 -o chapters.txt -t template.png

Thumbnail Command Different

The thumbnail subcommand has different syntax:

loups VIDEO thumbnail [OPTIONS]

The VIDEO comes first, then thumbnail, then options.

---

Example Workflows

YouTube Content Creation

# Extract thumbnail
loups game.mp4 thumbnail --thumbnail-output game_thumb.jpg

# Generate chapters
loups -o game_chapters.txt game.mp4

# Upload video to YouTube
# - Use game_thumb.jpg as custom thumbnail
# - Paste game_chapters.txt content into description

Batch Processing Multiple Videos

# Process all MP4 files
for video in *.mp4; do
  echo "Processing $video..."
  loups -q -o "${video%.mp4}_chapters.txt" "$video"
done

Custom Template Workflow

# Step 1: Create template from video frame
# (Screenshot the text overlay you want to detect)

# Step 2: Test on short clip
loups -t my_template.png --log test_clip.mp4

# Step 3: Check logs to verify detection
cat loups.log

# Step 4: Process full video
loups -t my_template.png -o chapters.txt full_video.mp4

---

Testing Tips

Test on Short Clips First

Before processing long videos:

1. Create a short test clip (1-2 minutes)
2. Verify template detection works
3. Check OCR accuracy in logs
4. Then process full video

# Create test clip with ffmpeg
ffmpeg -i full_video.mp4 -t 120 -c copy test_clip.mp4

# Test with logging
loups --log --debug -t template.png test_clip.mp4

---

Next Steps

• CLI Reference - All command options
• Custom Templates - Create templates for your videos
• API Reference - Use Loups programmatically

---

Common Questions

Can I use Loups with any video?

Yes! As long as your video has:

• Consistent text overlays or identifying frames
• Readable text that OCR can extract
• A template image you can create

See Custom Templates for details.

What video formats are supported?

Loups supports any format that OpenCV can read:

• MP4 (recommended)
• AVI
• MOV
• MKV
• And more

If you encounter codec issues, convert to MP4 with H.264 encoding.

How accurate is the OCR?

Accuracy depends on:

• Video quality - Higher resolution = better OCR
• Text clarity - Clear, high-contrast text works best
• Steady frames - Motion blur reduces accuracy

Loups uses confidence-based filtering to ensure quality results.

Can I process videos in batch?

Absolutely! Use quiet mode for scripting:

loups -q -o output.txt video.mp4

Check the exit code to verify success in scripts.