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-string、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レポートテンプレート