Skip to content

CLI Reference

Complete command-line interface documentation for Loups.

🗺 Command Structure

graph TD
    A[loups] --> B{Command Type}
    B -->|Default| C[Scan for Chapters]
    B -->|thumbnail| D[Extract Thumbnail]

    C --> C1[loups OPTIONS VIDEO]
    C1 --> C2[Process video with template matching]
    C2 --> C3[Generate YouTube chapters]

    D --> D1[loups VIDEO thumbnail OPTIONS]
    D1 --> D2[SSIM-based thumbnail extraction]
    D2 --> D3[Save thumbnail JPEG]

    style A fill:#00ffff,stroke:#000,color:#000
    style B fill:#00b8d4,stroke:#000,color:#000
    style C fill:#00ffff,stroke:#000,color:#fff
    style D fill:#00ffff,stroke:#000,color:#fff
    style C3 fill:#00ffff,stroke:#000,color:#000
    style D3 fill:#00ffff,stroke:#000,color:#000

Syntax Differences

  • Main command: loups [OPTIONS] VIDEO - Options BEFORE video
  • Thumbnail command: loups VIDEO thumbnail [OPTIONS] - Video BEFORE options

📹 Main Command: Chapter Scanning

Scan video for chapters using template matching and OCR.

Syntax

loups [OPTIONS] VIDEO

Required Arguments

Argument Description
VIDEO Path to video file (must come AFTER options)

Optional Flags

Template & Output

Flag Short Type Description
--template PATH -t Path Template image for detection
Default: Bundled Lights Out HB template
Use: Provide custom template for any video
--output PATH -o Path Save results to file in YouTube format
Format: HH:MM:SS Chapter Title per line

Logging & Debug

Flag Short Type Description
--log [PATH] -l Path Enable logging
Default: loups.log in current directory
Rotation: 10MB max, 3 backup files
--debug -d Flag Enable DEBUG level logging
Requires: --log flag
Use: Troubleshoot detection issues
--quiet -q Flag Suppress progress display
Note: Errors still shown
Use: Automation/scripting

Thumbnail Options (During Scan)

Flag Type Description
--extract-thumbnail Flag Extract thumbnail during scan
--thumbnail-template PATH Path Template for thumbnail matching
Default: Uses bundled template
--thumbnail-output PATH Path Thumbnail save location
Default: <video>-thumbnail.jpg
--thumbnail-threshold FLOAT 0.0-1.0 SSIM similarity threshold
Default: 0.35
Range: 0.0 (loose) to 1.0 (exact)
--thumbnail-scan-duration INT Seconds Max seconds to scan from start
Default: 120 seconds
--thumbnail-frames-per-second INT FPS Frame sampling rate
Default: 3 FPS

Examples

Basic Usage

# Use bundled template (Lights Out HB)
loups game_video.mp4

# Custom template
loups -t scoreboard.png video.mp4

# Save to file
loups -o chapters.txt video.mp4

# Custom template + save
loups -t template.png -o chapters.txt video.mp4

Logging & Debug

# Enable default logging
loups --log video.mp4

# Custom log file
loups --log /tmp/debug.log video.mp4

# Debug mode for troubleshooting
loups --log --debug video.mp4

Quiet Mode

# Suppress progress (for scripts)
loups -q -o chapters.txt video.mp4

# Combine with logging
loups -q --log --debug -o output.txt video.mp4

Combined with Thumbnail

# Extract thumbnail during scan
loups --extract-thumbnail -o chapters.txt video.mp4

# Custom thumbnail settings
loups --extract-thumbnail \
      --thumbnail-template title.png \
      --thumbnail-output thumb.jpg \
      --thumbnail-threshold 0.5 \
      -o chapters.txt \
      video.mp4

🖼 Thumbnail Command

Extract thumbnail using SSIM-based template matching.

Syntax

loups VIDEO thumbnail [OPTIONS]

Note the Order

Unlike the main command, VIDEO comes BEFORE the thumbnail keyword.

Required Arguments

Argument Description
VIDEO Path to video file
thumbnail Subcommand keyword

Optional Flags

Flag Type Description
--thumbnail-template PATH Path Template image for matching
Default: Bundled template
--thumbnail-output PATH Path Output file path
Default: <video>-thumbnail.jpg in cwd
--thumbnail-threshold FLOAT 0.0-1.0 SSIM similarity threshold
Default: 0.35
--thumbnail-scan-duration INT Seconds Max seconds to scan
Default: 120
--thumbnail-frames-per-second INT FPS Frame sampling rate
Default: 3
--quiet Flag Suppress output

Examples

Basic Thumbnail Extraction

# Use default settings
loups video.mp4 thumbnail

# Custom output location
loups video.mp4 thumbnail --thumbnail-output ./thumbnails/game1.jpg

# Custom template
loups video.mp4 thumbnail --thumbnail-template title_screen.png

Advanced Thumbnail Settings

# Stricter matching (higher threshold)
loups video.mp4 thumbnail --thumbnail-threshold 0.7

# Scan longer duration
loups video.mp4 thumbnail --thumbnail-scan-duration 300

# Sample more frames per second
loups video.mp4 thumbnail --thumbnail-frames-per-second 5

Batch Thumbnail Extraction

# Process multiple videos
for video in *.mp4; do
  loups "$video" thumbnail --thumbnail-output "thumbs/${video%.mp4}.jpg"
done

💡 Tips & Best Practices

Option Order

Correct Order

loups [OPTIONS] VIDEO          # Main command
loups VIDEO thumbnail [OPTIONS] # Thumbnail command

Incorrect Order

loups VIDEO [OPTIONS]           # Won't work!
loups thumbnail VIDEO [OPTIONS] # Won't work!

Template Quality

Good Templates

  • High contrast, clear text
  • Consistent position in video
  • No motion blur
  • Tightly cropped around target

Poor Templates

  • Blurry or low resolution
  • Includes moving elements
  • Too large (includes extra regions)
  • Inconsistent across video

Logging Strategies

# Full debug logging
loups --log debug.log --debug -t template.png video.mp4

# Check the log
tail -f debug.log

# Quiet mode, log errors only
loups -q --log errors.log video.mp4

# Minimal output, errors to log
loups -q --log /var/log/loups.log -o output.txt video.mp4

Exit Codes

Code Meaning
0 Success
1 Error occurred
2 Invalid arguments

Use in scripts:

if loups -q -o chapters.txt video.mp4; then
  echo "Success!"
else
  echo "Failed with exit code $?"
fi