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をstdoutではなくファイルに書き込む |
-q, --quiet | 進捗メッセージを抑制し、JSONのみを出力 |
抽出モード
| モード | 仕組み | 最適な用途 |
|---|---|---|
scene | ffmpegのselect='gt(scene,0.3)'でシーンチェンジを検出 | ほとんどの動画、さまざまなコンテンツ |
keyframe | Iフレーム(コーデックのキーフレーム)を抽出 | 自然なキーフレーム配置のエンコード済み動画 |
interval | 動画の長さと最大フレーム数に基づいて均等間隔でフレームを抽出 | 一定のサンプリング、予測可能な出力 |
sceneモードでシーンチェンジが検出されない場合、自動的にintervalモードにフォールバックします。
出力
スクリプトはJSONをstdoutに出力します(-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": "こんにちは、ようこそ..."}
],
"text": "全文文字起こし...",
"note": "フレーム画像を視覚的に理解するには、Readツールを使用してください。"
}
Readツールを使用してフレーム画像のパスを読み取ることで、抽出されたフレームを視覚的に検査できます。
参考資料
references/output-format.md-- 完全なJSON出力スキーマのドキュメント