# Video Analysis Core

> 動画の全フレームをローカルで数値解析し、代表画像、未確認変化の補完、指定区間の画像列を取得してCodexで視覚分析する。動画レビューや内容確認で画像抽出が必要なときに使う。専用OCRや生成サービスを使わず、意味判断は画像を見て行う。

- Skill: `ryryo/video-analysis-core` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add ryryo/video-analysis-core`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ryryo/video-analysis-core/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ryryo (https://skillmd.com/u/ryryo)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/ryryo/video-analysis-core

---


# 動画の画像解析基盤

数値処理で見る画像を絞り、返された画像をCodexが実際に読む。CLIは画像を渡すところまでを担い、意味・品質・採否を判定しない。生成動画の合否判断は [review-generated-video](../review-generated-video/SKILL.md) を使う。

## 実行環境と保存

同梱の [video_analysis.py](scripts/video_analysis.py) を使う。Python 3.11以上、NumPy、FFmpeg／ffprobeが必要。利用可能な環境を確認し、不足していれば既存の依存環境を探す。特定project、動画名、実験データ、OCR出力への依存はない。ネットワークや生成APIは呼ばない。

保存を依頼されていなければ `--out` を省略する。一時ディレクトリに画像と処理状態を置き、報告は会話内で返す。`review.md` やリポジトリ内の解析成果物は自動作成しない。永続的な画像出力を求められた場合だけ `--out NEW_DIRECTORY` を指定する。既存ディレクトリは上書きしない。

以下の `<skill>` はこのスキルのディレクトリ、`<session>` はprepareのJSONが返した絶対パス。

## 1. 数値解析と代表画像の取得

```bash
python3 <skill>/scripts/video_analysis.py prepare "VIDEO_PATH"
```

全フレームを160×96へ縮小して、画素差・局所RGB・色分布・明暗構造・鮮明さを計算する。数値的な区間と区間内の持続した変化から候補を作り、代表画像だけを元映像から抽出する。暗いカードや平坦な区間も存在情報を残す。数値上の区間は意味上のショットではない。

既定は初回最大32枚、追加予算12枚。`--max-initial`、`--extra-budget` で用途に合わせて指定できる。初回上限で区間が省かれた場合は `initial_cap_omitted_segments` と各segmentの `initial_frame_index: null` で分かる。上限や数値閾値は品質保証ではない。

JSONの `frames` にある画像を `view_image` など実際の画像閲覧ツールで確認する。パスを列挙しただけ、CLIが成功しただけで分析済みにしない。原寸で見づらければ要所を拡大し、画像生成で証拠を補完しない。

まず時刻・被写体・構図・見える状態と、確認したい疑いを整理する。全テキストの転記は目的にしない。画像の意味を読む際の観点と追加要求の選び方は [視覚分析](references/visual-analysis.md) を使う。

## 2. 不明箇所を追加する

数値区間内の別候補を最大3枚取得する例。

```bash
python3 <skill>/scripts/video_analysis.py request "<session>" \
  --segment 3 --mode novelty --count 3 --reason "接触箇所が別の状態でも保たれているか"
```

`novelty` は同じ区間の既配信画像から異なる候補、`late` はまず区間後半の候補を返す。`late` は動作の結果や必要な文字の完成状態を確認したいときに使える。返却後は実画像を読み、疑いが解消したか、別の状態が見えただけかを分ける。

動作を調べるときは、離れた候補だけで済ませず次のsequenceを使う。

```bash
python3 <skill>/scripts/video_analysis.py sequence "<session>" \
  --start 12.0 --end 12.5 --count 12 --reason "手と物体の接触の前後"
```

秒数は動画の最初のフレームからの相対時刻。指定区間の元フレームが予算を超える場合は、両端を含む時間順の間引き画像を返す。`all_source_frames_included: false` を全フレーム確認と読み替えない。前後関係のため既配信画像を再度含む場合も、その枚数は追加予算を消費する。十分な時間分解能がない場合はその判断を保留する。

## 3. 質問されなかった変化を少数補う

```bash
python3 <skill>/scripts/video_analysis.py supplement "<session>" \
  --count 4 --reason "未確認の大きな視覚変化を補完"
```

未代表の区間、次いで同じ区間の既配信画像から数値差が残る候補を選ぶ。選んだ画像を比較対象へ加え、近い候補を繰り返さないようにする。数値差が既定の下限0.08未満なら打ち切る。`--threshold` は変更できるが、既知の正解画像を拾うためだけに調整しない。動作の疑いの解消に必要な予算を先に取り、補完だけで枠を使い切らない。

request・supplement・sequenceは同じ追加予算を共有する。並行呼出しでもロックで予算と履歴を保ち、上限を超える要求は残り枚数へ縮め、残り0なら失敗する。数値差が大きくても意味が重複する場合は追加を続けない。

## 読取と結果の受渡し

- 返却値の `seconds`、`source_pts`、`frame_index` と実画像を対応させる。VFRでもFFprobeのPTSを使い、単純な番号/fpsへ置き換えない。
- `state.json` に記録するのは**配信した画像**。モデルが見た証明ではない。未確認の配信画像があれば、追加を繰り返す前に確認する。
- 既存の解析セッションと読取結果を再利用する。元動画が変わった場合はhash照合で追加を拒否するため、新規セッションを作る。
- 主担当が画像を確認してよい。Lunaなどへの分担が承認・指定されている場合は、その観測結果を使えるが、自動で別モデルや課金APIを起動しない。
- 結果は会話内で、観察事実、根拠時刻、解消した疑問、未確認事項を渡す。保存を求められた場合だけ成果物へまとめる。

数値解析や時刻順の静止画像は、実際の連続視聴、音声解析、滑らかさの確認を代替しない。必要な能力が使えない場合は、その観点を未確認として返す。