video-understand

video-understand

ffmpeg によるフレーム抽出と Whisper による文字起こしを使用して、動画の内容をローカルで解析します。完全にオフラインで動作し、API キーは不要です。

前提条件

• ffmpeg + ffprobe（必須）：brew install ffmpeg
• openai-whisper（文字起こしに使用、任意）：pip install openai-whisper

コマンド

# Scene detection + transcribe (default)
python3 skills/video-understand/scripts/understand_video.py video.mp4

# Keyframe extraction
python3 skills/video-understand/scripts/understand_video.py video.mp4 -m keyframe

# Regular interval extraction
python3 skills/video-understand/scripts/understand_video.py video.mp4 -m interval

# Limit frames extracted
python3 skills/video-understand/scripts/understand_video.py video.mp4 --max-frames 10

# Use a larger Whisper model
python3 skills/video-understand/scripts/understand_video.py video.mp4 --whisper-model small

# Frames only, skip transcription
python3 skills/video-understand/scripts/understand_video.py video.mp4 --no-transcribe

# Quiet mode (JSON only, no progress)
python3 skills/video-understand/scripts/understand_video.py video.mp4 -q

# Output to file
python3 skills/video-understand/scripts/understand_video.py video.mp4 -o result.json

CLI オプション

フラグ	説明
video	入力動画ファイル（位置引数、必須）
-m, --mode	抽出モード：scene（デフォルト）、keyframe、interval
--max-frames	保持するフレームの最大数（デフォルト：20）
--whisper-model	Whisper モデルのサイズ：tiny、base、small、medium、large（デフォルト：base）
--no-transcribe	音声の文字起こしをスキップし、フレームのみを抽出します
-o, --output	標準出力の代わりに、結果を JSON ファイルに書き込みます
-q, --quiet	進行状況メッセージを抑制し、JSON のみを出力します

抽出モード

モード	仕組み	最適な用途
scene	ffmpeg の select='gt(scene,0.3)' を使ってシーンの切り替わりを検出します	さまざまな内容を含むほとんどの動画
keyframe	I フレーム（コーデックのキーフレーム）を抽出します	自然なキーフレーム配置でエンコードされた動画
interval	動画の長さと max-frames に基づいて、フレームを等間隔で抽出します	固定間隔でのサンプリング、予測可能な出力

scene モードでシーンの切り替わりが検出されない場合、自動的に interval モードに切り替わります。

出力

スクリプトは JSON を標準出力に出力します（-o を指定した場合はファイルに出力します）。完全なスキーマについては references/output-format.md を参照してください。

{
  "video": "video.mp4",
  "duration": 18.076,
  "resolution": {"width": 1224, "height": 1080},
  "mode": "scene",
  "frames": [
    {"path": "/abs/path/frame_0001.jpg", "timestamp": 0.0, "timestamp_formatted": "00:00"}
  ],
  "frame_count": 12,
  "transcript": [
    {"start": 0.0, "end": 2.5, "text": "Hello and welcome..."}
  ],
  "text": "Full transcript...",
  "note": "Use the Read tool to view frame images for visual understanding."
}

フレーム画像のパスに対して Read ツールを使用し、抽出されたフレームを目視で確認してください。

リファレンス

• references/output-format.md -- JSON 出力スキーマの完全なドキュメント