video-comparer

Compare two videos and generate interactive HTML reports with quality metrics (PSNR, SSIM) and frame-by-frame visual comparisons. Use when analyzing compression results, evaluating codec performance, or assessing video quality differences

Installation

npx claude-plugins install @daymade/daymade-skills/video-comparer

Contents

Folders: assets, references, scripts

Files: README.md, SKILL.md

Documentation

A professional video comparison tool that analyzes compression quality and generates interactive HTML reports. Compare original vs compressed videos with detailed metrics (PSNR, SSIM) and frame-by-frame visual comparisons.

Features

🎯 Video Analysis

• Metadata Extraction: Codec, resolution, frame rate, bitrate, duration, file size
• Quality Metrics: PSNR (Peak Signal-to-Noise Ratio) and SSIM (Structural Similarity Index)
• Compression Analysis: Size and bitrate reduction percentages

🖼️ Interactive Comparison

• Three Viewing Modes:
  • Slider Mode: Interactive before/after slider using img-comparison-slider
  • Side-by-Side Mode: Simultaneous display of both frames
  • Grid Mode: Compact 2-column layout
• Zoom Controls: 50%-200% zoom with real image dimension scaling
• Responsive Design: Works on desktop, tablet, and mobile

🔒 Security & Reliability

• Path Validation: Prevents directory traversal attacks
• Command Injection Prevention: No shell=True in subprocess calls
• Resource Limits: File size and timeout restrictions
• Comprehensive Error Handling: User-friendly error messages

Quick Start

Prerequisites

1. Python 3.8+ (for type hints and modern features)
2. FFmpeg (required for video analysis)

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Windows
# Download from https://ffmpeg.org/download.html

Basic Usage

# Navigate to the skill directory
cd /path/to/video-comparer

# Compare two videos
python3 scripts/compare.py original.mp4 compressed.mp4

# Open the generated report
open comparison.html  # macOS
# or
xdg-open comparison.html  # Linux
# or
start comparison.html  # Windows

Command Line Options

python3 scripts/compare.py <original> <compressed> [options]

Arguments:
  original      Path to original video file
  compressed    Path to compressed video file

Options:
  -o, --output PATH     Output HTML report path (default: comparison.html)
  --interval SECONDS    Frame extraction interval in seconds (default: 5)
  -h, --help           Show help message

Examples

# Basic comparison
python3 scripts/compare.py original.mp4 compressed.mp4

# Custom output file
python3 scripts/compare.py original.mp4 compressed.mp4 -o report.html

# Extract frames every 10 seconds (fewer frames, faster processing)
python3 scripts/compare.py original.mp4 compressed.mp4 --interval 10

# Compare with absolute paths
python3 scripts/compare.py ~/Videos/original.mov ~/Videos/compressed.mov

# Batch comparison
for original in originals/*.mp4; do
    compressed="compressed/$(basename "$original")"
    python3 scripts/compare.py "$original" "$compressed" -o "reports/$(basename "$original" .mp4).html"
done

Supported Formats

Output Report

The generated HTML report includes:

1. Video Parameters Comparison

• Codec: Video compression format (h264, hevc, vp9, etc.)
• Resolution: Width × Height in pixels
• Frame Rate: Frames per second
• Bitrate: Data rate (kbps/Mbps)
• Duration: Total video length
• File Size: Storage requirement
• Filenames: Original file names

2. Quality Analysis

• Size Reduction: Percentage of storage saved
• Bitrate Reduction: Percentage of bandwidth saved
• PSNR: Peak Signal-to-Noise Ratio (dB)
  • 30-35 dB: Acceptable quality
  • 35-40 dB: Good quality
  • 40+ dB: Excellent quality
• SSIM: Structural Similarity Index (0.0-1.0)
  • 0.90-0.95: Good quality
  • 0.95-0.98: Very good quality
  • 0.98+: Excellent quality

3. Frame-by-Frame Comparison

• Interactive slider for detailed comparison
• Side-by-side viewing for overall assessment
• Grid layout for quick scanning
• Zoom controls (50%-200%)
• Timestamp labels for each frame

Configuration

Constants in scripts/compare.py

ALLOWED_EXTENSIONS = {'.mp4', '.mov', '.avi', '.mkv', '.webm'}
MAX_FILE_SIZE_MB = 500          # Maximum file size limit
FFMPEG_TIMEOUT = 300            # FFmpeg timeout (5 minutes)
FFPROBE_TIMEOUT = 30            # FFprobe timeout (30 seconds)
BASE_FRAME_HEIGHT = 800         # Frame height for comparison
FRAME_INTERVAL = 5              # Default frame extraction interval

Customizing Frame Resolution

To change the frame resolution for comparison:

# In scripts/compare.py
BASE_FRAME_HEIGHT = 1200  # Higher resolution (larger file size)
# or
BASE_FRAME_HEIGHT = 600   # Lower resolution (smaller file size)

Performance

Processing Time

• Metadata Extraction: < 5 seconds
• Quality Metrics: 1-2 minutes (depends on video duration)
• Frame Extraction: 30-60 sec

Source

View on GitHub