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)にスケーリングし、自己完結型HTMLにbase64データURLとして埋め込みます。処理後、一時ファイルは自動的に削除されます。
出力レポート
生成されたHTMLレポートには以下が含まれます:
- スライダーモード: ドラッグしてオリジナルと圧縮を切り替え(デフォルト)
- サイドバイサイドモード: 直接比較するための同時表示
- グリッドモード: コンパクトな2カラムレイアウト
- ズームコントロール: 50%〜200%の拡大表示
- 自己完結型フォーマット(サーバー不要、オフラインでも動作)
重要な実装の詳細
セキュリティ
スクリプトは以下を実装しています:
- パス検証(絶対パス、ディレクトリトラバーサル防止)
- コマンドインジェクション防止(
shell=True不使用、引数を検証) - リソース制限(ファイルサイズ、タイムアウト)
- カスタム例外:
ValidationError、FFmpegError、VideoComparisonError
よくあるエラーシナリオ
「FFmpeg not found」:プラットフォームのパッケージマネージャーを使用してFFmpegをインストールしてください(必要条件のセクションを参照)
「File too large」:比較する前に動画を圧縮するか、scripts/compare.py の MAX_FILE_SIZE_MB を調整してください
「Operation timed out」:FFMPEG_TIMEOUT 定数を増やすか、より大きな --interval 値を使用してください(処理するフレーム数が減ります)
「Frame count mismatch」:動画の長さまたはフレームレートが異なります。スクリプトは自動的に最小フレーム数に切り詰め、警告を表示します
設定
スクリプトには、ファイルサイズ制限、タイムアウト、フレーム寸法、抽出間隔の調整可能な定数が含まれています。動作をカスタマイズするには、scripts/compare.py の上部にある定数を編集してください。詳細な設定オプションとその影響については、references/configuration.md を参照してください。
参考資料
詳細情報については、以下のファイルを参照してください:
references/video_metrics.md:品質指標の解釈(PSNR/SSIMスケール、圧縮目標、ビットレートガイドライン)references/ffmpeg_commands.md:FFmpegコマンドリファレンス(メタデータ抽出、フレーム抽出、トラブルシューティング)references/configuration.md:スクリプト設定オプションと調整可能な定数assets/template.html:表示モードとスタイルをカスタマイズするためのHTMLレポートテンプレート