analyzing-video

Video Analyzer

適応的なレートでフレームを抽出し、モンタージュグリッドを作成し、シーンの変化を検出して、並列サブエージェントに視覚と音声の分析を割り当てます。

注意事項

• ソーシャルメディアからのダウンロード（Instagram、TikTok）では、MJPEG サムネイルがビデオストリーム 0 として埋め込まれています。スクリプトは実際の H.264/H.265 ストリームを自動検出し、attached_pic ストリームをスキップします。
• macOS の grep には -P（Perl 正規表現）がありません。互換性を保つため、すべてのスクリプトで sed と基本的な grep を使用します。
• FFmpeg は出力ファイル名の . を画像シーケンスのパターンとして扱います。キーフレームの抽出では、-update 1 を使って単一画像を書き込みます。
• 縦向きの動画（高さ > 幅）では、セルを見やすくするため、4x4 ではなく 3x5 のグリッドレイアウトを使用します。
• シーン検出のしきい値は 0.3 です。静的なコンテンツ（プレゼンテーション、ドキュメント）では 0.1 に下げます。動きの速いコンテンツ（ゲーム、スポーツ）では 0.4 に上げます。
• 分析エージェントに処理を割り当てる前に、抽出結果が出力されていることを必ず確認してください。

前提条件

ffmpeg、ffprobe、python3、bc が必要です。文字起こしには whisper CLI が必要です。

brew install ffmpeg && pip install openai-whisper

文字起こしモード

モード	トリガー	動作
auto	デフォルト	Whisper を実行
user-provided	ユーザーが文字起こしファイル／テキストを提供	提供された文字起こしを使用
skip	「視覚のみ」、「音声をスキップ」、「文字起こしなし」	音声処理なし

カスタマイズ

ユーザーのリクエストから、次の上書き設定を検出します。

上書き設定	ユーザーの指定	効果
カスタム FPS	「5fps で」、「毎秒 3 フレーム」、「2 秒ごとに 1 フレーム」	ティア別の fps レートを上書き
時間範囲	「0:10 から 0:30 まで」、「最初の 15 秒」、「最後の 1 分」	指定された区間のみを分析
両方	「0:10〜0:30 を 5fps で分析」	区間にカスタム fps を適用

ユーザーの指定をスクリプトのパラメーターに変換します。

• 「5fps」／「毎秒 5 フレーム」 → fps_override=5
• 「3 秒ごとに 1 フレーム」 → fps_override=0.333
• 「10 秒ごとに 1 フレーム」 → fps_override=0.1
• 「0:10 から 0:30 まで」 → start_time=10 end_time=30
• 「最初の 15 秒」 → start_time=0 end_time=15
• 「最後の 30 秒」 → 計算：start_time=duration-30

上書き設定をスクリプトに渡します。

bash ${CLAUDE_SKILL_DIR}/scripts/video-info.sh "<video_path>" [fps_override] [start_time] [end_time]
bash ${CLAUDE_SKILL_DIR}/scripts/extract-frames.sh "<video_path>" "<work_dir>/frames" <fps> <max> <stream> <grid> [start_time] [end_time]

カスタム fps が設定されている場合、ティアは custom になり、1000 フレームの安全上限が適用されます。

ワークフロー

このチェックリストをコピーして、進捗を記録してください。

- [ ] Step 1: Get video info (tier, stream, orientation)
- [ ] Step 2: Extract frames + grids + scene key frames
- [ ] Step 3: Verify extraction output (frames exist, grids exist)
- [ ] Step 4: Dispatch parallel analysis agents
- [ ] Step 5: Synthesize results into analysis document
- [ ] Step 6: Clean up temp directory

ステップ 1：動画情報を取得

bash ${CLAUDE_SKILL_DIR}/scripts/video-info.sh "$ARGUMENTS"

次の情報を含む JSON が返されます：video_stream_index、tier、fps_rate、max_frames、orientation、grid_layout、has_audio、work_dir、whisper_model。

ティア	長さ	フレームレート	Whisper モデル
短	<1 分	毎秒 2 フレーム	medium
中	1〜3 分	毎秒 1 フレーム	medium
長	3〜10 分	10 秒ごとに 1 フレーム	base
拡張	10 分以上	20 秒ごとに 1 フレーム（最大 60）	base

ステップ 2：フレーム（と音声）を抽出

bash ${CLAUDE_SKILL_DIR}/scripts/extract-frames.sh "$ARGUMENTS" "<work_dir>/frames" <fps_rate> <max_frames> <stream_index> <grid_layout>

文字起こしの場合（auto モードのみ）：

bash ${CLAUDE_SKILL_DIR}/scripts/extract-audio.sh "$ARGUMENTS" "<work_dir>/audio" <whisper_model>

該当する場合は、両方を並列で実行します。

ステップ 3：抽出結果を確認

エージェントに処理を割り当てる前に、出力を確認します。

• <work_dir>/frames/grid_*.jpg が存在すること（グリッドが 1 つ以上）
• <work_dir>/frames/metadata.json でフレーム数とグリッド数を確認
• シーンの変化が検出された場合、<work_dir>/frames/key_frames/ に画像があることを確認
• 抽出に失敗した場合は、エラーを報告して終了

ステップ 4：サブエージェントによる並列分析

並列で処理を割り当てます。

• グリッドエージェント（2〜3 個のグリッドにつき 1 つ）：モンタージュグリッド画像を読み込み、時間範囲ごとに視覚的な内容を説明
• キーフレームエージェント（シーンの変化が検出された場合）：高解像度の key_frames/ 画像を読み込み、シーン変化を詳細に分析
• 音声エージェント（モードが skip の場合はスキップ）：文字起こしと音声メタデータを読み込み

ステップ 5：統合して出力

すべてのエージェントの結果を統合し、元の動画の隣にある <video_name>_analysis.md に出力します。

# Video Analysis: [filename]

## Overview
| Property | Value |
|----------|-------|
| Duration | HH:MM:SS |
| Resolution | WxH |
| Orientation | portrait/landscape |
| Analysis Tier | short/medium/long/extended |
| Frames Analyzed | N |
| Scene Changes | N |
| Transcription | auto/user-provided/skipped |

## Executive Summary
[2-3 paragraph summary]

## Timeline
| Time | Visual | Audio/Speech |
|------|--------|-------------|
| 00:00 | [description] | [what is said/heard] |

## Detailed Scene Analysis
### Scene 1: [Title] (00:00 - 00:15)
**Visual**: [description]
**Audio**: [what is heard]
**Context**: [significance]

## Conclusions
[Overall analysis]

ステップ 6：クリーンアップ

rm -rf "<work_dir>"

スクリプト

スクリプト	目的	引数
scripts/video-info.sh	メタデータ、ストリーム検出、ティア	<video_path>
scripts/extract-frames.sh	フレーム、グリッド、シーン検出、キーフレーム	<video_path> <out_dir> <fps> [max] [stream] [grid]
scripts/extract-audio.sh	音声、無音検出、文字起こし	<video_path> <out_dir> [model]

参考資料

• references/ffmpeg-commands.md — FFmpeg の注意点と、わかりにくいコマンド
• references/transcription-guide.md — Whisper モデルの選択とトラブルシューティング
• references/analysis-strategies.md — サブエージェントのディスパッチパターンと出力テンプレート