Metadata-Version: 2.4
Name: video-diff-checker
Version: 0.1.0
Summary: A CLI tool that compares two video files and automates pixel-level diff detection
Author: Hidano
License-Expression: MIT
Project-URL: Homepage, https://github.com/Hidano/VideoDiffChecker
Project-URL: Repository, https://github.com/Hidano/VideoDiffChecker
Project-URL: Issues, https://github.com/Hidano/VideoDiffChecker/issues
Project-URL: Changelog, https://github.com/Hidano/VideoDiffChecker/blob/main/CHANGELOG.md
Keywords: video,diff,comparison,ffmpeg
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Environment :: Console
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# 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+

## インストール

```bash
pip install video-diff-checker
```

開発用:

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

## 使い方

### 一括実行（compare）

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

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

出力先を指定する場合:

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

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

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

### 差分検出のみ（diff）

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

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

### 区間検出（detect）

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

```bash
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 に基づき、旧版・新版・差分動画からパート動画を切り出す。

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

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

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

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

### レポート生成（report）

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

```bash
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](LICENSE) を参照。
