video-comparer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Video Comparer

视频比较工具

Overview

概述

Compare two videos and generate an interactive HTML report analyzing compression results. The script extracts video metadata, calculates quality metrics (PSNR, SSIM), and creates frame-by-frame visual comparisons with three viewing modes: slider, side-by-side, and grid.

比较两个视频并生成分析压缩结果的交互式HTML报告。该脚本会提取视频元数据，计算质量指标（PSNR、SSIM），并创建三种查看模式的逐帧视觉对比：滑块模式、并排模式和网格模式。

When to Use This Skill

何时使用此技能

Use this skill when:

Comparing original and compressed videos
Analyzing video compression quality and efficiency
Evaluating codec performance or bitrate reduction impact
Users mention "compare videos", "video quality", "compression analysis", or "before/after compression"

在以下场景使用此技能：

比较原始视频与压缩后的视频
分析视频压缩的质量和效率
评估编解码器性能或比特率降低的影响
用户提及“比较视频”、“视频质量”、“压缩分析”或“压缩前后”时

Core Usage

核心用法

Basic Command

基础命令

bash

python3 scripts/compare.py original.mp4 compressed.mp4

Generates

comparison.html

with:

Video parameters (codec, resolution, bitrate, duration, file size)
Quality metrics (PSNR, SSIM, size/bitrate reduction percentages)
Frame-by-frame comparison (default: frames at 5s intervals)

bash

python3 scripts/compare.py original.mp4 compressed.mp4

生成包含以下内容的

comparison.html

文件：

视频参数（编解码器、分辨率、比特率、时长、文件大小）
质量指标（PSNR、SSIM、大小/比特率降低百分比）
逐帧对比（默认：每5秒提取一帧）

Command Options

命令选项

bash

undefined

bash

undefined

Custom output file

自定义输出文件

python3 scripts/compare.py original.mp4 compressed.mp4 -o report.html

Custom frame interval (larger = fewer frames, faster processing)

自定义帧间隔（值越大，提取的帧越少，处理速度越快）

python3 scripts/compare.py original.mp4 compressed.mp4 --interval 10

Batch comparison

批量比较

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

undefined

undefined

Requirements

要求

System Dependencies

系统依赖

FFmpeg and FFprobe (required for video analysis and frame extraction):

bash

undefined

FFmpeg 和 FFprobe（用于视频分析和帧提取的必备工具）：

bash

undefined

macOS

brew install ffmpeg

Ubuntu/Debian

sudo apt update && sudo apt install ffmpeg

Windows

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

从 https://ffmpeg.org/download.html 下载

Or use: winget install ffmpeg

或使用：winget install ffmpeg


**Python 3.8+** (uses type hints, f-strings, pathlib)


**Python 3.8+**（使用类型提示、f-string、pathlib）

Video Specifications

视频规格

Supported formats:
```
.mp4
```
(recommended),
```
.mov
```
,
```
.avi
```
,
```
.mkv
```
,
```
.webm
```
File size limit: 500MB per video (configurable)
Processing time: ~1-2 minutes for typical videos; varies by duration and frame interval

支持格式：
```
.mp4
```
（推荐）、
```
.mov
```
、
```
.avi
```
、
```
.mkv
```
、
```
.webm
```
文件大小限制：每个视频最大500MB（可配置）
处理时间：典型视频约1-2分钟；具体时长取决于视频长度和帧间隔

Script Behavior

脚本行为

Automatic Validation

自动验证

The script automatically validates:

FFmpeg/FFprobe installation and availability
File existence, extensions, and size limits
Path security (prevents directory traversal)

Clear error messages with resolution guidance appear when validation fails.

脚本会自动验证以下内容：

FFmpeg/FFprobe是否已安装且可用
文件是否存在、扩展名是否合法、是否符合大小限制
路径安全性（防止目录遍历）

当验证失败时，会显示清晰的错误消息及解决指南。

Quality Metrics

质量指标

The script calculates two standard quality metrics:

PSNR (Peak Signal-to-Noise Ratio): Pixel-level similarity measurement (20-50 dB scale, higher is better)

SSIM (Structural Similarity Index): Perceptual similarity measurement (0.0-1.0 scale, higher is better)

For detailed interpretation scales and quality thresholds, consult

references/video_metrics.md

脚本会计算两种标准质量指标：

PSNR（峰值信噪比）：像素级相似性度量（范围20-50 dB，值越高越好）

SSIM（结构相似性指数）：感知相似性度量（范围0.0-1.0，值越高越好）

如需详细的解释标尺和质量阈值，请查阅

references/video_metrics.md

。

Frame Extraction

帧提取

The script extracts frames at specified intervals (default: 5 seconds), scales them to consistent height (800px) for comparison, and embeds them as base64 data URLs in self-contained HTML. Temporary files are automatically cleaned after processing.

脚本会按指定间隔提取帧（默认：5秒），将其缩放至统一高度（800px）以进行比较，并将其作为base64数据URL嵌入到独立的HTML文件中。处理完成后会自动清理临时文件。

Output Report

输出报告

The generated HTML report includes:

Slider Mode: Drag to reveal original vs compressed (default)
Side-by-Side Mode: Simultaneous display for direct comparison
Grid Mode: Compact 2-column layout
Zoom Controls: 50%-200% magnification
Self-contained format (no server required, works offline)

生成的HTML报告包含：

滑块模式：拖动滑块显示原始视频与压缩视频的对比（默认模式）
并排模式：同时显示两个视频以便直接对比
网格模式：紧凑的双列布局
缩放控制：50%-200%的放大倍数
独立格式（无需服务器，可离线使用）

Important Implementation Details

重要实现细节

Security

安全性

The script implements:

Path validation (absolute paths, prevents directory traversal)
Command injection prevention (no
```
shell=True
```
, validated arguments)
Resource limits (file size, timeouts)

Custom exceptions:

ValidationError

FFmpegError

VideoComparisonError

脚本实现了以下安全措施：

路径验证（绝对路径，防止目录遍历）
命令注入防护（不使用
```
shell=True
```
，验证参数）
资源限制（文件大小、超时时间）

自定义异常：

ValidationError

、

FFmpegError

、

VideoComparisonError

Common Error Scenarios

常见错误场景

"FFmpeg not found": Install FFmpeg via platform package manager (see Requirements section)

"File too large": Compress videos before comparison, or adjust

MAX_FILE_SIZE_MB

scripts/compare.py

"Operation timed out": Increase

FFMPEG_TIMEOUT

constant or use larger

--interval

value (processes fewer frames)

"Frame count mismatch": Videos have different durations/frame rates; script auto-truncates to minimum frame count and shows warning

"FFmpeg not found"：通过平台包管理器安装FFmpeg（参见要求部分）

"File too large"：在比较前压缩视频，或调整

scripts/compare.py

中的

MAX_FILE_SIZE_MB

参数

"Operation timed out"：增大

FFMPEG_TIMEOUT

常量，或使用更大的

--interval

值（处理更少的帧）

"Frame count mismatch"：视频的时长/帧率不同；脚本会自动截断至最小帧数并显示警告

Configuration

配置

The script includes adjustable constants for file size limits, timeouts, frame dimensions, and extraction intervals. To customize behavior, edit the constants at the top of

scripts/compare.py

. For detailed configuration options and their impacts, consult

references/configuration.md

脚本包含可调整的常量，用于设置文件大小限制、超时时间、帧尺寸和提取间隔。如需自定义行为，请编辑

scripts/compare.py

顶部的常量。有关详细的配置选项及其影响，请查阅

references/configuration.md

。

Reference Materials

参考资料

Consult these files for detailed information:

references/video_metrics.md
: Quality metrics interpretation (PSNR/SSIM scales, compression targets, bitrate guidelines)
references/ffmpeg_commands.md
: FFmpeg command reference (metadata extraction, frame extraction, troubleshooting)
references/configuration.md
: Script configuration options and adjustable constants
assets/template.html
: HTML report template for customizing viewing modes and styling

查阅以下文件获取详细信息：

references/video_metrics.md
：质量指标解读（PSNR/SSIM标尺、压缩目标、比特率指南）
references/ffmpeg_commands.md
：FFmpeg命令参考（元数据提取、帧提取、故障排除）
references/configuration.md
：脚本配置选项和可调整常量
assets/template.html
：HTML报告模板，用于自定义查看模式和样式