ffmpeg-analyse-video

FFmpeg 動画分析

ffmpeg を使用して動画ファイルからフレームを抽出します。メインのコンテキストウィンドウを保持するため、フレームの読み取りはサブエージェントに委任します。テキストのみのサブエージェントのレポートから、タイムスタンプ付きの構造化された要約を作成します。

アーキテクチャ：コンテキスト効率に優れたサブエージェントのパイプライン

問題：メインの会話コンテキストに数十枚の画像を読み込むと、コンテキストウィンドウの大半が消費され、要約や追加の質問に使える余地がほとんどなくなります。

解決策：3 フェーズのパイプラインです。

Main Agent                          Sub-Agents (disposable context)
──────────                          ──────────────────────────────
1. ffprobe metadata        ───►
2. ffmpeg frame extraction ───►
3. Split frames into batches ──►   4. Read images (vision)
                                      Write text descriptions
                                      to batch_N_analysis.md
5. Read text files only    ◄───    (context discarded)
6. Synthesise final output

画像が存在するのは、サブエージェントのコンテキスト内だけです。メインエージェントが読み取るのは、軽量なテキストファイルだけです。これにより、コンテキストの使用量を約 90% 削減できます。

1. 前提条件

which ffmpeg && which ffprobe

どちらかが不足している場合は、プラットフォームに応じたインストール手順を表示して、停止します。

• macOS：brew install ffmpeg
• Ubuntu/Debian：sudo apt install ffmpeg
• Windows：choco install ffmpeg または winget install ffmpeg

2. 一時ディレクトリのセットアップ

# macOS/Linux
TMPDIR="/tmp/video-analysis-$(date +%s)"
mkdir -p "$TMPDIR"

# Windows (PowerShell)
# $TMPDIR = "$env:TEMP\video-analysis-$(Get-Date -UFormat %s)"
# New-Item -ItemType Directory -Path $TMPDIR

3. 動画メタデータの抽出

ffprobe -v quiet -print_format json -show_format -show_streams "VIDEO_PATH"

抽出して報告する内容：長さ、解像度（幅 x 高さ）、fps、コーデック、ファイルサイズ、音声の有無。

動画ストリームが見つからない場合は「音声のみのファイル」と報告して停止します。 ファイルサイズが 2GB を超える場合は、ユーザーに警告し、-ss START -to END を使って時間範囲を指定した分析を提案します。

4. フレームの抽出

長さに応じて方法を選択します。

長さ	方法	コマンド
0-60s	2 秒ごとに 1 フレーム	ffmpeg -hide_banner -y -i INPUT -vf "fps=1/2,scale='min(1280,iw)':-2" -q:v 5 DIR/frame_%04d.jpg
1-10min	シーン検出（しきい値 0.3）	ffmpeg -hide_banner -y -i INPUT -vf "select='gt(scene,0.3)',scale='min(1280,iw)':-2" -vsync vfr -q:v 5 DIR/scene_%04d.jpg
10-30min	キーフレームの抽出	ffmpeg -hide_banner -y -skip_frame nokey -i INPUT -vf "scale='min(1280,iw)':-2" -vsync vfr -q:v 5 DIR/key_%04d.jpg
30min+	サムネイルフィルター	ffmpeg -hide_banner -y -i INPUT -vf "thumbnail=SEGMENT_FRAMES,scale='min(1280,iw)':-2" -vsync vfr -q:v 5 DIR/thumb_%04d.jpg

サムネイルフィルターでは、出力を約 60 フレームに抑えるため、SEGMENT_FRAMES = total_frames / 60 として計算します。

フォールバック：

• シーン検出で 0 フレームが生成された場合 → 5 秒ごとに 1 フレームを抽出する方法で再試行します
• 100 フレームを超えて抽出された場合 → 均等に間引いて 80 フレームにします
• フレームの抽出に失敗した場合 → 次に単純な方法を試します（シーン検出 → 間隔指定、キーフレーム → 間隔指定）

時間範囲の分析： ユーザーが範囲を指定した場合は、-i の前に -ss START -to END を追加します。 高詳細モード： 要求された場合は、fps レートを 2 倍にし、シーンのしきい値を 0.2 に下げます。

抽出後、すべてのフレームファイルを一覧表示し、連番と抽出レートから各フレームのタイムスタンプを計算します。

5. フレーム分析をサブエージェントに委任する

ここがコンテキストを節約するための重要な手順です。 メインの会話でフレーム画像を読み込まないでください。代わりに、フレームをバッチに分割し、各バッチの処理をサブエージェントに委任します。

5a. バッチマニフェストの準備

抽出したフレームファイルの一覧を、各 8～10 フレームのバッチに分割します。各バッチについて、以下を記録します。

• バッチ番号（1、2、3、...）
• フレームファイルのパス（絶対パス）
• フレームのタイムスタンプ（連番から計算）
• 出力ファイルのパス：TMPDIR/batch_N_analysis.md

5b. サブエージェントの起動

以下のプロンプトを使って、各バッチにサブエージェントを起動します。ツールが対応している場合は、すべてのバッチを並行して起動してください。バッチ間に依存関係はありません。

サブエージェントのプロンプトテンプレート

プレースホルダーを置き換えて、このプロンプトをそのまま使用します。

You are analysing frames extracted from a video file.

VIDEO: {filename}
DURATION: {duration}
BATCH: {batch_number} of {total_batches}

Read each frame image listed below using the Read tool (or equivalent file reading tool that supports images). For each frame, write a structured description.

FRAMES:
{for each frame in batch}
- {absolute_path_to_frame} (timestamp: {MM:SS})
{end for}

For each frame, describe:
1. SCENE: What is visible (layout, UI elements, environment)
2. CONTENT: Text, code, labels, menus, or dialogue visible on screen
3. ACTION: What is happening or has changed since the likely previous frame
4. DETAILS: Any notable specifics (error messages, URLs, file names, button states)

After describing all frames, add a BATCH SUMMARY section with:
- Content type (one of: Screencast, Presentation, Tutorial, Footage, Animation)
- Key events in this batch's time range
- Any text/prompts/commands the user typed (quote exactly)

Write the complete analysis to: {TMPDIR}/batch_{N}_analysis.md

Format the output file as:

# Batch {N} Analysis ({start_timestamp} - {end_timestamp})

## Frame-by-Frame

### Frame {sequence} ({timestamp})
- **Scene**: ...
- **Content**: ...
- **Action**: ...
- **Details**: ...

(repeat for each frame)

## Batch Summary
- **Content Type**: ...
- **Key Events**: ...
- **Quoted Text/Prompts**: ...

起動方法

使用しているツールが提供するサブエージェント、バックグラウンドタスク、または独立したエージェントの仕組みを使用してください。必要なことは簡単です。各サブエージェントは次の処理を行います。

1. 画像ファイルを読み取る（フレームの JPEG）
2. テキストファイルを書き込む（バッチ分析の Markdown）

ツールが対応している場合は、すべてのバッチを並行して起動してください。各バッチは独立しており、共有状態はありません。

ツールにサブエージェントの仕組みがない場合は、メインコンテキストでフレームを直接読み取る方法に切り替えます。ただし、最大 20 フレームに制限し、コンテキストの使用量についてユーザーに警告します。

5c. 結果を収集する

すべてのサブエージェントが完了したら、テキスト分析ファイルを読み取ります。これらは軽量な Markdown ファイルであり、画像がメインコンテキストに入ることはありません。

ls TMPDIR/batch_*_analysis.md

各 batch_N_analysis.md ファイルを順番に読み取ります。これらに含まれるのはテキストによる説明のみであり、元の画像を読み取る場合と比べてコンテキストの消費は最小限です。

6. 統合する

バッチ分析ファイルのテキストのみを使用して、メインコンテキストで統合を行います。

1. すべてのフレームの説明を、ひとつの時系列にまとめます
2. フレームを自然なセグメント（同じシーン、スライド、画面など）にグループ化します
3. すべてのバッチを通じて優勢なコンテンツの種類を判定します
4. 重要な場面を3～7個特定します
5. ユーザーが入力した引用テキスト、プロンプト、コマンドをすべて抽出します
6. 2～5文の概要を書きます

出力形式：

# Video Analysis: [filename]

## Metadata
| Property | Value |
|----------|-------|
| Duration | M:SS |
| Resolution | WxH |
| FPS | N |
| Content Type | [detected] |
| Frames Analysed | N |

## Timeline
### [Segment Title] (M:SS - M:SS)
Description of what happens in this segment.

### [Segment Title] (M:SS - M:SS)
Description of what happens in this segment.

## Key Moments
1. **[M:SS] Title**: Description
2. **[M:SS] Title**: Description
3. **[M:SS] Title**: Description

## Summary
[2-5 sentence narrative paragraph summarising the entire video]

7. クリーンアップ

出力が完了したら、一時ディレクトリを削除します。

# macOS/Linux
rm -rf "$TMPDIR"

# Windows (PowerShell)
# Remove-Item -Recurse -Force $TMPDIR

ユーザーがフレームの保持を求めた場合は、クリーンアップをスキップします。

高度なオプション

• 時間範囲：「video.mp4 の 2:00 から 5:00 を分析」→ -ss 120 -to 300 を使用します
• 詳細度を上げる：「高い詳細度で分析」→ フレームレートを2倍にし、シーン閾値を0.2に下げます
• 注目領域：「表示されているコードに注目」→ サブエージェントのプロンプトでテキスト／コードの抽出を優先します
• スプライトシート：視覚的な概要を確認するため、コンタクトシートを生成します：

  ffmpeg -hide_banner -y -i INPUT -vf "select='not(mod(n,EVERY_N))',scale='min(320,iw)':-2,tile=5xROWS" -frames:v 1 DIR/sprite.jpg
  

エラー処理

• ffmpeg が見つからない → プラットフォームごとのインストール手順を案内して、停止します
• 動画ストリームがない → 音声のみであることを報告して、停止します
• シーン検出でフレームが0件になる → 間隔ベースの方式にフォールバックします
• フレームが多すぎる（>100）→ 80件にサブサンプリングします
• ファイルサイズが大きい（>2GB）→ 警告し、時間範囲の指定を提案します
• サブエージェントが失敗またはタイムアウトする → フォールバックとして該当バッチのフレームを直接読み取り、コンテキストの使用量について警告します
• サブエージェントでフレームの読み取りに失敗する → そのフレームをスキップし、バッチ分析ファイルに欠落を記録します