影片比較器
概述
比較兩部影片並產生一個互動式 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 報告包含:
- 滑桿模式: 拖曳以揭示原始與壓縮畫面(預設)
- 並排模式: 同時顯示以進行直接比較
- 網格模式: 緊湊的 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 報告範本