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 | 動画の長さと 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 出力スキーマの完全なドキュメント