用途
Video Comparer 用于对比两个视频，分析压缩结果或画质差异。当需要对比原始视频与压缩视频、分析视频压缩质量与效率、评估编解码器性能或码率降低带来的影响时，可以使用该技能。用户提及“compare videos”“video quality”“compression analysis”或“before/after compression”等需求时同样适用。
主要能力
该技能通过脚本提取视频元数据，计算质量指标（PSNR、SSIM），并生成逐帧视觉对比的交互式 HTML 报告。报告包含三种查看模式：滑块模式（拖动以显示原始与压缩视频的对比，为默认模式）、并排模式（同时显示以便直接对比）、网格模式（紧凑的双列布局）。报告还提供 50%-200% 的缩放控制，且为自包含格式，无需服务器，可离线使用。
报告内容包括：视频参数（编解码器、分辨率、码率、时长、文件大小）、质量指标（PSNR、SSIM、大小/码率降低百分比）、逐帧对比（默认提取间隔为 5 秒的帧）。
质量指标说明：PSNR（峰值信噪比）为像素级相似度测量，范围 20-50 dB，越高越好；SSIM（结构相似性指数）为感知相似度测量，范围 0.0-1.0，越高越好。详细解读标尺与质量阈值可参考 references/video_metrics.md。
使用方式
基本命令：
python3 scripts/compare.py original.mp4 compressed.mp4
该命令生成 comparison.html。
自定义输出文件：
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-strings、pathlib）。
视频规格：支持格式为 .mp4（推荐）、.mov、.avi、.mkv、.webm；文件大小限制为每个视频 500MB（可配置）；典型视频处理时间约 1-2 分钟，具体取决于时长和帧间隔。
脚本行为
自动验证：脚本会自动验证 FFmpeg/FFprobe 的安装与可用性、文件存在性、扩展名和大小限制、路径安全性（防止目录遍历）。验证失败时会显示清晰的错误信息和解决指引。
帧提取：脚本按指定间隔（默认 5 秒）提取帧，将其缩放至统一高度（800px）以便对比，并以 base64 数据 URL 嵌入自包含 HTML 中。处理完成后会自动清理临时文件。
安全与错误处理
脚本实现了路径验证（绝对路径，防止目录遍历）、命令注入防护（不使用 shell=True，验证参数）、资源限制（文件大小、超时），并定义了自定义异常：ValidationError、FFmpegError、VideoComparisonError。
常见错误场景：
“FFmpeg not found”：通过平台包管理器安装 FFmpeg（见环境要求）。
“File too large”：对比前先压缩视频，或调整 scripts/compare.py 中的 MAX_FILE_SIZE_MB。
“Operation timed out”：增大 FFMPEG_TIMEOUT 常量，或使用更大的 --interval 值（处理更少的帧）。
“Frame count mismatch”：视频时长/帧率不同；脚本会自动截断至最小帧数并显示警告。
配置与参考材料
脚本包含可调整的常量，用于文件大小限制、超时、帧尺寸和提取间隔。要自定义行为，可编辑 scripts/compare.py 顶部的常量。详细配置选项及其影响可参考 references/configuration.md。
参考材料：references/video_metrics.md（质量指标解读：PSNR/SSIM 标尺、压缩目标、码率指南）；references/ffmpeg_commands.md（FFmpeg 命令参考：元数据提取、帧提取、故障排除）；references/configuration.md（脚本配置选项与可调整常量）；assets/template.html（HTML 报告模板，用于自定义查看模式和样式）。