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 代理打造 🍿