Content
# ai-video-prepper
Extract transcripts, screen content, and structured summaries from video files — fully on-device or via Gemini API.
Two modes depending on your privacy and speed requirements:
| | Local Pipeline | Gemini Path |
|---|---|---|
| **Privacy** | 100% on-device | Video uploaded to Google |
| **Speed** | 30–60 min / hr of video | 2–4 min / hr of video |
| **Cost** | Free (compute only) | ~$0.35 / hr of video |
| **Screen OCR** | qwen2.5vl:7b via Ollama | Native Gemini vision |
| **Setup** | Ollama + Python deps | Google API key |
---
## What it produces
- **Full transcript** with timestamps (spoken audio)
- **Screen content descriptions** — reads text on screen, slides, code, URLs, UI state
- **Structured summary** — key topics, decisions, action items
- **Per-scene analysis** — what was said and what was visible at each moment
---
## Quick Start
### Gemini path (recommended for speed)
```bash
# Install deps
npm install
# Set your API key (get one free at aistudio.google.com)
export GEMINI_API_KEY=your_key_here
# Analyze a video
npm run analyze:gemini -- path/to/video.mp4
```
Output lands in `output/<video-stem>-analysis/analysis.md`.
**Caching:** Re-running the **same file path** with the same options skips work via a full-result cache under `~/.ai-video-prepper/cache/` (SHA256 filenames). Use **`--force`** to always re-run; **`--cache-dir <dir>`** to relocate the cache. On Gemini only, **`--no-cache`** applies to the **File API upload** cache (`.cache.json` next to outputs), not the full-result cache.
### Web UI (barebones)
Same Gemini pipeline in the browser: file is sent to a **local** server (key stays in `process.env`).
```bash
export GEMINI_API_KEY=your_key_here
npm run web
```
Open [http://127.0.0.1:3840](http://127.0.0.1:3840) (set `PORT` to change). Drag a video, optionally add a guiding question, then **Analyze**. The response shows a short summary plus full JSON in the page.
Uploads are buffered in memory (up to 2GB); for very large files prefer the CLI.
### MCP server (Cursor)
Expose the same pipelines as Cursor tools over stdio:
```bash
npm run mcp
```
See [docs/mcp.md](docs/mcp.md) for tool list and `mcp.json` setup.
### Local path (fully offline)
Requires Ollama running with a vision model, faster-whisper, and PySceneDetect.
```bash
# One-time setup — macOS only (Homebrew + launchctl); see docs for other platforms
npm run setup:local
# Analyze
npm run analyze -- path/to/video.mp4
```
Same full-result cache defaults as Gemini CLI (`~/.ai-video-prepper/cache`, **`--force`**, **`--cache-dir`**).
### Custom prompts (`--prompts-dir`)
**Gemini** (`npm run analyze:gemini -- --prompts-dir ./my-prompts video.mp4`): the directory must contain **both** `extraction.txt` and `synthesis.txt`. Each file is only the task / preamble; the tool always appends the fixed JSON shape instructions so Zod validation stays valid.
**Local** (`npm run analyze -- --prompts-dir ./my-prompts video.mp4`): requires **all** of `synthesis.txt`, `frame_analysis/frame_analysis.txt`, and `frame_analysis/describe.txt`. Those mirror the patched `video-analyzer` templates (full text); keep placeholders like `{PREVIOUS_FRAMES}`, `{prompt}`, `{FRAME_NOTES}`, `{TRANSCRIPT}` if your copy is based on the repo defaults.
If any required file is missing, the CLI exits with an error (no partial fallback).
**`--context-continuity`** (local only): analyzes frames **sequentially** and fills `{PREVIOUS_FRAMES}` from recent prior descriptions. Much slower than the default parallel path (8-wide), but better cross-frame consistency.
---
## Project Structure
```
ai-video-prepper/
├── src/
│ ├── analyze-gemini.ts # Gemini CLI
│ ├── mcp-server.ts # MCP (stdio) for Cursor
│ ├── web-server.ts # local web UI + upload API
│ ├── services/
│ │ ├── gemini-analysis.service.ts
│ │ └── local-analysis.service.ts
│ ├── analyze.ts # Local pipeline CLI (video-analyzer + Ollama)
│ ├── prompts/ # Gemini / synthesis prompt builders (TS)
│ ├── utils/
│ │ ├── cache.util.ts # File URI cache + full-result cache helpers
│ │ ├── mcp-server.helpers.ts # MCP listing + response formatting
│ │ ├── mcp-tool-schemas.ts # Zod shapes for MCP tools
│ │ └── prompt.util.ts # --prompts-dir file loading + cache bundle
│ └── types/
├── web/
│ └── public/
│ └── index.html # drag-and-drop UI
├── scripts/
│ ├── setup-local.mjs # One-time local setup (macOS)
│ └── patches/ # video-analyzer site-package patches
├── output/ # Analysis results (gitignored)
└── docs/
├── roadmap.md
├── next-session.md
└── system/
└── pipeline-architecture.md
```
---
## Requirements
### Gemini path
- Node.js 18+
- `@google/genai` (installed via npm)
- Free Google AI Studio API key
- ffmpeg (for `ffprobe` — used for duration detection on long videos)
### Local path
- Node.js 18+ (TypeScript orchestration)
- Python 3.10+ (video-analyzer, scenedetect, faster-whisper)
- [Ollama](https://ollama.ai) with a vision model (e.g. `qwen2.5vl:7b`)
- ffmpeg
**Recommended hardware for local path:** Apple Silicon M-series with 32GB+ RAM, or equivalent with dedicated GPU.
---
## Performance (local path, Apple Silicon M4 Max)
| Video | Duration | Frames | Total Time |
|---|---|---|---|
| Screenshare tutorial | 5 min | ~35 (uniform fallback) | ~11 min |
| Mixed-content video | 5 min | ~18 (scene detection) | ~4 min |
| Long recording | 1 hr | 150 (capped) | ~45–60 min |
For the Gemini path, all of the above take 2–4 minutes regardless of length.
---
## Docs
- [Roadmap](docs/roadmap.md) — planned phases and technical decisions
- [MCP (Cursor)](docs/mcp.md) — stdio server and tool reference
- [Pipeline Architecture](docs/system/pipeline-architecture.md) — how both paths work under the hood
---
## License
MIT
