AI导哈

视频分析工具

Popcorn是一款为AI代理设计的本地视频分析工具，能够提取视频转录、检测场景变化并返回关键帧，适用于编码代理理解视频内容。

  • by haithamelmengad
  • TypeScript
  • 本地部署
  • 7 星标
  • 更新于
在 GitHub 查看 haithamelmengad/popcorn

使用说明

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响应中直接返回关键帧
  • 智能预设 --自动配置屏幕录像、演示文稿、电影、采访
  • 零配置 --只需通过一条视频路径，它就可以工作了
  • 隐私第一 --一切都在本地运行，没有数据离开您的机器

文档

入门指南

指南

参考

运作原理

核心组件：

  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工具

工具 说明
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耳语 最快 苹果硅（M1/M2/M3/M4） pip install mlx-whisper
更快的耳语 快速 NVIDIA GPU pip install faster-whisper
耳语cpp 中等 跨平台 brew install whisper-cpp
低语 慢 最兼容 pip install openai-whisper

处理时间（60分钟视频）

后端 时间
mlx耳语 3-8分钟
更快的耳语 5-10分钟
耳语cpp 10-20分钟
耳语 30-60分钟

强制后端

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

配置

所有参数

参数 类型 说明
path 字符串 必修的。 视频文件的绝对路径
videoType string 视频类型预设
objective string 分析目标预设
transcribe boolean 启用/禁用转录
backend string 转录后端
model string Whisper型号(tiny, base, small, medium, large)
language string 语言代码（例如。， en, es, fr)
frameMode 字符串 scene 或 interval
sceneThreshold number 场景灵敏度（0-1）
maxFrames number 要提取的最大帧数
inlineFrames number 以base64格式返回的帧

输出结构

.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
        └── ...

故障排除

未找到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许可证——见 许可证 了解详情。

致谢

Made with 🍿 for AI agents everywhere

相关 MCP