Imported from xtone/ai_development_tools (common_development/skills/video-keyframe-analyzer/SKILL.md). Install upstream with npx skills add xtone/ai_development_tools --skill video-keyframe-analyzer. Copyright stays with the author.

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化（リアルタイムプレビュー）

video-keyframe-analyzer

About