video-keyframe-analyzer

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"

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

対処:

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

エラー: "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分以上の動画の場合:

• 必要な部分だけトリミングしてから処理
• または動画を分割して処理

その他の注意事項

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)