Video Comparer
概述
比较两个视频,生成交互式 HTML 报告,分析压缩结果。该脚本提取视频元数据,计算质量指标(PSNR、SSIM),并创建逐帧视觉对比,提供三种查看模式:滑块、并排和网格。
何时使用此技能
在以下情况下使用此技能:
- 比较原始视频和压缩后的视频
- 分析视频压缩质量和效率
- 评估编解码器性能或比特率降低的影响
- 用户提及“比较视频”、“视频质量”、“压缩分析”或“压缩前后对比”
核心用法
基本命令
python3 scripts/compare.py original.mp4 compressed.mp4
生成 comparison.html,其中包含:
- 视频参数(编解码器、分辨率、比特率、时长、文件大小)
- 质量指标(PSNR、SSIM、大小/比特率降低百分比)
- 逐帧对比(默认:每 5 秒间隔一帧)
命令选项
# 自定义输出文件
python3 scripts/compare.py original.mp4 compressed.mp4 -o report.html
# 自定义帧间隔(间隔越大,帧数越少,处理速度越快)
python3 scripts/compare.py original.mp4 compressed.mp4 --interval 10
# 批量比较
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
系统要求
系统依赖项
FFmpeg 和 FFprobe(视频分析和帧提取必需):
# macOS
brew install ffmpeg
# Ubuntu/Debian
sudo apt update && sudo apt install ffmpeg
# Windows
# 从 https://ffmpeg.org/download.html 下载
# 或使用:winget install ffmpeg
Python 3.8+(使用类型提示、f-string、pathlib)
视频规范
- 支持格式:
.mp4(推荐)、.mov、.avi、.mkv、.webm - 文件大小限制: 每个视频 500MB(可配置)
- 处理时间: 典型视频约 1-2 分钟;根据时长和帧间隔而变化
脚本行为
自动验证
脚本自动验证:
- FFmpeg/FFprobe 是否已安装且可用
- 文件是否存在、扩展名和大小限制
- 路径安全性(防止目录遍历)
验证失败时会显示清晰的错误消息及解决指南。
质量指标
脚本计算两个标准质量指标:
PSNR(峰值信噪比): 像素级相似度测量(20-50 dB 范围,越高越好)
SSIM(结构相似性指数): 感知相似度测量(0.0-1.0 范围,越高越好)
有关详细的解释范围和质量阈值,请参阅 references/video_metrics.md。
帧提取
脚本按指定间隔(默认:5 秒)提取帧,缩放至统一高度(800px)以便比较,并将其作为 base64 数据 URL 嵌入到独立的 HTML 中。处理完成后自动清理临时文件。
输出报告
生成的 HTML 报告包含:
- 滑块模式: 拖动滑块显示原始与压缩对比(默认)
- 并排模式: 同时显示以直接比较
- 网格模式: 紧凑的两列布局
- 缩放控制: 50%-200% 放大
- 独立格式(无需服务器,可离线使用)
重要实现细节
安全性
脚本实现了:
- 路径验证(绝对路径,防止目录遍历)
- 命令注入防护(无
shell=True,参数经过验证) - 资源限制(文件大小、超时)
- 自定义异常:
ValidationError、FFmpegError、VideoComparisonError
常见错误场景
“未找到 FFmpeg”:通过平台包管理器安装 FFmpeg(参见系统要求部分)
“文件太大”:在比较前压缩视频,或调整 scripts/compare.py 中的 MAX_FILE_SIZE_MB
“操作超时”:增加 FFMPEG_TIMEOUT 常量,或使用更大的 --interval 值(处理帧数更少)
“帧数不匹配”:视频时长/帧率不同;脚本自动截断至最小帧数并显示警告
配置
脚本包含可调整的常量,用于文件大小限制、超时时间、帧尺寸和提取间隔。要自定义行为,请编辑 scripts/compare.py 顶部的常量。有关详细的配置选项及其影响,请参阅 references/configuration.md。
参考资料
请查阅以下文件获取详细信息:
references/video_metrics.md:质量指标解释(PSNR/SSIM 范围、压缩目标、比特率指南)references/ffmpeg_commands.md:FFmpeg 命令参考(元数据提取、帧提取、故障排除)references/configuration.md:脚本配置选项和可调整常量assets/template.html:用于自定义查看模式和样式的 HTML 报告模板