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-strings、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 報告包含:
- 滑桿模式: 拖曳顯示原始與壓縮版本對比(預設)
- 並排模式: 同時顯示,便於直接比較
- 網格模式: 緊湊的 2 欄佈局
- 縮放控制: 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 報告範本,用於自訂檢視模式與樣式