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