内容
# 视频准备工具
从视频文件中提取文字记录、屏幕内容和结构化摘要 — 完全在设备上进行或通过 Gemini API 进行。
根据您的隐私和速度需求，有两种模式：
| | 本地处理流程 | Gemini 路径 |
|---|---|---|
| **隐私** | 100% 在设备上进行 | 视频上传到 Google |
| **速度** | 30–60 分钟 / 小时视频 | 2–4 分钟 / 小时视频 |
| **成本** | 免费（仅计算） | ~$0.35 / 小时视频 |
| **屏幕 OCR** | 通过 Ollama 使用 qwen2.5vl:7b | 原生 Gemini 视觉 |
| **设置** | Ollama + Python 依赖项 | Google API 密钥 |
---
## 输出内容
- **完整文字记录**，带有时间戳（口语音频）
- **屏幕内容描述** — 读取屏幕上的文本、幻灯片、代码、URL、UI 状态
- **结构化摘要** — 关键主题、决策、行动项
- **每场景分析** — 在每个时刻说了什么和看到了什么
---
## 快速入门
### Gemini 路径（推荐速度）
```bash
# 安装依赖项
npm install
# 设置您的 API 密钥（在 aistudio.google.com 上免费获取）
export GEMINI_API_KEY=您的密钥
# 分析视频
npm run analyze:gemini -- path/to/video.mp4
```
输出结果位于 `output/<video-stem>-analysis/analysis.md`。
**缓存：** 重新运行 **相同的路径** 和相同的选项会跳过工作，使用 `~/.ai-video-prepper/cache/` 下的完整结果缓存（SHA256 文件名）。使用 **`--force`** 始终重新运行；使用 **`--cache-dir <dir>`** 重新定位缓存。仅在 Gemini 上，`--no-cache` 应用于 **文件 API 上传** 缓存（输出旁边为 `.cache.json`），而不是完整结果缓存。
### 网络界面（简单）
浏览器中的相同 Gemini 处理流程：文件发送到 **本地** 服务器（密钥保留在 `process.env` 中）。
```bash
export GEMINI_API_KEY=您的密钥
npm run web
```
打开 [http://127.0.0.1:3840](http://127.0.0.1:3840) （设置 `PORT` 以更改）。拖放视频，可选地添加指导问题，然后 **分析**。响应显示短摘要和页面中的完整 JSON。
上传缓冲在内存中（最多 2GB）；对于非常大的文件，请优先使用 CLI。
### MCP 服务器（Cursor）
通过 stdio 将相同的处理流程暴露为 Cursor 工具：
```bash
npm run mcp
```
参见 [docs/mcp.md](docs/mcp.md) 获取工具列表和 `mcp.json` 设置。
### 本地路径（完全离线）
需要 Ollama 运行带有视觉模型、faster-whisper 和 PySceneDetect。
```bash
# 一次性设置 — 仅限 macOS（Homebrew + launchctl）；其他平台请参见文档
npm run setup:local
# 分析
npm run analyze -- path/to/video.mp4
```
与 Gemini CLI 相同的完整结果缓存默认值 (`~/.ai-video-prepper/cache`、`--force`、`--cache-dir`)。
### 自定义提示（ `--prompts-dir` ）
**Gemini** (`npm run analyze:gemini -- --prompts-dir ./my-prompts video.mp4`）：目录必须包含 **两个** `extraction.txt` 和 `synthesis.txt`。每个文件仅为任务/前言；工具始终附加固定的 JSON 形状指令，以便 Zod 验证保持有效。
**本地** (`npm run analyze -- --prompts-dir ./my-prompts video.mp4`)：需要 **所有** `synthesis.txt`、`frame_analysis/frame_analysis.txt` 和 `frame_analysis/describe.txt`。这些镜像修补的 `video-analyzer` 模板（完整文本）；保留占位符，如 `{PREVIOUS_FRAMES}`、`{prompt}`、`{FRAME_NOTES}`、`{TRANSCRIPT}`，如果您的副本基于存储库默认值。
如果缺少任何必需文件，CLI 将退出并显示错误（无部分回退）。
**`--context-continuity`** （仅本地）：按顺序分析帧，并从最近的先前描述中填充 `{PREVIOUS_FRAMES}`。比默认并行路径（8-wide）慢得多，但具有更好的跨帧一致性。
---
## 项目结构
```
ai-video-prepper/
├── src/
│ ├── analyze-gemini.ts # Gemini CLI
│ ├── mcp-server.ts # MCP（stdio）用于 Cursor
│ ├── web-server.ts # 本地 Web UI + 上传 API
│ ├── services/
│ │ ├── gemini-analysis.service.ts
│ │ └── local-analysis.service.ts
│ ├── analyze.ts # 本地管道 CLI（video-analyzer + Ollama）
│ ├── prompts/ # Gemini / 合成提示生成器（TS）
│ ├── utils/
│ │ ├── cache.util.ts # 文件 URI 缓存 + 完整结果缓存帮助程序
│ │ ├── mcp-server.helpers.ts # MCP 列表 + 响应格式设置
│ │ ├── mcp-tool-schemas.ts # MCP 工具的 Zod 形状
│ │ └── prompt.util.ts # --prompts-dir 文件加载 + 缓存包
│ └── types/
├── web/
│ └── public/
│ └── index.html # 拖放 UI
├── scripts/
│ ├── setup-local.mjs # 一次性本地设置（macOS）
│ └── patches/ # video-analyzer 站点包补丁
├── output/ # 分析结果（gitignored）
└── docs/
├── roadmap.md
├── next-session.md
└── system/
└── pipeline-architecture.md
```
---
## 要求
### Gemini 路径
- Node.js 18+
- `@google/genai` （通过 npm 安装）
- 免费的 Google AI Studio API 密钥
- ffmpeg（用于 `ffprobe` — 用于长视频的时长检测）
### 本地路径
- Node.js 18+（TypeScript 编排）
- Python 3.10+（video-analyzer、scenedetect、faster-whisper）
- [Ollama](https://ollama.ai) 带有视觉模型（例如 `qwen2.5vl:7b`）
- ffmpeg
**本地路径的推荐硬件：** 带有 32GB+ RAM 的 Apple Silicon M 系列，或带有专用 GPU 的等效设备。
---
## 性能（本地路径，Apple Silicon M4 Max）
| 视频 | 时长 | 帧数 | 总时间 |
|---|---|---|---|
| 屏幕分享教程 | 5 分钟 | ~35（统一回退） | ~11 分钟 |
| 混合内容视频 | 5 分钟 | ~18（场景检测） | ~4 分钟 |
| 长录制 | 1 小时 | 150（上限） | ~45–60 分钟 |
对于 Gemini 路径，所有上述内容均需 2–4 分钟，无论长度如何。
---
## 文档
- [路线图](docs/roadmap.md) — 计划阶段和技术决策
- [MCP（Cursor）](docs/mcp.md) — stdio 服务器和工具参考
- [管道架构](docs/system/pipeline-architecture.md) — 两个路径的工作原理
---
## 许可证
MIT
