video-understand
ffmpeg を使用したフレーム抽出と Whisper を使用した文字起こしにより、動画コンテンツをローカルで理解します。完全オフライン、APIキー不要。
前提条件
ffmpeg+ffprobe(必須):brew install ffmpegopenai-whisper(任意、文字起こし用):pip install openai-whisper
コマンド
# シーン検出 + 文字起こし (デフォルト)
python3 skills/video-understand/scripts/understand_video.py video.mp4
# キーフレーム抽出
python3 skills/video-understand/scripts/understand_video.py video.mp4 -m keyframe
# 一定間隔抽出
python3 skills/video-understand/scripts/understand_video.py video.mp4 -m interval
# 抽出するフレーム数を制限
python3 skills/video-understand/scripts/understand_video.py video.mp4 --max-frames 10
# より大きな Whisper モデルを使用
python3 skills/video-understand/scripts/understand_video.py video.mp4 --whisper-model small
# フレームのみ、文字起こしスキップ
python3 skills/video-understand/scripts/understand_video.py video.mp4 --no-transcribe
# クワイエットモード (JSONのみ、進行状況非表示)
python3 skills/video-understand/scripts/understand_video.py video.mp4 -q
# ファイルに出力
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 | 動画の長さと最大フレーム数に基づいて等間隔にフレームを抽出 | 固定サンプリング、予測可能な出力 |
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出力スキーマの完全なドキュメント