Popcorn

🚀 爆米花（Popcorn）

爆米花是一个代理技能，能赋予任何编码代理观看和理解视频的能力。它可与 Claude Code、Codex 以及任何兼容 MCP 的代理协同工作。

🚀 快速开始

安装依赖

# 安装 FFmpeg（必需）
brew install ffmpeg                    # macOS
sudo apt install ffmpeg                # Ubuntu/Debian

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

# 可选：安装转录后端
pip install mlx-whisper                # Apple Silicon（最快）
pip install openai-whisper             # 任何平台

添加到 Claude 桌面配置

将以下内容添加到 Claude 桌面配置文件（~/Library/Application Support/Claude/claude_desktop_config.json）中：

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

✨ 主要特性

• 场景检测 — 在视觉过渡处捕获帧，而非固定间隔。
• 本地转录 — 提供 4 种后端选项（mlx-whisper、faster-whisper、whisper-cpp、whisper）。
• 内联图像 — 在 MCP 响应中直接返回关键帧。
• 智能预设 — 自动为屏幕录制、演示文稿、电影、访谈等进行配置。
• 零配置 — 只需传入视频路径即可工作。
• 隐私优先 — 所有操作都在本地运行，数据不会离开你的设备。

📚 详细文档

入门指南

• 快速开始 — 安装与设置
• 教程 — 逐步使用指南
• MCP 工具 — 可用工具参考

使用指南

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

参考文档

• 故障排除 — 常见问题及解决方案
• 代理技能 — AI 代理的使用说明
• API 参考 — 工具架构与响应

🔧 技术细节

工作原理

核心组件：

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

视频文件 ──▶ FFprobe ──▶ FFmpeg ──▶ Whisper ──▶ 分析包
                 │           │          │              │
                 ▼           ▼          ▼              ▼
              元数据    帧图像    转录文本    MCP 响应

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/<video>_<timestamp>/
├── analysis.json          # 完整元数据
├── transcript.txt         # 纯文本
├── transcript.json        # 带时间戳的片段
├── transcript.chunks.json # 适合大语言模型的块
└── 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   # 任何平台

检测到的帧数过少

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

检测到的帧数过多

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

更多解决方案请参阅 故障排除指南。

🛠️ 开发

npm install          # 安装依赖
npm run build        # 构建项目
npm run dev          # 开发模式
npm start            # 运行服务器

项目结构

popcorn/
├── src/
│   ├── index.ts        # MCP 服务器
│   ├── analyze.ts      # 分析管道
│   ├── ffmpeg.ts       # 视频处理
│   ├── transcribe.ts   # 多后端转录
│   ├── presets.ts      # 视频类型预设
│   └── commands.ts     #  shell 执行
├── docs/               # 文档
└── skills/             # 代理技能

🤝 贡献

1. 分叉仓库
2. 创建功能分支（git checkout -b feature/amazing）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing）
5. 打开拉取请求

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE。

👏 致谢

• OpenAI Whisper — 语音识别
• whisper.cpp — C++ 端口
• MLX Whisper — Apple Silicon
• faster-whisper — CTranslate2
• FFmpeg — 视频处理
• Model Context Protocol — MCP 规范

为全球的 AI 代理打造 🍿