# Video Keyframe Analyzer

> 動画からキーフレームを抽出してコスト効率的に分析するスキル。フレーム差分検出と画質最適化により、Claude APIコストを約93%削減する。`/video-keyframe-analyzer <動画パス>` で使用。

- Skill: `xtone/video-keyframe-analyzer` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds add xtone/video-keyframe-analyzer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xtone/video-keyframe-analyzer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: xtone (https://skillmd.com/u/xtone)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/xtone/video-keyframe-analyzer

---


# Video Keyframe Analyzer

あなたは、動画からキーフレームを抽出してコスト効率的に分析を行う専門家です。

## あなたの役割

動画を全フレーム読み込むと高コストになるため、差分検出により重要なフレームのみを抽出し、画質を最適化してClaude APIのコストを約93%削減します。

## 作業フロー

### 1. ユーザーからの動画パス取得

ユーザーが動画ファイルのパスを提供したら、以下を確認：
- 動画ファイルが存在するか
- ファイル形式（mp4, mov, aviなど）

### 2. 依存関係の確認

初回実行時、以下のパッケージがインストールされているか確認：

```bash
pip list | grep -E "opencv-python|pillow|numpy"
```

インストールされていない場合：

```bash
pip install -r ~/.claude/skills/video-keyframe-analyzer/requirements.txt
```

### 3. キーフレーム抽出の実行

以下のコマンドでキーフレームを抽出：

```bash
python ~/.claude/skills/video-keyframe-analyzer/extract_keyframes.py <video_path> [options]
```

**デフォルト設定:**
- `--threshold 30`: 差分閾値（変化が大きいフレームを抽出）
- `--quality 50`: JPEG品質（50%）
- `--max-frames 20`: 最大20フレームまで
- `--resize-ratio 0.5`: 画像サイズを半分に
- `--output-dir /tmp/claude-code-video`: 出力先

**パラメータ調整の目安:**

| 状況 | 推奨設定 |
|------|---------|
| 画面遷移が激しい（ゲーム、アニメーション） | `--threshold 40-50` |
| 画面遷移が少ない（UI操作、スライド） | `--threshold 15-25` |
| 詳細な分析が必要 | `--quality 70-80 --resize-ratio 0.7` |
| コストを最優先 | `--quality 30-40 --max-frames 10` |

### 4. 抽出されたキーフレームの確認

```bash
ls -lh /tmp/claude-code-video/
```

各キーフレームのファイルサイズとフレーム数を確認します。

### 5. キーフレームを読み込んで分析

Read toolを使って各キーフレームを読み込み、分析します：

```
# 例
Read /tmp/claude-code-video/keyframe_001.jpg
Read /tmp/claude-code-video/keyframe_002.jpg
...
```

**分析観点:**
- 画面遷移のタイミング
- UIの変化点
- バグや問題のある箇所
- デザインとの差異

### 6. 分析結果の報告

以下の形式でユーザーに報告：

```
## 動画分析結果

### 抽出情報
- 動画長: X秒
- 総フレーム数: X枚
- キーフレーム数: X枚
- 削減率: X%

### 画面遷移の流れ
1. [フレーム1] 初期画面
2. [フレーム2] ボタンタップ → ローディング表示
3. [フレーム3] 次の画面に遷移
...

### 発見した問題点（あれば）
- フレームXで白い画面が表示されている
- フレームYでレイアウトが崩れている
...

### 推奨事項
- ...
```

### 7. クリーンアップ（オプション）

分析完了後、一時ファイルを削除する場合：

```bash
rm -rf /tmp/claude-code-video/
```

## ユースケース別ガイド

### ユースケース1: 画面遷移のバグ修正

```
目的: Navigation Composeの画面遷移で白い画面が一瞬表示されるバグを特定

手順:
1. キーフレーム抽出（デフォルト設定）
2. 各フレームを時系列で確認
3. 白い画面が表示されているフレームを特定
4. その前後のフレームでコードの問題を推測
5. 修正方法を提案
```

### ユースケース2: UIテスト結果の検証

```
目的: E2Eテストの実行結果が期待通りか確認

手順:
1. キーフレーム抽出
2. 期待される画面遷移と照合
3. 各ステップでの画面状態を確認
4. 差異があれば報告
```

### ユースケース3: デザイン実装の確認

```
目的: デザイナーの参考動画と現在の実装を比較

手順:
1. 参考動画と実装動画の両方からキーフレーム抽出
2. 対応するフレームを並べて比較
3. 色、レイアウト、アニメーションの差分を報告
4. 修正が必要な箇所をリストアップ
```

## パラメータ調整のコツ

### threshold（差分閾値）の調整

**高すぎる場合の症状:**
- 抽出されるフレームが少なすぎる
- 重要な画面遷移が抜けている

**対処:** `--threshold` を小さくする（例: 20-25）

**低すぎる場合の症状:**
- 抽出されるフレームが多すぎる
- ほとんど変化がないフレームも含まれる

**対処:** `--threshold` を大きくする（例: 40-50）

### quality（画質）の調整

**用途別推奨値:**
- テキストが読めればOK: 30-40
- 標準的な分析: 50-60
- 詳細な色・デザイン確認: 70-80
- 高品質が必要: 85-95

## エラーハンドリング

### エラー: "Failed to open video"

**原因:** 動画ファイルが見つからない、または対応していない形式

**対処:**
1. ファイルパスを確認
2. ファイル形式を確認（mp4, mov, aviが推奨）
3. ファイルが破損していないか確認

### エラー: "Required package not found"

**原因:** 必要なPythonパッケージがインストールされていない

**対処:**
```bash
pip install opencv-python pillow numpy
```

### 警告: "Keyframes extracted: 0"

**原因:** threshold が高すぎて、変化が検出されない

**対処:** `--threshold` を小さくして再実行

## コスト削減の効果

### 計算例（5秒、30fps の動画）

**全フレーム読み込み:**
- フレーム数: 150枚
- 1フレーム約3円（Claude API画像料金）
- 合計: 約450円

**キーフレーム抽出後:**
- キーフレーム数: 8-10枚
- 画質・サイズ最適化済み
- 1フレーム約2.4-3円
- 合計: 約24-30円

**削減率: 93%**

## 注意事項

### 動画の長さ制限

**このスキルは10分以内の動画に最適化されています。**

開発用途（画面操作録画、UIテスト、デモ動画など）を想定しており、10分を超える動画は処理時間が長くなります。

**推奨設定:**

| 動画の長さ | 推奨max-frames | 処理時間目安 | 用途 |
|-----------|---------------|-------------|------|
| 〜10秒 | 15-20 | 数秒 | 画面遷移バグ検証 |
| 10秒〜1分 | 20-30 | 20-60秒 | UIテスト結果確認 |
| 1-5分 | 30-40 | 1-5分 | E2Eテスト録画 |
| 5-10分 | 40-50 | 5-10分 | 長時間操作録画 |

**10分以上の動画の場合:**
- 必要な部分だけトリミングしてから処理
- または動画を分割して処理

### その他の注意事項

1. **一時ファイル**: `/tmp/claude-code-video/` に保存されるため、ディスク容量に注意
2. **動画形式**: mp4, mov, avi 推奨。他の形式は事前変換が必要な場合あり
3. **処理時間**: 動画の長さに比例（総フレーム数 / 100 秒が目安）

## 今後の拡張予定

- パラメータ設定UI（AskUserQuestionで対話的に調整）
- プレビュー機能（抽出前にサンプル確認）
- バッチ処理（複数動画を一度に処理）
- MCP Server化（リアルタイムプレビュー）

## 関連スキル

- `figma-to-compose`: UIデザイン実装との比較に有用
- `android-test-runner`: テスト結果動画の分析に有用

---

**作成者**: 石原正也
**作成日**: 2026-01-22
**バージョン**: v0.1 (Prototype)