Popcorn

🚀 🍿 popcorn

このエージェントスキルは、任意のコーディングエージェントに動画を視聴し理解する能力を付与します。Claude Code、Codex、およびMCP互換のエージェントで動作します。

README • ⚖️ ライセンス

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

クイックスタート • 仕組み • MCPツール • 文字起こし • 設定 • トラブルシューティング • ライセンス

Popcornは、トランスクリプトを抽出し、シーンの変化を検出し、キーフレームを返すことで、AIエージェントが長時間の動画を視聴し理解できるようにします。すべてがローカルで実行され、外部APIや料金は必要なく、完全なプライバシーが保証されます。

🚀 クイックスタート

# 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 Desktopの設定ファイル (~/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 # LLMに適したチャンク
└── 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     # シェル実行
├── 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エージェントのために🍿で作られました