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 報告範本