JinDaGe - popcorn MCP Details

article

README

🚀 爆米花（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 参考 — 工具架构与响应

🔧 技术细节

工作原理

核心组件：

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

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

MCP 工具

| 工具 | 描述 | |------|-------------| | popcorn_analyze | 主要分析工具 — 提取帧、转录音频并返回结果 | | popcorn_suggest | 探测视频元数据并获取推荐设置 | | popcorn_presets | 列出可用的视频类型和目标 | | popcorn_backends | 检测你的系统并显示转录选项 | | popcorn_read | 按时间过滤读取转录片段 |

基础用法

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

使用预设

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

视频类型

| 类型 | 适用场景 | 场景检测 | |------|----------|-----------------| | screencast | 教程、编码会话、UI 演示 | 低阈值 | | presentation | 幻灯片、讲座、主题演讲 | 幻灯片过渡 | | movie | 电影、电视剧 | 平衡 | | interview | 播客、访谈 | 转录优先 | | surveillance | 监控录像、行车记录仪 | 高阈值 | | sports | 现场活动、快速动作 | 高帧率 |

分析目标

| 目标 | 使用场景 | |-----------|----------| | summary | 需要快速概述 | | detailed | 不想错过任何细节 | | find_moment | 搜索特定内容 | | transcribe | 音频/语音最重要 | | visual_only | 只关注视觉效果 | | quick_scan | 需要快速预览 |

转录后端

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

后端比较

| 后端 | 速度 | 适用场景 | 安装命令 | |---------|-------|----------|---------| | mlx-whisper | 最快 | Apple Silicon（M1/M2/M3/M4） | pip install mlx-whisper | | faster-whisper | 快 | NVIDIA GPU | pip install faster-whisper | | whisper-cpp | 中等 | 跨平台 | brew install whisper-cpp | | whisper | 慢 | 兼容性最强 | pip install openai-whisper |

处理时间（60 分钟视频）

| 后端 | 时间 | |---------|------| | mlx-whisper | 3 - 8 分钟 | | faster-whisper | 5 - 10 分钟 | | whisper-cpp | 10 - 20 分钟 | | whisper | 30 - 60 分钟 |

强制使用后端

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

配置

所有参数

| 参数 | 类型 | 描述 | |-----------|------|-------------| | path | 字符串 | 必需。 视频文件的绝对路径 | | videoType | 字符串 | 视频类型预设 | | objective | 字符串 | 分析目标预设 | | transcribe | 布尔值 | 启用/禁用转录 | | backend | 字符串 | 转录后端 | | model | 字符串 | Whisper 模型（tiny、base、small、medium、large） | | language | 字符串 | 语言代码（例如，en、es、fr） | | frameMode | 字符串 | scene 或 interval | | sceneThreshold | 数字 | 场景敏感度（0 - 1） | | maxFrames | 数字 | 最大提取帧数 | | inlineFrames | 数字 | 以 base64 形式返回的帧数 |

输出结构

.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/             # 代理技能

🤝 贡献

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

📄 许可证

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

👏 致谢

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

为全球的 AI 代理打造 🍿

popcorn