video-understand

動画理解

自動フォールバックとモデル選択に対応した、複数プロバイダーによる動画理解です。

クイックスタート

# Check available providers
python3 scripts/check_providers.py

# Process a video (auto-selects best provider)
python3 scripts/process_video.py "https://youtube.com/watch?v=..."
python3 scripts/process_video.py /path/to/video.mp4

# Custom prompt
python3 scripts/process_video.py video.mp4 -p "List all products shown with timestamps"

# Use specific provider/model
python3 scripts/process_video.py video.mp4 --provider openrouter -m google/gemini-3-pro-preview

# List available models
python3 scripts/process_video.py --list-models

プロバイダーの優先順位

利用可能なプロバイダーから最適なものを自動的に選択します。

優先度	プロバイダー	機能	環境変数	デフォルトモデル
1	Gemini	動画全体	GEMINI_API_KEY	gemini-3-flash-preview
2	Vertex AI	動画全体	GOOGLE_APPLICATION_CREDENTIALS	gemini-3-flash-preview
3	OpenRouter	動画全体	OPENROUTER_API_KEY	google/gemini-3-flash-preview
4	FFMPEG	フレーム＋ASR	なし（ffmpeg + whisper が必要）	scene
5	OpenAI	ASR のみ	OPENAI_API_KEY	whisper-1
6	AssemblyAI	ASR＋分析	ASSEMBLYAI_API_KEY	best
7	Deepgram	ASR	DEEPGRAM_API_KEY	nova-2
8	Groq	ASR（高速）	GROQ_API_KEY	whisper-large-v3-turbo
9	Local Whisper	ASR（オフライン）	なし	base

動画全体＝映像＋音声の分析です。フレーム＋ASR＝抽出したスクリーンショット＋音声の文字起こし（無料、オフライン）です。ASR＝音声の文字起こしのみです。

CLI オプション

python3 scripts/process_video.py [OPTIONS] SOURCE

Arguments:
  SOURCE              YouTube URL, video URL, or local file path

Options:
  -p, --prompt TEXT   Custom prompt for video understanding
  --provider NAME     Force specific provider
  -m, --model NAME    Force specific model
  --asr-only          Force ASR-only mode (skip visual analysis)
  -o, --output FILE   Write JSON to file instead of stdout
  -q, --quiet         Suppress progress messages
  --list-models       Show available models per provider
  --list-providers    Show available providers as JSON

モデル選択

各プロバイダーは複数のモデルに対応しています。選択肢を確認するには、--list-models を使用します。

python3 scripts/process_video.py --list-models

OpenRouter のモデル：

• google/gemini-3-flash-preview（デフォルト）- 高速、無料枠あり
• google/gemini-3-pro-preview - より高品質

Gemini のモデル：

• gemini-3-flash-preview（デフォルト）- 最新、高速
• gemini-3-pro-preview - 最高品質
• gemini-2.5-flash - 安定した本番環境向けフォールバック

Local Whisper のモデル：

• tiny、base（デフォルト）、small、medium、large、large-v3

FFMPEG モード（フレーム抽出方式）：

• scene（デフォルト）- シーンの切り替わり時にフレームを抽出します（スマートで効率的）
• keyframe - I フレームのみを抽出します（最速）
• interval - 一定間隔でフレームを抽出します（予測しやすい）

クイックリファレンス

タスク	リファレンス
セットアップと API キー	setup-guide.md
Gemini で動画を使用	gemini.md
OpenRouter を使用	openrouter.md
FFMPEG フレーム（無料）	ffmpeg-frames.md
ASR プロバイダー	asr-providers.md
出力 JSON スキーマ	output-format.md
動画ソースとダウンロード	video-sources.md

セットアップの確認

python3 scripts/setup.py  # Check dependencies and API keys

出力形式

すべてのプロバイダーは一貫した JSON を返します。

{
  "source": {
    "type": "youtube|url|local",
    "path": "...",
    "duration_seconds": 120.5,
    "size_mb": 15.2
  },
  "provider": "openrouter",
  "model": "google/gemini-3-flash-preview",
  "capability": "full_video",
  "response": "...",
  "transcript": [{"start": 0.0, "end": 2.5, "text": "..."}],
  "text": "Full transcript..."
}

機能

• 利用可能な API キーに基づくプロバイダーの自動選択
• 適切なデフォルト値を備えた、プロバイダーごとのモデル選択
• macOS の特殊文字や Unicode に対応した堅牢なパス処理
• 進行状況の出力（静音モードでは -q を使用）
• API の制限に対するファイルサイズの警告
• 必要に応じた動画形式の自動変換
• YouTube URL に対応（直接指定またはダウンロード経由）

要件

動画全体の理解に必要なもの：

pip install google-generativeai  # Gemini
pip install openai               # OpenRouter

ASR フォールバックに必要なもの：

brew install yt-dlp ffmpeg       # Video tools
pip install openai               # OpenAI Whisper
pip install groq                 # Groq Whisper
pip install assemblyai           # AssemblyAI
pip install deepgram-sdk         # Deepgram
pip install openai-whisper       # Local Whisper