Skip to content

API Reference

Complete API documentation for using Loups programmatically in your Python projects.

📚 Module Overview

Loups provides a clean Python API for video chapter generation and thumbnail extraction.

Loups Class

Main class for video processing and chapter generation

CLI Module

Command-line interface implementation using Typer

Thumbnail Extraction

SSIM-based thumbnail matching and extraction

⚡ Quick API Example

from loups import Loups

# Create Loups instance
loups = Loups(
    video_path="game_video.mp4",
    template_path="template.png"
)

# Scan for chapters
chapters = loups.scan()

# Print results
for chapter in chapters:
    print(f"{chapter.timestamp} {chapter.title}")

📦 Installation

pip install loups

Then import in your Python code:

from loups import Loups
from loups.cli import app
from loups.thumbnail_extractor import extract_thumbnail
Module Description Link
loups.loups Main Loups class Documentation
loups.cli CLI application Documentation
loups.thumbnail_extractor Thumbnail extraction Documentation
loups.match_template_scan Template matching API docs
loups.frame_utils Frame utilities API docs
loups.geometry Geometry helpers API docs

💡 Common Use Cases

Batch Processing

from pathlib import Path
from loups import Loups

videos = Path("videos").glob("*.mp4")

for video in videos:
    loups = Loups(
        video_path=str(video),
        template_path="template.png"
    )

    chapters = loups.scan()

    # Save chapters
    output = video.with_suffix(".txt")
    output.write_text("\n".join([
        f"{ch.timestamp} {ch.title}"
        for ch in chapters
    ]))

Custom Processing

from loups import Loups

loups = Loups(
    video_path="video.mp4",
    template_path="template.png",
    threshold=0.8,  # Stricter matching
    log_level="DEBUG"
)

# Access internal data
for frame_num, match in loups.matches.items():
    print(f"Frame {frame_num}: {match.confidence}")

Integration with Other Tools

from loups import Loups
import json

loups = Loups("video.mp4", "template.png")
chapters = loups.scan()

# Export as JSON
chapters_json = json.dumps([
    {
        "timestamp": ch.timestamp,
        "title": ch.title,
        "frame_number": ch.frame_number
    }
    for ch in chapters
], indent=2)

print(chapters_json)

❓ API Questions

Can I use Loups without the CLI?

Yes! The Python API is fully featured:

from loups import Loups

loups = Loups("video.mp4", "template.png")
chapters = loups.scan()
How do I access raw OCR results?

Access the internal OCR data:

loups = Loups("video.mp4", "template.png")
loups.scan()

# Access OCR results for each match
for frame_num, ocr_result in loups.ocr_results.items():
    print(f"Frame {frame_num}: {ocr_result}")
Can I customize the OCR engine?

Currently Loups uses EasyOCR. You can configure:

loups = Loups(
    video_path="video.mp4",
    template_path="template.png",
    ocr_languages=['en'],  # Languages
    ocr_confidence=0.6     # Confidence threshold
)