Popcorn

🚀 Popcorn

An agent skill that enables any coding agent to watch and understand videos. It's compatible with Claude Code, Codex, and any MCP-compatible agent, providing local video analysis with no external APIs, fees, and ensuring complete privacy.

🚀 Quick Start

# Install FFmpeg (required)
brew install ffmpeg                    # macOS
sudo apt install ffmpeg                # Ubuntu/Debian

# Install Popcorn
git clone https://github.com/anthropics/popcorn.git
cd popcorn && npm install && npm run build

# Optional: Install a transcription backend
pip install mlx-whisper                # Apple Silicon (fastest)
pip install openai-whisper             # Any platform

Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "popcorn": {
      "command": "node",
      "args": ["/path/to/popcorn/dist/index.js"]
    }
  }
}

✨ Features

• Scene Detection — Captures frames at visual transitions, not fixed intervals
• Local Transcription — 4 backend options (mlx-whisper, faster-whisper, whisper-cpp, whisper)
• Inline Images — Returns key frames directly in MCP responses
• Smart Presets — Auto-configures for screencasts, presentations, movies, interviews
• Zero Config — Just pass a video path and it works
• Privacy First — Everything runs locally, no data leaves your machine

📚 Documentation

Getting Started

• Quick Start — Installation & setup
• Tutorial — Step-by-step usage guide
• MCP Tools — Available tools reference

Guides

• Transcription Backends — Choose the best backend for your system
• Video Types & Objectives — Presets for different content
• Configuration — Advanced parameters

Reference

• Troubleshooting — Common issues & solutions
• Agent Skill — Instructions for AI agents
• API Reference — Tool schemas & responses

🔧 Technical Details

How It Works

Core Components:

1. FFprobe — Extracts video metadata (duration, resolution, codecs)
2. FFmpeg Scene Detection — Finds visual transitions using select='gt(scene,N)' filter
3. Parallel Frame Extraction — Captures JPEGs at scene change timestamps
4. Multi-Backend Transcription — Whisper variants convert audio to timestamped text
5. Analysis Bundle — Results saved to .popcorn/ directory
6. MCP Response — Returns metadata + inline base64 images

Video File ──▶ FFprobe ──▶ FFmpeg ──▶ Whisper ──▶ Analysis Bundle
                 │           │          │              │
                 ▼           ▼          ▼              ▼
              metadata    frames    transcript    MCP Response

📦 MCP Tools

💻 Usage Examples

Basic Usage

{
  "tool": "popcorn_analyze",
  "arguments": {
    "path": "/path/to/video.mp4"
  }
}

Advanced Usage

{
  "tool": "popcorn_analyze",
  "arguments": {
    "path": "/path/to/video.mp4",
    "videoType": "screencast",
    "objective": "detailed"
  }
}

📦 Video Types

📦 Objectives

📦 Transcription Backends

Popcorn auto-detects your system and recommends the best backend.

Backend Comparison

Processing Times (60-min video)

Force a Backend

{
  "tool": "popcorn_analyze",
  "arguments": {
    "path": "/path/to/video.mp4",
    "backend": "mlx-whisper"
  }
}

📦 Configuration

All Parameters

Output Structure

.popcorn/<video>_<timestamp>/
├── analysis.json          # Full metadata
├── transcript.txt         # Plain text
├── transcript.json        # Timestamped segments
├── transcript.chunks.json # LLM-friendly chunks
└── assets/
    ├── audio.wav
    └── frames/
        ├── scene_000001.jpg
        └── ...

📦 Troubleshooting

FFmpeg not found

brew install ffmpeg          # macOS
sudo apt install ffmpeg      # Ubuntu/Debian

No transcription backend

pip install mlx-whisper      # Apple Silicon
pip install openai-whisper   # Any platform

Too few frames detected

{ "sceneThreshold": 0.15, "minSceneInterval": 2 }

Too many frames detected

{ "sceneThreshold": 0.5, "minSceneInterval": 10 }

See Troubleshooting Guide for more solutions.

📦 Development

npm install          # Install dependencies
npm run build        # Build
npm run dev          # Development mode
npm start            # Run server

Project Structure

popcorn/
├── src/
│   ├── index.ts        # MCP server
│   ├── analyze.ts      # Analysis pipeline
│   ├── ffmpeg.ts       # Video processing
│   ├── transcribe.ts   # Multi-backend transcription
│   ├── presets.ts      # Video type presets
│   └── commands.ts     # Shell execution
├── docs/               # Documentation
└── skills/             # Agent skills

📦 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing)
5. Open a Pull Request

📄 License

MIT License — see LICENSE for details.

📦 Acknowledgments

• OpenAI Whisper — Speech recognition
• whisper.cpp — C++ port
• MLX Whisper — Apple Silicon
• faster-whisper — CTranslate2
• FFmpeg — Video processing
• Model Context Protocol — MCP spec

Made with 🍿 for AI agents everywhere