Popcorn MCP

README • ⚖️ License

🍿

popcorn

🇨🇳 中文 • 🇯🇵 日本語 • 🇰🇷 한국어 • 🇪🇸 Español • 🇩🇪 Deutsch • 🇫🇷 Français • 🇧🇷 Português • 🇷🇺 Русский • 🇸🇦 العربية • 🇮🇹 Italiano • 🇳🇱 Nederlands • 🇹🇷 Türkçe • 🇻🇳 Tiếng Việt • 🇮🇳 हिन्दी

An agent skill that gives any coding agent the ability to watch and understand video. Works with Claude Code, Codex, and any MCP-compatible agent.

Quick Start • How It Works • MCP Tools • Transcription • Configuration • Troubleshooting • License

Popcorn enables AI agents to watch and understand long-form videos by extracting transcripts, detecting scene changes, and returning key frames. Everything runs locally—no external APIs, no fees, complete privacy.

______________________________________________________________________

快速开始

# 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

添加到Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json):

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

主要特点：

• 场景检测 --以视觉过渡而非固定间隔捕获帧
• 本地转录 --4种后端选项（mlx耳语、更快耳语、耳语cpp、耳语）
• 内联图像 --在MCP响应中直接返回关键帧
• 智能预设 --自动配置屏幕录像、演示文稿、电影、采访
• 零配置 --只需通过一条视频路径，它就可以工作了
• 隐私第一 --一切都在本地运行，没有数据离开您的机器

______________________________________________________________________

文档

入门指南

• 快速开始 --安装和设置
• 教程 --分步使用指南
• MCP工具 --可用工具参考

指南

• 转录后端 --为您的系统选择最佳后端
• 视频类型和目标 --不同内容的预设
• 配置 --高级参数

参考

• 故障排除 --常见问题和解决方案
• 代理技能 --AI代理说明
• API 参考 --工具模式和响应

______________________________________________________________________

运作原理

核心组件：

1. FF探头 --提取视频元数据（持续时间、分辨率、编解码器）
2. FFmpeg场景检测 --使用以下命令查找视觉过渡 select='gt(scene,N)' 过滤器
3. 并行帧提取 --在场景切换时间戳处捕获JPEG
4. 多后端转录 --Whisper变体将音频转换为带时间戳的文本
5. 分析包 --结果保存到 .popcorn/ 目录
6. MCP响应 --返回元数据+内联base64图像

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

______________________________________________________________________

MCP工具

基本用法

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

带预设

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

______________________________________________________________________

视频类型

目标

______________________________________________________________________

转录后端

Popcorn会自动检测您的系统并推荐最佳后端。

后端比较

处理时间（60分钟视频）

强制后端

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

______________________________________________________________________

配置

所有参数

输出结构

.popcorn/_/
├── 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
        └── ...

______________________________________________________________________

故障排除

未找到FFmpeg

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

无转录后端

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

检测到的帧太少

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

检测到太多帧

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

看 故障排除指南 更多解决方案。

______________________________________________________________________

发展

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

项目结构

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

______________________________________________________________________

贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing)
3. 提交更改(git commit -m 'Add amazing feature')
4. 推送到分支(git push origin feature/amazing)
5. 打开拉取请求

______________________________________________________________________

许可证

MIT许可证——见 许可证 了解详情。

______________________________________________________________________

致谢

• OpenAI耳语 --语音识别
• whisper.cpp --C++端口
• MLX耳语 --苹果硅
• 更快的耳语 --C翻译2
• FFmpeg --视频处理
• 模型上下文协议 --MCP规范

______________________________________________________________________

Made with 🍿 for AI agents everywhere