Skip to content

Creating Custom Templates

Learn how to create templates for any video content to use with Loups.

❓ What is a Template?

A template is an image that acts as a trigger - Loups scans your video looking for frames that match this template. When a match is found, Loups extracts the text from that frame to create a chapter entry.

Template Analogy

Think of the template as a "bookmark shape" - Loups flips through your video looking for frames that look like your bookmark. When it finds one, it reads the text on that page.

👣 4-Step Process

1⃣ Find a Clear Frame

Pause your video where the identifying text overlay is clearly visible:

  • Sports: Scoreboard with player name
  • Podcasts: Guest name overlay
  • Gaming: Level title card
  • Educational: Speaker introduction

Best Practices

  • Text is fully visible and readable
  • No motion blur
  • Consistent lighting
  • Frame appears multiple times in video

2⃣ Take a Screenshot

Capture the frame:

  • Press ⌘ + Shift + 4
  • Select area to capture
  • File saved to Desktop
  • Press Win + Shift + S
  • Select area
  • Save from clipboard
  • Use screenshot tool
  • Or: gnome-screenshot -a

3⃣ Crop the Template

Open in image editor and crop to include:

  • The region where text appears
  • Some surrounding context (helps matching)
  • Exclude elements that change frame-to-frame

Crop Carefully

Too large: May include changing elements → false negatives Too small: May not match reliably → missed detections

Just right: Includes text region + stable surrounding area

4⃣ Save and Use

Save as PNG (recommended) or JPG:

loups -t my_template.png video.mp4

🎨 Template Examples

Sports Scoreboard

┌─────────────────────────────┐
│  BATTER: Sarah Johnson #7   │  ← Include this
│  INNING: 3   SCORE: 2-1     │  ← Crop around text
└─────────────────────────────┘

What to include: - Player name area - Jersey number location - Stable background elements

What to exclude: - Changing score - Moving elements - Video timestamp

Podcast Guest Overlay

┌──────────────────────┐
│  NOW SPEAKING:       │
│  Dr. Jane Smith      │  ← Crop this region
│  AI Researcher       │
└──────────────────────┘

What to include: - Name card background - "NOW SPEAKING" label if consistent - Text region

Game Level Card

┌─────────────────┐
│  LEVEL 5        │  ← Level text
│  The Castle     │  ← Level name
└─────────────────┘

What to include: - Level indicator - Title text area - Consistent UI elements

✅ Template Quality Checklist

Good Template Characteristics

  • High contrast - Text clearly visible
  • Consistent position - Same location throughout video
  • Clear text - No blur, pixelation, or distortion
  • Stable background - Unchanging elements
  • Appropriate size - Not too large, not too small
  • Good resolution - Match video quality

Avoid These Issues

  • Motion blur or partial frames
  • Changing elements (scores, timers)
  • Low resolution or compression artifacts
  • Text partially cut off
  • Inconsistent appearance across video

🧪 Testing Your Template

Step 1: Test on Short Clip

Create a test clip first:

# Extract first 2 minutes with ffmpeg
ffmpeg -i full_video.mp4 -t 120 -c copy test_clip.mp4

Step 2: Run with Logging

loups --log --debug -t my_template.png test_clip.mp4

Step 3: Check Results

# View the log
cat loups.log

# Look for:
# - Template match timestamps
# - OCR confidence scores
# - Extracted text

Step 4: Adjust if Needed

Troubleshooting

Too many matches? → Crop template more tightly Missing matches? → Include more surrounding context Wrong text extracted? → Adjust template boundaries Garbled OCR? → Use higher quality source frame

💡 Advanced Tips

Multiple Templates

Can't find one template that works for all frames? Use different templates:

# Process same video multiple times with different templates
loups -t template1.png -o chapters1.txt video.mp4
loups -t template2.png -o chapters2.txt video.mp4

# Combine results manually
cat chapters1.txt chapters2.txt | sort > all_chapters.txt

Template for Thumbnails

Create a separate template for thumbnail extraction:

# Different template for title screen
loups video.mp4 thumbnail --thumbnail-template title_screen_template.png

Video Quality Matters

Source Quality

Template matching works best with:

  • 720p or higher video resolution
  • Minimal compression artifacts
  • Steady camera (for handheld footage)
  • Good lighting and contrast

Use Case Examples

Educational Lecture

Scenario: Video with speaker name overlays

Template includes:
┌─────────────────────┐
│ 👤 Speaker Name     │
│    Title/Role       │
└─────────────────────┘

Result: 

0:00:00 Introduction
0:05:30 Dr. Sarah Chen - Computer Science
0:25:15 Prof. Michael Brown - Mathematics
0:45:00 Dr. Lisa Wang - Physics

Music Performance

Scenario: Song title cards between performances

Template includes:
┌──────────────────────┐
│  🎵 Now Playing:     │
│  [Song Title]        │
│  [Artist Name]       │
└──────────────────────┘

Result: 

0:00:00 Opening
0:03:45 Song Title - Artist Name
0:08:20 Another Song - Different Artist

TV Series

Scenario: Episode title cards

Template includes:
┌────────────────────┐
│  EPISODE 5         │
│  "Episode Title"   │
└────────────────────┘

🛠 Tools for Template Creation

Tool Platform Free Use Case
Preview macOS Built-in, simple cropping
Paint Windows Basic editing
GIMP All Advanced editing
ffmpeg All Extract frames
VLC All Screenshot frames

Extract Frame with ffmpeg

Get a perfect frame from exact timestamp:

# Extract frame at 01:23:45
ffmpeg -ss 01:23:45 -i video.mp4 -frames:v 1 template.png

🔗 Next Steps

Now that you have a template:

  1. Quick Start - Use your template
  2. CLI Reference - Template options
  3. API Reference - Programmatic usage

❓ Common Questions

Can I use the same template for different videos?

Yes, if the videos have the same overlay/UI format!

For example: - All episodes of same TV series - Same game with consistent UI - Videos from same production

What image format should I use?

PNG recommended for best quality (lossless compression)

Also supported: - JPG/JPEG (acceptable, slightly lower quality) - BMP (works but larger files)

Does template size matter?

Yes! Template should be:

  • Same resolution as video (or close)
  • Large enough to be distinctive
  • Small enough to avoid changing elements

Typically 200-800 pixels wide works well.

Can I create templates from YouTube videos?

Absolutely! Take screenshots while watching:

  • Pause at the overlay you want
  • Screenshot the browser window
  • Crop to just the overlay region
  • Use with downloaded video file
My template isn't matching. What now?

Try these steps:

  1. Enable debug logging: loups --log --debug -t template.png video.mp4
  2. Check the log for match confidence scores
  3. Verify template matches video frames exactly
  4. Adjust crop - try larger/smaller regions
  5. Check resolution - template should match video quality

Still stuck? Open an issue with: - Sample frame from video - Your template image - Debug log output