Video Comparer
概要
2つの動画を比較し、圧縮結果を分析するインタラクティブなHTMLレポートを生成します。このスクリプトは動画メタデータを抽出し、品質メトリクス(PSNR、SSIM)を計算し、スライダー、サイドバイサイド、グリッドの3つの表示モードでフレームごとの視覚比較を作成します。
このスキルを使用するタイミング
以下の場合にこのスキルを使用してください:
- オリジナル動画と圧縮動画を比較する
- 動画圧縮の品質と効率を分析する
- コーデックのパフォーマンスやビットレート削減の影響を評価する
- ユーザーが「動画を比較」「動画品質」「圧縮分析」「圧縮前/圧縮後」に言及している
基本的な使い方
基本コマンド
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 - ファイルサイズ制限: 1動画あたり500MB(設定変更可能)
- 処理時間: 一般的な動画で約1〜2分。再生時間とフレーム間隔によって変動
スクリプトの動作
自動検証
スクリプトは以下を自動的に検証します:
- FFmpeg/FFprobeのインストールと使用可能性
- ファイルの存在、拡張子、サイズ制限
- パスの安全性(ディレクトリトラバーサルを防止)
検証に失敗した場合、解決策を示す明確なエラーメッセージが表示されます。
品質メトリクス
スクリプトは2つの標準品質メトリクスを計算します:
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レポートテンプレート