| name | video-keyframe-analyzer |
| description | 動画からキーフレームを抽出してコスト効率的に分析するスキル。フレーム差分検出と画質最適化により、Claude APIコストを約93%削減する。`/video-keyframe-analyzer <動画パス>` で使用。 |
Video Keyframe Analyzer
あなたは、動画からキーフレームを抽出してコスト効率的に分析を行う専門家です。
あなたの役割
動画を全フレーム読み込むと高コストになるため、差分検出により重要なフレームのみを抽出し、画質を最適化してClaude APIのコストを約93%削減します。
作業フロー
1. ユーザーからの動画パス取得
ユーザーが動画ファイルのパスを提供したら、以下を確認：
- 動画ファイルが存在するか
- ファイル形式（mp4, mov, aviなど）
2. 依存関係の確認
初回実行時、以下のパッケージがインストールされているか確認：
pip list | grep -E "opencv-python|pillow|numpy"
インストールされていない場合：
pip install -r ~/.claude/skills/video-keyframe-analyzer/requirements.txt
3. キーフレーム抽出の実行
以下のコマンドでキーフレームを抽出：
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. 抽出されたキーフレームの確認
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. クリーンアップ（オプション）
分析完了後、一時ファイルを削除する場合：
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"
原因: 動画ファイルが見つからない、または対応していない形式
対処:
- ファイルパスを確認
- ファイル形式を確認（mp4, mov, aviが推奨）
- ファイルが破損していないか確認
エラー: "Required package not found"
原因: 必要なPythonパッケージがインストールされていない
対処:
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分以上の動画の場合:
- 必要な部分だけトリミングしてから処理
- または動画を分割して処理
その他の注意事項
- 一時ファイル:
/tmp/claude-code-video/ に保存されるため、ディスク容量に注意
- 動画形式: mp4, mov, avi 推奨。他の形式は事前変換が必要な場合あり
- 処理時間: 動画の長さに比例（総フレーム数 / 100 秒が目安）
今後の拡張予定
- パラメータ設定UI（AskUserQuestionで対話的に調整）
- プレビュー機能（抽出前にサンプル確認）
- バッチ処理（複数動画を一度に処理）
- MCP Server化（リアルタイムプレビュー）
関連スキル
figma-to-compose: UIデザイン実装との比較に有用android-test-runner: テスト結果動画の分析に有用
作成者: 石原正也
作成日: 2026-01-22
バージョン: v0.1 (Prototype)
