影片比較器
概述
比較兩部影片並生成互動式 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-字串、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 報告包含:
- **滑桿模式:**拖曳以顯示原始 vs 壓縮(預設)
- **並排模式:**同時顯示以便直接比較
- **網格模式:**緊湊的兩欄佈局
- **縮放控制:**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 報告模板