video-frames

動画フレーム

ffmpeg を使用して動画ファイルからフレームを抽出し、LLM の画像分析に最適化された JPEG 画像を生成します。複数のフレーム選択方式（固定 FPS、シーン検出、目標フレーム数）、品質プリセット、モデルに応じたサイズ最適化、OCR 機能強化に対応しています。

前提条件

ffmpeg と ffprobe がインストールされ、PATH に設定されている必要があります。

brew install ffmpeg  # macOS

ワークフロー

1. ユーザーから動画ファイルのパスを受け取ります
2. scripts/extract_frames.py を実行して JPEG フレームを抽出します
3. JSON 出力を解析し、フレームのパス、解像度、トークンの推定値を取得します
4. 抽出したフレームを画像添付ファイルとして読み込み、分析します
5. 動画の内容についてのユーザーの質問に回答します
6. 完了したら一時ディレクトリをクリーンアップします

クイックスタート

最も簡単な実行方法では、標準品質で 1 秒あたり 1 フレームを抽出します。

python3 scripts/extract_frames.py video.mp4

ほとんどの用途では、--max-frames を使ってスクリプトに FPS を自動計算させます。

python3 scripts/extract_frames.py video.mp4 --max-frames 30

動画の長さに応じて調整され、フレーム数を予測しやすく保てるため、--fps を手動で設定するよりも推奨される方法です。

プリセット

4 つの品質プリセットで、解像度、JPEG 品質、画像処理を制御します。

プリセット	最大寸法	品質	追加処理	最適な用途
efficient	768px	5	--	大量のフレーム、長い動画
balanced	1024px	3	--	一般的な分析（デフォルト）
detailed	1568px	2	--	細部、小さなオブジェクト
ocr	1568px	1	グレースケール＋高コントラスト＋シャープ化	テキスト／文書の抽出

# Long video, keep costs low
python3 scripts/extract_frames.py long_video.mp4 --max-frames 20 --preset efficient

# Need to read text in a screencast
python3 scripts/extract_frames.py screencast.mp4 --max-frames 40 --preset ocr

品質（1＝最高、31＝最低）と最大寸法は、それぞれ個別に上書きできます。

python3 scripts/extract_frames.py video.mp4 --preset balanced --quality 1 --max-dimension 1568

シーン変化の検出

固定レートで抽出する代わりに、視覚的なシーンの変化を検出し、シーンごとに 1 フレームを抽出します。明確なセグメントに分かれた動画（プレゼンテーション、編集済み映像、チュートリアル）に最適です。

python3 scripts/extract_frames.py video.mp4 --scene-threshold 0.3

• --scene-threshold（float、0.0～1.0）：感度です。値を小さくするほど感度が高くなり、より小さな変化を検出します。まずは 0.3（このフラグを使用した場合のデフォルト値）から始めてください。
• --min-scene-interval（float、デフォルト：1.0）：検出されたシーン間の最小秒数です。急速なカット中に検出が集中するのを防ぎます。

注： --fps と --scene-threshold は同時に指定できません。--max-frames は --fps モードでのみ使用でき、シーン検出では使用できません。

# Presentation with clear slide transitions
python3 scripts/extract_frames.py presentation.mp4 --scene-threshold 0.2

# Action footage -- less sensitive, min 2s apart
python3 scripts/extract_frames.py action.mp4 --scene-threshold 0.5 --min-scene-interval 2.0

モデルに応じた最適化

--target-model を使用すると、フレームを特定のモデルのタイル境界に合う寸法にリサイズし、無駄なトークンを最小限に抑えられます。

モデル	最大寸法	理由
claude	1568px	自動リサイズ前の最大ネイティブ解像度
openai	768px	512px のタイルグリッドに合わせる（短辺 768）
gemini	768px	768px のタイル境界に合わせる
universal	768px	すべてのモデルに適した最適値（デフォルト）

# Optimized for Claude -- maximum detail
python3 scripts/extract_frames.py video.mp4 --max-frames 30 --target-model claude

# Optimized for GPT-4o -- efficient tile packing
python3 scripts/extract_frames.py video.mp4 --max-frames 30 --target-model openai

--target-model は最大寸法を設定します。ただし、--max-dimension が明示的に指定されている場合は、CLI の指定が優先されます。

各モデルの詳細なトークン計算式、タイル計算、最適な寸法の表については、references/llm-image-specs.md を参照してください。

OCR とグレースケールモード

テキストを含む動画（画面録画、プレゼンテーション、文書、ターミナルの録画）向けです。

# Full OCR pipeline via preset
python3 scripts/extract_frames.py screencast.mp4 --preset ocr --max-frames 40

# Manual OCR flags (can combine with any preset)
python3 scripts/extract_frames.py video.mp4 --grayscale --high-contrast

• --grayscale：フレームをグレースケールに変換します。OCR の精度を損なわず、ファイルサイズを約 60% 削減します。
• --high-contrast：テキストと背景の分離を改善するため、contrast=1.3, brightness=0.05 を適用します。
• ocr プリセットでは、両方のフラグに加えて、1568px、品質 1（最高の JPEG 品質）でアンシャープマスクによるシャープ化を有効にします。

高度なオプション

FPS 選択ガイド

--max-frames の代わりに --fps を直接使用する場合：

動画の長さ	推奨 FPS	理由
< 30s	2-5	短いクリップなので、詳細を捉えます
30s - 5min	1	カバー範囲とフレーム数のバランスが良好です
5min - 30min	0.5	フレーム数が過剰になるのを防ぎます
> 30min	0.1 - 0.2	重要な場面のみをサンプリングします

LLM のコンテキストを最適に使用するには、フレーム数の合計を約 50 未満にしてください。計算式：duration_seconds * fps = frame_count。

手動で FPS を指定するよりも --max-frames を優先してください。適切なレートを自動計算し、0.05～30.0 FPS の範囲に調整します。

タイムスタンプのオーバーレイ

python3 scripts/extract_frames.py video.mp4 --timestamps --max-frames 30

各フレームの右下隅に、元のファイル名と hh:mm:ss 形式のタイムスタンプを重ねて表示します（半透明の黒いボックス上に白いテキストで表示）。動画内の特定の場面をユーザーが参照する必要がある場合に使用してください。

CLI オプション一覧

オプション	型	デフォルト	説明
video_path	位置指定	（必須）	動画ファイルへのパス
--fps	float	1.0	1 秒あたりのフレーム数（--scene-threshold とは相互に排他的）
--scene-threshold	float	--	シーン変更の感度 0.0～1.0（--fps とは相互に排他的）
--min-scene-interval	float	1.0	シーン変更フレーム間の最小秒数
--max-frames	int	--	約 N フレームを生成する FPS を自動計算
--preset	choice	balanced	efficient / balanced / detailed / ocr
--max-dimension	int	--	最大ピクセル寸法（最長辺）を上書き
--quality	int	--	JPEG 品質 1～31（1＝最高、31＝最低）
--target-model	choice	--	claude / openai / gemini / universal
--grayscale	flag	off	グレースケールに変換
--high-contrast	flag	off	テキストの読みやすさを高めるためにコントラストを強調
--timestamps	flag	off	フレームにファイル名とタイムスタンプを重ねて表示
--output-dir	string	temp dir	抽出したフレームの出力ディレクトリ

出力 JSON の構造

スクリプトは、次の構造の JSON を標準出力に出力します。

{
  "output_dir": "/tmp/video_frames_abc123/",
  "frames": ["/tmp/video_frames_abc123/frame_00001.jpg", "..."],
  "preset": "balanced",
  "resolution": { "width": 1024, "height": 576 },
  "token_estimate": {
    "frame_count": 30,
    "per_frame": {
      "claude": 787,
      "openai_high": 765,
      "openai_low": 85,
      "openai_patch": 934,
      "gemini": 258
    },
    "total": {
      "claude": 23610,
      "openai_high": 22950,
      "openai_low": 2550,
      "openai_patch": 28020,
      "gemini": 7740
    }
  },
  "summary": {
    "video_duration_seconds": 120.5,
    "extraction_method": "max_frames",
    "scene_changes_detected": null,
    "frames_extracted": 30,
    "estimated_total_tokens": {
      "claude": 23610,
      "openai_high": 22950,
      "openai_low": 2550,
      "openai_patch": 28020,
      "gemini": 7740
    }
  }
}

フレームをプロンプトに添付する前に、token_estimate.total を使用して、フレームセットがモデルのコンテキスト上限に収まることを確認してください。

注： openai_high と openai_low は旧モデル（GPT-4o、GPT-4.1）向けです。openai_patch は新しいモデル（gpt-5.4+、gpt-5-mini、o4-mini）向けです。詳細は references/llm-image-specs.md を参照してください。

エラーが発生した場合は、"error" キーを含む JSON が標準エラー出力に出力され、スクリプトは終了コード 1 で終了します。

抽出後の手順

1. JSON 出力を解析し、frames からフレームパスの一覧を取得します
2. token_estimate.total を確認し、フレームがコンテキスト上限に収まることを確かめます
3. Read ツールを使用して各フレーム画像を読み込みます（JPEG ファイルです）
4. フレームを分析して、ユーザーの質問に回答します
5. 後片付け：一時ディレクトリの場合は、完了後に出力ディレクトリを削除します