videoctx

videoctx

動画を一度インデックス化すれば、どの LLM でも、低コストでいつまでもクエリできます。

videoctx（「video context」）は、ローカルで動作するモデル不要のツールだけを使って、あらゆる動画をオープンでポータブルな動画コンテキストインデックス（.vctx、SPEC.mdを参照）に変換します。使用するのは、ffmpeg のキーフレーム、PySceneDetect のショット境界、faster-whisper の文字起こし、および任意で任意の低コスト VLM による一行の視覚キャプションです。エージェントは、ほとんどの質問にインデックスのテキストレイヤーからわずかなコストで回答し、質問に映像情報が必要な場合にのみ、必要なフレームをその都度取得します。

videoctx index lecture.mp4          # one-time, local, free
videoctx show  lecture.vctx         # the text view the model reads
videoctx ask   lecture.vctx "What diagram is shown when she explains backprop?"

どのような用途に使われていますか

ドキュメントに尋ねるように、動画について質問できます。

• 講義やコース：「この50分の講義を要約して」「バックプロパゲーションの説明箇所はどこ？ そのときスライドには何が表示されている？」
• 会議やインタビュー：「タイムスタンプ付きでアクションアイテムを列挙して」「クライアントが価格に難色を示した場面を見つけて」
• 画面録画：「エラーは何分何秒に表示される？ ダイアログには何と書かれている？」
• コンテンツ制作：「短いクリップに最適な場面を3つ見つけて」「チャプターマーカーを生成して」
• **動画アーカイブ：**トーク動画のフォルダーを一度インデックス化すれば、その後のすべての動画への質問は、数秒で回答され、コストも数セントです。
• **AI エージェント：**MCP に対応したあらゆるエージェント（Claude Code、Cursor、…）に、動画を読み取る機能を与えます。

**対象ユーザー：**開発者、およびターミナルコマンドをいくつか実行できる方です。Python、ffmpeg、質問応答用の Anthropic API キーが必要です（インデックス化自体は無料でオフラインで実行できます）。まだその準備ができていない場合は、リポジトリにスターを付けるか、更新をウォッチしてください。インストール不要のバージョンをロードマップに掲載しています。

理由

ネイティブな動画取り込みでは、質問のたびに動画全体を再トークン化します。1時間の映像は約250,000～350,000トークンになり、質問のたびに同じ処理が必要です。プロプライエタリな動画プラットフォームは、分単位の料金がかかるクローズドな表現にインデックスを作成します。videoctx はその第三の選択肢です。無料ツールで作成する、あらゆるモデルが利用できるオープンなディスク上のフォーマットで、1時間の動画への追加質問にかかる限界費用は約$0.02です。

ベンチマーク結果（Video-MME、2026年10月）

プロトコル全体と、プロンプトキャッシュへの書き込み割増料金を含む正確なコスト計算については、paper/draft.mdを参照してください。クエリモデル：Claude Opus 4.8。

以下の数値は、凍結された設定（v0.2：キャプション＋OCR＋根拠ルール、Opus 4.8 のループ処理；v0.3、2026-10-21：テキスト根拠ルール、文字起こしからの逐語引用、最終的な回答と根拠の照合を追加）を、完全なコスト計算のもとで一度だけ実行した結果です。同じ設定を複数回測定した場合は、観測された範囲を示しています。n=150では、1回の実行ごとに2～3問分の変動があり、n=30では2～3問分（＝7～10ポイント）の変動があります。このベンチマークでは、3ポイント未満の差はノイズとして扱ってください。

サブセット構成に関する注意：動画は Video-MME データセットの順序に従って取得しているため、ドメインごとに偏りがあります。medium と long のデータはすべて Knowledge ドメインの動画で、short のデータは76～88％が Knowledge（残りは Film & Television）です。これらは Video-MME 全体ではなく、Knowledge に偏ったサブセットとして捉えてください。今後はドメインごとに層化した分割を行う予定です。

短い動画、テスト用に確保した半分（n=150）：

方法	正解率	$/問
videoctx v0.4	84.7%	$0.025
videoctx v0.3	82.0%	$0.025
videoctx v0.2	80.7%（同等の設定では80.7～85.3%の範囲）	$0.025
均等なフレームサンプリング	74.0%	$0.0172
Gemini Flash-Lite ネイティブ（パイロット n=30）	70.0%	$0.0009
Gemini Flash ネイティブ（パイロット n=30）	53.3%	$0.0047

中程度の長さの動画、4～15分（n=30、誤差範囲が広い）：

方法	正解率	$/問
均等なフレームサンプリング	80.0%	$0.081
videoctx v0.7（キャッシュ済みプレフィックスにコンタクトシート60@512）	70.0%	初回は$0.092、追加質問は約$0.02
videoctx v0.2～v0.6	66.7%（ほぼ同一の失敗セット）	$0.051～0.062
Gemini Flash-Lite ネイティブ	70.0%	$0.0034
Mediumは最も成績が低いデータセットであり、引き続き名指しの目標です。生の精度ではnaiveが上回っています。5つの構成（プロンプトルール、テキストビューのバグ修正、高密度キャプション、24枚のサムネイルコンタクトシート）すべてで、10問が同じように失敗しました。6つ目の構成では、キャッシュ済みプレフィックスに60枚の512pxサムネイルのコンタクトシートを組み込み、1問を解決しました。結果は一貫した傾向を示しています。これらの動画はカットが速く、字幕がすべて付いており、残る差は質問時の視覚的な詳細を得られる帯域幅です。これはnaiveが持つ構造上の唯一の優位点です。最良の段だけでなく、改善の段階を公開します。

訂正（2026-10-21）：OCR対応インデックスの出荷以降、テキストビューのバグにより、すべてのインデックスでヘッダー行（再生時間、ショット数）が欠落していました。v0.2／v0.3の数値はすべて、このバグがある状態で測定されたものです。v0.4は修正済みの構成です（shortは+2.7ポイント、longは80.0%に戻り、mediumは変わりません）。

長尺動画、30～60分（n=30）：

手法	精度	質問あたりの費用	追加質問あたりの費用
videoctx v0.5（高密度キャプション）	83.3%	$0.109 キャッシュなし（実測値は$0.047、注記参照）	$0.021
videoctx v0.4	80.0%	$0.099	$0.019
videoctx v0.2 / v0.3	80.0% / 76.7%（n=30の誤差範囲）	$0.098	$0.019

費用の訂正（2026-10-22）：v0.5のlongの実行はv0.4の実行から57分後に開始されました。また、高密度キャプションによってテキストビューが変わらなかった10本中7本では、まだ有効だったv0.4の1時間プロンプトキャッシュがそのまま引き継がれ、初回質問の費用が実際より低く見えていました。$0.109/qはキャッシュなしの場合に相当する値です（初回質問は$0.285、追加質問は実測値の$0.021）。この問題が再発しないよう、現在はベンチマークの実行ごとに構成別のキャッシュソルトを設定しています。 | 均等なフレームサンプリング（上限60フレーム） | 70.0% | $0.133 | $0.133 | | Gemini Flash-Lite ネイティブ | 76.7% | $0.022 | $0.022（1問あたり5～9分のレイテンシ） | | ネイティブ取り込み（公開済みPro料金、推定） | 保留中 | ~$0.50 | ~$0.50 |

インデックスの一回限りの費用：動画1時間あたり約$0.10～0.25（キャプション＋ローカルOCR＋ローカル埋め込み）。それ以外はわずかな費用です。

費用の訂正履歴：短い動画の初期の数値（$0.0067/q）は、プロンプトキャッシュ書き込みの割増料金を過少計上していました。計測方法は2026-10-18に修正され、上記の数値はすべて関連費用を含んでいます。こうした計上上の落とし穴を避ける方法については、論文のSection 7.3を参照してください。

インストール

git clone <repo> && cd videoctx
uv venv && uv pip install -e .

PATH上にffmpegが必要です。videoctx indexとMCP サーバーのコアツールは、APIキーなしで完全にローカルで動作します。videoctx askはAnthropic APIを使用します（ANTHROPIC_API_KEYまたはant auth loginプロファイル）。

MCP サーバー：あらゆるエージェントで動画を読み取る

claude mcp add videoctx -- $(pwd)/.venv/bin/videoctx-mcp

呼び出し元のエージェント自身のモデルがテキストレイヤーとフレームを直接読み取ります。サーバーはモデルを呼び出さず、キーも必要ありません。ツール：video_overview（低コストのテキストレイヤー）、survey_video（ショットごとにサムネイル1枚）、get_frames(path, t0, t1, detail)、transcript_search、find_moments（意味に基づく視覚検索。インデックスごとにvideoctx embedを1回実行する必要があります）、index_video。サーバーの指示には根拠に関するルールが含まれています。視覚的な回答では、取得したフレームを引用し、一般知識を根拠にしてはいけません。

ベンチマークを再現する

uv pip install -e ".[eval]"
python eval/prepare_videomme.py --duration short --videos 100 --out eval/data
python eval/split_dev_test.py eval/data/videomme_short.jsonl
python eval/run.py eval/data/videomme_short_test.jsonl --methods videoctx,naive

eval/methods.pyには、各ベースラインの説明があります。費用計算では、キャッシュ書き込みに実際の割増料金（TTLに応じて1.25倍／2倍）を適用します。この方法で避けられる計上上の落とし穴については、論文のSection 7.3を参照してください。

フォーマット

.vctxディレクトリは、プレーンなJSONとJPEGで構成されています：manifest.json（由来情報、パラメーター、ソースハッシュ）、index.json（ショット、キーフレーム、トランスクリプト、キャプション）、frames/。利用側は未知のキーを無視する必要があります。拡張レイヤー（OCR、埋め込み）は、SPEC.md v0.1で予約されています。

ステータスとロードマップ

動作確認とベンチマーク済み：インデックス作成、クエリループ、MCP サーバー、評価ハーネス。 次の予定：mediumのサブセット、Proティアのネイティブベースライン、モデル間の移植性テスト（Claude以外のモデルで同じインデックスを使用）、OCRおよびショットごとの埋め込みレイヤー、spec v1.0。

ライセンス

Apache-2.0。Copyright 2026 Fred Dunyo。