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文字列、pathlib を使用）

ビデオ仕様

• 対応フォーマット: .mp4（推奨）、.mov、.avi、.mkv、.webm
• ファイルサイズ制限: ビデオあたり500MB（設定可能）
• 処理時間: 標準的なビデオで約1～2分。期間とフレーム間隔によって異なります

スクリプトの動作

自動検証

スクリプトは自動的に以下を検証します:

• FFmpeg/FFprobe のインストールと可用性
• ファイルの存在、拡張子、サイズ制限
• パスセキュリティ（ディレクトリトラバーサルを防止）

検証が失敗すると、解決ガイダンス付きの明確なエラーメッセージが表示されます。

品質メトリクス

スクリプトは2つの標準的な品質メトリクスを計算します:

PSNR（Peak Signal-to-Noise Ratio）: ピクセルレベルの類似度測定（20～50 dB スケール、高いほど良い）

SSIM（Structural Similarity Index）: 知覚的類似度測定（0.0～1.0 スケール、高いほど良い）

詳細な解釈スケールと品質閾値については、references/video_metrics.md を参照してください。

フレーム抽出

スクリプトは指定された間隔（デフォルト: 5秒）でフレームを抽出し、比較用に一貫した高さ（800px）にスケーリングし、base64データURLとして自己完結型HTMLに埋め込みます。処理後、一時ファイルは自動的にクリーンアップされます。

出力レポート

生成される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レポートテンプレート