LLM に動画を「本当に見せる」方法：claude-real-video を試してみた

はじめに

LLM に YouTube の URL を渡しても、実際に読まれているのは字幕（トランスクリプト）だけで、映像そのものは見られていない、ということが多いです。Claude は動画ファイルをそもそも受け付けませんし、ネイティブに動画を読める Gemini も、デフォルトでは 1fps の固定間隔でフレームをサンプリングするため、速いカットは抜け落ちてしまいます。

そこで、MIT ライセンスのオープンソースツール claude-real-video（略称 crv）を試してみました。動画をローカルで処理して、「意味のあるフレーム＋タイムスタンプ付きトランスクリプト＋読み方の説明書（マニフェスト）」という、どの LLM でも読めるプレーンなファイル一式に変換してくれるツールです。処理はすべて自分のマシン上で行われ、動画がどこかにアップロードされることはありません。

インストール

必要なのは Python 3.10+ と ffmpeg です。

pip install "claude-real-video[whisper]"

Claude Code / Cursor / Codex などのコーディングエージェントで使う場合は、スキルも 1 コマンドで入ります。

npx skills add HUANGCHIHHUNGLeo/claude-real-video

実行してみる

URL かローカルファイルを渡すだけです。

crv "https://www.youtube.com/watch?v=..."

出力はこうなります。

crv-out/
├── frames/*.jpg      # 選別されたキーフレーム
├── frames.json       # 各フレームのタイムスタンプ
├── transcript.txt    # タイムスタンプ付きトランスクリプト
└── MANIFEST.txt      # LLM に「この一式の読み方」を伝えるファイル

出力が意図的に「地味なプレーンファイル」になっているのがポイントで、だからこそ Claude / ChatGPT / Gemini のどれにでもそのまま投げられます。frames と MANIFEST.txt をドラッグして質問するだけです。

モデルに渡す前に自分の目で確認したい場合は --viewer を付けると、ローカルの viewer.html（動画＋キーフレーム一覧＋トランスクリプト）が生成されます。ネットワーク接続も追加インストールも不要でした。

用途に応じたオプションもいくつかあります。

• --adaptive : アニメーションやスローパンなど、変化が緩やかなコンテンツ向け。固定しきい値ではなく周辺フレームとの相対比較で選別されます
• --text-anchors : スライド講義や画面録画向け。字幕キューのタイムスタンプにフレームを強制追加（sidecar の .srt/.vtt か埋め込み字幕トラックが必要）
• --speakers : インタビューや会議向け。各行に話者ラベルが付きます（ローカルの話者分離モデル 45MB を初回のみダウンロード、アカウント不要）

ターミナルを使いたくない場合は crv-web でローカルの Web ページ（日本語 UI はまだなく、繁体字中国語／簡体字中国語／英語）も開けます。

MCP で Claude / Cursor につなぐ

MCP サーバーとして動かすと、エージェント側から全自動で使えます。

pip install "claude-real-video[mcp]"
crv-mcp

これで任意の MCP クライアント（Claude Desktop、Claude Code、Cursor など）から watch_video ツールを URL またはファイルパスで呼べるようになり、フレームとトランスクリプトを融合した結果が返ってきます。設計上の工夫として、返却されるフレームは長辺 768px にリサイズされ（フル解像度はコンテキストを浪費するだけで視覚的なゲインがないため）、解析結果はソースごとにキャッシュされるので、同じ動画への追加質問で再ダウンロード・再抽出は発生しません。

Claude Code のプラグインマーケットプレイス経由でも導入できます。

/plugin marketplace add HUANGCHIHHUNGLeo/claude-real-video
/plugin install claude-real-video@claude-real-video

どうやってフレームを選んでいるのか（簡単に）

作者のエンジニアリングノートによると、前提となる制約は「vision LLM に現実的に渡せるのは 1 本あたり約 150 枚」というトークン予算です。この予算をどう使うかがすべてで、抽出ではなく「選別」が本体だとされています。

流れをざっくり書くと：

1. シーン検出: ffmpeg の scene スコアでシーン変化ごとにフレームを取得。固定しきい値だとアニメやスローパンを取りこぼすため、移動平均に対する相対値で判定する方式が用意されています
2. 3 チャンネルの重複除去: ① 16×16 のグローバル署名で全体変化を判定（直近に保持した 4 フレームのスライディングウィンドウと比較）、② 32×32 のグリッドで「画面の一部だけが強く動いた」小さな被写体の変化を検出、③ 192×192 の署名で字幕の切り替わりやホワイトボードの書き込みのような局所的な状態変化を検出
3. トランスクリプトとの融合: 埋め込み字幕があればそれを、なければローカル Whisper を使用。各セグメントにどのフレームが属するかを事前に結合してあるので、モデル側でタイムスタンプを突き合わせる必要がありません

実例として、同じ 58 秒のクリップで固定 1fps サンプリングだと 58 枚になるところ、crv は実際に異なる 26 枚だけを残す、という比較が README に載っています。

おわりに

「LLM に記事の要約を読ませる」のと「LLM に動画そのものを見せる」のは別物で、後者ができると、チュートリアルで一瞬だけ映ったエラーメッセージのような「誰も書き起こさなかった情報」まで拾えるようになります。ローカル完結で試せるので、興味のある方はぜひ。

GitHub: https://github.com/HUANGCHIHHUNGLeo/claude-real-video （MIT ライセンス）