video-understanding

使用 Google Gemini 多模式 AI 分析视频。从任何 URL 下载（Loom、YouTube、TikTok、 Vimeo、Twitter/X、Instagram、1000 多个网站）并获取文字记录、描述和答案 问题。当要求观看、分析、总结或转录视频或回答时使用 有关视频内容的问题。触发视频 URL 或涉及视频理解的请求。

# Video Understanding (Gemini)

Analyze videos using Google Gemini's multimodal video understanding. Supports 1000+ video sources via yt-dlp.

## Requirements

- `yt-dlp` — `brew install yt-dlp` / `pip install yt-dlp`
- `ffmpeg` — `brew install ffmpeg` (for merging video+audio streams)
- `GEMINI_API_KEY` environment variable

## Default Output

Returns structured JSON:
- **transcript** — Verbatim transcript with `[MM:SS]` timestamps
- **description** — Visual description (people, setting, UI, text on screen, flow)
- **summary** — 2-3 sentence summary
- **duration_seconds** — Estimated duration
- **speakers** — Identified speakers

## Usage

### Analyze a video (structured JSON output)

```bash
uv run {baseDir}/scripts/analyze_video.py "<video-url>"
```

### Ask a question (adds "answer" field)

```bash
uv run {baseDir}/scripts/analyze_video.py "<video-url>" -q "What product is shown?"
```

### Override prompt entirely

```bash
uv run {baseDir}/scripts/analyze_video.py "<video-url>" -p "Custom prompt" --raw
```

### Download only (no analysis)

```bash
uv run {baseDir}/scripts/analyze_video.py "<video-url>" --download-only -o video.mp4
```

## Options

| Flag | Description | Default |
|------|-------------|---------|
| `-q` / `--question` | Question to answer (added to default fields) | none |
| `-p` / `--prompt` | Override entire prompt (ignores -q) | structured JSON |
| `-m` / `--model` | Gemini model | gemini-2.5-flash |
| `-o` / `--output` | Save output to file | stdout |
| `--keep` | Keep downloaded video file | false |
| `--download-only` | Download only, skip analysis | false |
| `--max-size` | Max file size in MB | 500 |
| `--raw` | Raw text output instead of JSON | false |

## How It Works

1. **YouTube URLs** → Passed directly to Gemini (no download needed)
2. **All other URLs** → Downloaded via yt-dlp → uploaded to Gemini File API → poll until processed
3. Gemini analyzes video with structured prompt → returns JSON
4. Temp files and Gemini uploads cleaned up automatically

## Supported Sources

Any URL supported by [yt-dlp](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md): Loom, YouTube, TikTok, Vimeo, Twitter/X, Instagram, Dailymotion, Twitch, and 1000+ more.

## Tips

- Use `-q` for targeted questions on top of the full analysis
- YouTube is fastest (no download step)
- Large videos (10min+) work fine — Gemini File API supports up to 2GB (free) / 20GB (paid)
- The script auto-installs Python dependencies via `uv`

---

## 中文说明

# Video Understanding (Gemini)

使用 Google Gemini 的多模态视频理解能力分析视频。通过 yt-dlp 支持 1000 多个视频来源。

## 要求

- `yt-dlp` — `brew install yt-dlp` / `pip install yt-dlp`
- `ffmpeg` — `brew install ffmpeg`（用于合并视频+音频流）
- `GEMINI_API_KEY` 环境变量

## 默认输出

返回结构化 JSON：
- **transcript** — 带 `[MM:SS]` 时间戳的逐字文字记录
- **description** — 画面描述（人物、场景、UI、屏幕文字、流程）
- **summary** — 2-3 句的摘要
- **duration_seconds** — 估算的时长
- **speakers** — 识别出的发言人

## 用法

### 分析视频（结构化 JSON 输出）

```bash
uv run {baseDir}/scripts/analyze_video.py "<video-url>"
```

### 提问（增加 "answer" 字段）

```bash
uv run {baseDir}/scripts/analyze_video.py "<video-url>" -q "What product is shown?"
```

### 完全覆盖提示词

```bash
uv run {baseDir}/scripts/analyze_video.py "<video-url>" -p "Custom prompt" --raw
```

### 仅下载（不分析）

```bash
uv run {baseDir}/scripts/analyze_video.py "<video-url>" --download-only -o video.mp4
```

## 选项

| 选项 | 说明 | 默认值 |
|------|-------------|---------|
| `-q` / `--question` | 要回答的问题（追加到默认字段） | 无 |
| `-p` / `--prompt` | 覆盖整个提示词（忽略 -q） | 结构化 JSON |
| `-m` / `--model` | Gemini 模型 | gemini-2.5-flash |
| `-o` / `--output` | 将输出保存到文件 | stdout |
| `--keep` | 保留下载的视频文件 | false |
| `--download-only` | 仅下载，跳过分析 | false |
| `--max-size` | 最大文件大小（MB） | 500 |
| `--raw` | 输出原始文本而非 JSON | false |

## 工作原理

1. **YouTube URL** → 直接传给 Gemini（无需下载）
2. **所有其他 URL** → 通过 yt-dlp 下载 → 上传到 Gemini File API → 轮询直到处理完成
3. Gemini 用结构化提示词分析视频 → 返回 JSON
4. 临时文件与 Gemini 上传项会自动清理

## 支持的来源

任何 [yt-dlp](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md) 支持的 URL：Loom、YouTube、TikTok、Vimeo、Twitter/X、Instagram、Dailymotion、Twitch，以及 1000 多个其他来源。

## 提示

- 使用 `-q` 在完整分析之外提出有针对性的问题
- YouTube 最快（无下载步骤）
- 大视频（10 分钟以上）也能正常工作 — Gemini File API 支持最大 2GB（免费）/ 20GB（付费）
- 脚本会通过 `uv` 自动安装 Python 依赖