video-diff-checker 0.1.0

A CLI tool that compares two video files and automates pixel-level diff detection

Video Diff Checker

2つの動画ファイル（旧版/新版）を比較し、ピクセルレベルの差分検出・区間抽出・グリッド比較動画生成・レポート出力を自動化する Python CLI ツール。

特徴

• フレーム単位のピクセル差分検出（PSNR/SSIM スコア算出）
• 変化区間の自動検出とパート動画抽出（マージン・統合ギャップの調整可）
• 2x2 グリッド比較動画の生成（旧版 / 新版 / 差分 / 情報パネル）
• 変更サマリーレポート出力（JSON / テキスト形式）
• compare コマンドで差分検出からレポート生成まで一括実行

前提条件

• Python 3.10 以上
• FFmpeg 6.0 以上（PATH に含まれている必要あり）
• 対応 OS: Windows 10/11, macOS 12+, Ubuntu 22.04+

インストール

pip install video-diff-checker

開発用:

git clone https://github.com/Hidano/VideoDiffChecker.git
cd VideoDiffChecker
pip install -e ".[dev]"

使い方

一括実行（compare）

差分検出 → 区間特定 → パート抽出 → グリッド生成 → レポート出力を一括で実行する。

video-diff-checker compare old.mp4 new.mp4

出力先を指定する場合:

video-diff-checker compare old.mp4 new.mp4 -o ./output/

閾値やマージンを調整する場合:

video-diff-checker compare old.mp4 new.mp4 --threshold 0.90 --margin 60 --merge-gap 20

差分検出のみ（diff）

フレーム単位のピクセル差分動画とスコア CSV を生成する。

video-diff-checker diff old.mp4 new.mp4
video-diff-checker diff old.mp4 new.mp4 -o ./output/

区間検出（detect）

スコア CSV を解析し、変化区間を特定して segments.json を出力する。

video-diff-checker detect scores.csv
video-diff-checker detect scores.csv --threshold 0.90 --margin 60 --merge-gap 20 --fps 24.0

パート動画抽出（extract）

segments.json に基づき、旧版・新版・差分動画からパート動画を切り出す。

video-diff-checker extract old.mp4 new.mp4 diff.mp4 --segments segments.json

グリッド比較動画生成（grid）

2x2 グリッド比較動画（旧版 / 新版 / 差分 / 情報パネル）を生成する。

video-diff-checker grid old.mp4 new.mp4 diff.mp4 --segments segments.json

レポート生成（report）

スコア CSV と segments.json から変更サマリーレポートを生成する。

video-diff-checker report scores.csv segments.json
video-diff-checker report scores.csv segments.json --format json

コマンドリファレンス

共通オプション

以下のオプションは compare, diff, detect, extract, grid で共通で使用できる（report を除く）。

オプション	短縮形	説明	デフォルト
--verbose	-v	詳細ログを出力する	false
--threshold	-t	SSIM ベースの閾値（0.0 - 1.0）	0.95
--gpu	-	GPU アクセラレーションを使用する	false

compare

引数/オプション	説明	デフォルト
old (必須)	旧動画ファイルのパス	-
new (必須)	新動画ファイルのパス	-
--output, -o	出力ディレクトリのパス	./vdc-output/
--margin	セグメント前後に追加するマージン（フレーム数）	30
--merge-gap	セグメント統合のギャップ閾値（フレーム数）	15

diff

引数/オプション	説明	デフォルト
old (必須)	旧動画ファイルのパス	-
new (必須)	新動画ファイルのパス	-
--output, -o	出力ディレクトリのパス	./vdc-output/

detect

引数/オプション	説明	デフォルト
scores_csv (必須)	スコア CSV ファイルのパス	-
--margin	セグメント前後に追加するマージン（フレーム数）	30
--merge-gap	セグメント統合のギャップ閾値（フレーム数）	15
--fps	フレームレート（時刻計算用）	30.0
--output, -o	出力ディレクトリのパス	./vdc-output/

extract

引数/オプション	説明	デフォルト
old (必須)	旧動画ファイルのパス	-
new (必須)	新動画ファイルのパス	-
diff (必須)	差分動画ファイルのパス	-
--segments (必須)	segments.json ファイルのパス	-
--output, -o	出力ディレクトリのパス	./vdc-output/
--workers	並列ワーカー数の上限	CPU コア数

grid

引数/オプション	説明	デフォルト
old (必須)	旧動画ファイルのパス	-
new (必須)	新動画ファイルのパス	-
diff (必須)	差分動画ファイルのパス	-
--segments (必須)	segments.json ファイルのパス	-
--output, -o	出力ディレクトリのパス	./vdc-output/
--workers	並列ワーカー数の上限	CPU コア数

report

引数/オプション	説明	デフォルト
scores_csv (必須)	スコア CSV ファイルのパス	-
segments_json (必須)	segments.json ファイルのパス	-
--output, -o	出力ディレクトリのパス	./vdc-output/
--format	出力形式（json / text / all）	all
--verbose, -v	詳細ログを出力する	false

処理フロー

compare コマンドは以下の 4 ステージをパイプラインで順次実行する。各ステージは個別のサブコマンドとしても単独で使用できる。

diff --> detect --> extract --> grid --> report
(F-01)   (F-02)    (F-02)     (F-03)   (F-04)

1. diff (F-01): FFmpeg の blend=all_mode=difference フィルタでフレーム単位のピクセル差分動画を生成し、PSNR/SSIM スコアを CSV に出力する
2. detect (F-02): スコア CSV を閾値で解析し、変化区間（セグメント）を特定する。マージン追加や近接セグメントの統合を行う
3. extract (F-02): 特定されたセグメントに基づき、旧版・新版・差分動画からパート動画を切り出す
4. grid (F-03): パート動画を 2x2 グリッド（旧版 / 新版 / 差分 / 情報パネル）に合成し、drawtext でオーバーレイを付与する
5. report (F-04): スコアとセグメント情報から変更サマリーレポートを JSON/テキスト形式で生成する

ライセンス

MIT License. 詳細は LICENSE を参照。