videoctx

videoctx

只需为视频建立一次索引。之后可用任意大模型以低成本无限查询。

videoctx（“video context”，即视频上下文）仅使用本地、无需模型的工具，将任意视频转换为开放、可移植的 视频上下文 索引（.vctx，参见 SPEC.md）：ffmpeg 关键帧、PySceneDetect 镜头边界、faster-whisper 转录文本，以及可选的、由任意低成本 VLM 生成的单行视觉说明。Agent 可从索引的文本层回答大多数问题，成本仅为几分之一美分；只有问题需要查看像素时，才会按需提取单帧。

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 分钟的讲座。”“她在哪儿讲解了反向传播？当时的幻灯片上是什么内容？”
• 会议和访谈：“列出行动事项及其时间戳。” “找出客户对定价提出异议的时刻。”
• 屏幕录制：“错误在什么时间出现？对话框里写了什么？”
• 内容创作：“找出最适合制作短片的三个精彩片段。” “生成章节标记。”
• **视频档案：**为一个文件夹里的讲座建立一次索引，之后针对所有视频的每个问题都只需几美分，并可在几秒内得到答案。
• **AI Agent：**让任何支持 MCP 的 Agent（Claude Code、Cursor 等）都能读取视频。

**适用人群：**开发者，以及能够熟练运行几条终端命令的用户。你需要 Python、ffmpeg 和一个 Anthropic API 密钥来回答问题（建立索引本身免费且可离线完成）。如果你还不具备这些条件，可以给仓库加星或关注：路线图中规划了免安装版本。

为什么要用 videoctx

原生视频摄取会在每次提问时重新对整个视频进行分词：一小时的视频内容约为 250-350k 个 token，每次都要重新处理。专有视频平台会将视频索引到封闭格式中，并按分钟收费。videoctx 提供第三种选择：一种开放的磁盘格式，任何模型都能使用，由免费工具生成；对于一小时视频的后续提问，边际成本约为 $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 的测试中，单次运行的结果会波动 2-3 道题；在 n=30 的测试中，会波动 2-3 道题（= 7-10 个百分点）。在此基准测试中，低于 3 个百分点的差异应视为噪声。

子集构成注意事项：视频按照 Video-MME 数据集中的顺序选取，该顺序按领域分组。中等和长视频组完全由知识领域视频构成；短视频组中，知识领域占 76-88%，其余为电影与电视。应将这些结果视为以知识领域为主的 Video-MME 子集，而非完整基准测试；未来的划分将按领域分层。

短视频，留出测试集的一半（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 原生模式（试点测试 30 个）	70.0%	$0.0009
Gemini Flash 原生模式（试点测试 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
中等长度视频是我们最弱的一档，仍是明确的优化目标：朴素方法的原始准确率最高。五种配置（提示词规则、修复文本视图错误、密集字幕、包含 24 张缩略图的联系表）中，十个问题的结果完全相同；第六种配置将包含 60 张 512px 缩略图的联系表写入缓存前缀后，答对了其中一个。证据呈现出一致的情况：这些视频剪辑节奏快且字幕齐全，剩余差距在于提问时的视觉细节带宽，而这是朴素方法唯一的结构性优势。我们公布完整的改进阶梯，而不只展示最高一档。

更正（2026-10-21）：一个文本视图错误导致所有 OCR 增强索引都丢失了标题行（时长、镜头数）；自 OCR 发布以来一直如此。所有 v0.2/v0.3 数据均在该错误存在时测得。v0.4 是修正后的配置（短视频提升 2.7 个百分点，长视频恢复至 80.0%，中等长度视频不变）。

长视频，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 长视频测试在 v0.4 测试结束 57 分钟后开始；对于 10 个文本视图未受密集字幕影响的视频中的 7 个，测试静默沿用了仍然有效、时长为 1 小时的 v0.4 提示词缓存，导致首个问题的费用偏低。$0.109/问题是冷缓存等效费用（首个问题 $0.285，后续问题实测为 $0.021）。现在基准测试会按配置使用不同的缓存盐值，以免此情况再次发生。 | 均匀帧采样（最多 60 帧） | 70.0% | $0.133 | $0.133 | | Gemini Flash-Lite 原生 | 76.7% | $0.022 | $0.022（每个问题延迟 5-9 分钟） | | 原生导入（已公布的 Pro 费率，估算） | 待定 | ~$0.50 | ~$0.50 |

一次性索引费用：每小时视频约 ~$0.10-0.25（字幕 + 本地 OCR + 本地嵌入），其他情况下只需几分钱。

费用更正历史：早期短视频数据（$0.0067/问题）低估了提示词缓存写入附加费用；计量方式已于 2026-10-18 修正，以上所有数据均计入了全部费用。详情请见论文第 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 服务：让任意 Agent 读取视频

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

调用方 Agent 使用自身模型直接读取文本层和帧；服务不会调用模型，也不需要密钥。工具：video_overview（低成本文本层）、survey_video（每个镜头一张缩略图）、get_frames(path, t0, t1, detail)、transcript_search、find_moments（语义视觉搜索，每个索引需先运行一次 videoctx embed）、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.25x / 2x）；相关核算容易出错之处及避免方法，请见论文第 7.3 节。

格式

.vctx 目录是纯 JSON + JPEG：manifest.json（来源信息、参数、源文件哈希）、index.json（镜头、关键帧、转录文本、字幕）、frames/。使用方必须忽略未知键；增强层（OCR、嵌入）的相关字段已在 SPEC.md v0.1 中预留。

状态与路线图

已实现并完成基准测试：索引、查询循环、MCP 服务、评估框架。 下一步：中等时长视频子集、Pro 层级原生基线、跨模型可移植性测试（通过非 Claude 模型使用相同索引）、OCR 和逐镜头嵌入层、规范 v1.0。

许可证

Apache-2.0。版权所有 2026 Fred Dunyo。