agentic-video

agentic-video

agentic-video 让能够读取文本和图像、但无法读取视频的 AI Agent 处理你本机上的视频文件。它是一个 Python 库，也是一款 stdio MCP 服务。Agent 会提出简短、针对性的问题（“显示 0:40 到 1:10 之间的 12 帧”“‘launch’ 是什么时候说的？”），并获取测量结果、转录文本和联系表：由多帧组成的网格，每帧的时间戳都直接嵌入像素中。除两个可选云端工具（watch_for、label_sounds）外，所有操作都通过 FFmpeg、Whisper 和可选的本地模型在本机运行；只有在设置凭据并调用这两个工具时，帧或音频才会发送到 Cloudflare Workers AI。另有一项可选择加入的影子转录试用（默认关闭，仅限所有者的机器）也会在启用开关并设置凭据后将音频发送到 Cloudflare。

查看实际效果： https://agentic-video-gallery.infra-1b7.workers.dev（图库：真实任务，包括未成功的任务）。

2 分钟快速体验

选择一种方式并按步骤操作。

• **Claude Code：**运行 brew install ffmpeg uv，然后运行 claude mcp add -s user agentic-video -- uvx agentic-video。
• **Claude Desktop：**从最新版本下载 .mcpb 并双击打开（仅限 macOS；请先运行 brew install ffmpeg）。
• **Claude Code 插件：**先运行 brew install ffmpeg uv（该插件的服务会运行 uvx），然后运行 claude plugin marketplace add tlq5l/agentic-video，再运行 claude plugin install agentic-video@agentic-video（文档）。
• 其他客户端：运行 MCP 服务中提供了 JSON 代码块。

然后粘贴这条提示词：“Use agentic-video: make a contact sheet of /path/to/video.mp4 and list its cuts”

• 六个附带真实输出的任务示例：每个示例都包含一条提示词和工具结果。
• 用它做过什么？欢迎在讨论区告诉我们。
• 发现遗漏？提交问题。

**安装：**macOS 上运行 brew install ffmpeg，或在 Debian 或 Ubuntu 上运行 sudo apt-get install -y ffmpeg（uv 的安装命令见安装）。然后使用 claude mcp add -s user agentic-video -- uvx agentic-video（或 pipx install agentic-video）将其添加到 Claude Code。其他客户端请参阅运行 MCP 服务。

**Claude Desktop（一键安装）：**从最新的 GitHub 版本下载 agentic-video-<version>.mcpb 并双击打开。仍需运行 brew install ffmpeg。首次启动时，Claude Desktop 会安装 Python 软件包，大约需要一分钟。仅限 macOS。此安装包不包含本地视觉搜索或屏幕文字计数功能；如需使用这些功能，请采用下文“可选：视觉搜索（CLIP）和屏幕文字”一节中的 git 安装方式。详情：docs/features/desktop-bundle.md。

对一段 5 秒视频片段调用一次 contact_sheet：生成一张包含六帧的图片，每帧都标注了时间，Agent 可以读取这张图片。

只需 2 分钟（macOS），你的 Agent 就能回答本地视频文件中的“这段视频发生了什么？”和“X 是什么时候说的？”。你可以获取视频时长和大小、带时间戳的联系表图片、剪辑点、响度摘要以及可搜索的语音内容。除非你使用下文的可选云端工具，或开启影子转录试用开关（默认关闭，且仅限所有者的设备），否则任何内容都不会离开你的设备。Claude Code 的设置方式：

brew install ffmpeg uv
git clone https://github.com/tlq5l/agentic-video.git && cd agentic-video
uv venv --python 3.12 .venv && uv pip install --python .venv/bin/python -r requirements.txt
claude mcp add -s user agentic-video -e PYTHONPATH="$PWD" -- "$PWD/.venv/bin/python" -m src.executor.mcp_server

在 Debian 或 Ubuntu 上，请运行 sudo apt-get install -y ffmpeg git 和 curl -LsSf https://astral.sh/uv/install.sh | sh，代替第一行命令；然后打开一个新的 shell，以便将 uv 加入 PATH。

接着询问：“Use agentic-video to review /path/to/video.mp4。”其他客户端和详情请参阅：运行 MCP 服务。

**状态：**实验性。作者每天都在使用；支持仅按尽力而为提供。欢迎提交问题和拉取请求，但回复可能较慢。

它为 Agent 提供什么

MCP 服务公开了 25 个工具（完整架构见 src/adapters/mcp_schemas.json）：

• 查看： review_video（一次调用即可初步查看：元数据、联系表、剪辑点、近黑画面片段和响度摘要）、probe_video（时长、fps、尺寸、编解码器、音频）、contact_sheet、overview_chunks（长视频中连续的联系表）、inspect_window / inspect_windows（查看短片段的密集帧；对 inspect_window 使用 read_text 会添加每帧屏幕上显示的文字）、frame_at（以全尺寸获取一个精确帧，可选择裁剪并放大以读取小字；read_text: true 还会返回读取到的屏幕文字，在 macOS 上使用 Apple Vision）、inspect_moments（获取指定时刻附近的帧）、refine_temporal_beam（放大查看候选窗口）。
• 聆听： transcribe（带时间戳的语音转录，已缓存；对于尚无缓存转录的视频，会启动后台任务，因此首次调用会返回 status: in_progress 和 retry_after_seconds：等待指定秒数后再次调用同一工具）、search_transcript（查找词语出现的时间：先查找精确词语；如果已配置可选的本地 EmbeddingGemma 2 模型，之后再查找语义匹配的段落；未配置时仅按关键词查找）。
• 查找： detect_cuts（硬切和动画场景变化）、check_frame_cadence（检查帧重复的片段，即画面更新频率低于帧率的情况，例如将 30 fps 补帧至 60）、build_visual_index + search_visual（可选的本地 CLIP 搜索可见内容；包含最高分命中项的区间会从其最佳帧开始，仅向相邻且得分接近最高分的帧扩展，最长为 8 秒，因此区间可能更短；如果某个片段本身已超过 8 秒，例如定格帧或合并在一起的命中项，则会保留整个片段，因此区间可能更长，也可能包含得分较低的命中项）。watch_for（云端：当关于画面的是／否问题开始有明确答案时发出通知，基于采样帧）。
• 计数和跟踪： count_occurrences（统计物体或屏幕文字的独立出现次数；direction 用于统计沿某一方向穿过画面的目标，也会统计持续时间太短而无法显示运动的片段）、count_repetitions（统计重复动作的循环次数）、track_region_changes / track_region_events（跟踪同一个固定矩形区域内的变化）。
• 音频与同步： audio_onsets（合并间隔小于 min_gap_sec 的检测结果，默认值为 0.035 s）、loudness_timeline、spectrogram_window、sync_check（将剪辑点和声音提示与测得的音频进行核对；每个提示都会给出 candidate_onsets_count；verbose: true 会返回每个提示的完整 candidate_onsets 列表，而不是计数）。label_sounds（云端：为一段音频中的声音命名）。

哪些工具需要 Mac、Apple Vision、带 CLIP 模型的 torch 或 Cloudflare 凭据，以及每个工具的运行位置：docs/capabilities.md。Agent 可以将 inspect_moments 的时刻作为纯数字或 {"time": 12.5} 传入，并将 region 设为 [x, y, width, height]；两种形式都会按文档所述的格式读取。参见 docs/features/argument-shapes.md。

此外，还有一个用于检查渲染后视频的命令行检查器：python -m src.loop check <video> 会测量同步情况、响度、起始点、剪辑点和一些画面故障，然后写入 report.md 及证据图像。python -m src.loop cadence <video> 会以 JSON 格式打印 check_frame_cadence 的结果。

AGENTS.md 指南说明了何时使用哪个工具。FEATURES.md 则将各项功能映射到对应的代码和测试。

安装（macOS 或 Linux）

你需要 FFmpeg、Git 和 uv。已在 Apple 芯片的 macOS（Python 3.12）和 Debian 12（x86_64）上测试。

macOS（Homebrew）：

brew install ffmpeg uv
git clone https://github.com/tlq5l/agentic-video.git
cd agentic-video
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -r requirements.txt pytest jsonschema
.venv/bin/python -m pytest -q   # optional: about 3 minutes

Debian 或 Ubuntu（apt 和 uv 安装程序；运行 uv 那一行后，请打开新的 shell，以便 uv 加入 PATH）：

sudo apt-get install -y ffmpeg git
curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/tlq5l/agentic-video.git
cd agentic-video
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -r requirements.txt pytest jsonschema
.venv/bin/python -m pytest -q   # optional: about 3 minutes

用户可以选择是否运行测试。

要在每次提交前运行 lint（uvx ruff check .，规则核心见 ruff.toml），请在每个克隆仓库中启用一次钩子：git config core.hooksPath .githooks。

仅限 macOS 的功能：

• count_occurrences 中的屏幕文本匹配（text=）通过 pyobjc 使用 Apple Vision。
• bench-v1 测试框架使用 sandbox-exec；部分测试和生成器会使用 say。需要的工具缺失时，相关测试会自动跳过。

核心工具可在 Linux 上运行。在 Debian 12（x86_64、ffmpeg 5.1）上全新安装 0.3.1 后，探测、帧和语音转文本检查均通过；其他发行版和 CPU 尚未经过测试。

可选：更快、更准确的语音识别（whisper.cpp turbo）

默认情况下，transcribe 在 CPU 上使用 faster-whisper（tiny、base 或 small；首次使用时会下载权重）。在 Apple 芯片上，使用 large-v3-turbo 模型的 whisper.cpp 速度快得多，也更准确：

brew install whisper-cpp
mkdir -p ~/.cache/whisper.cpp
curl -L -o ~/.cache/whisper.cpp/ggml-large-v3-turbo-q5_0.bin \
  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo-q5_0.bin

如果模型存放在其他位置，请设置 AGENTIC_VIDEO_WHISPER_CPP_MODEL。安装后，turbo 会成为默认模型。

可选：视觉搜索（CLIP）和屏幕文本

uv pip install --python .venv/bin/python -r requirements-visual.txt
.venv/bin/python -c 'from huggingface_hub import snapshot_download; snapshot_download(repo_id="openai/clip-vit-base-patch32", revision="3d74acf9a28c67741b2f4f2ea7635f0aaf6f0268", allow_patterns=["*.json", "*.txt", "pytorch_model.bin"])'

这会安装 PyTorch、Transformers，以及（在 macOS 上）Apple Vision 绑定，并下载约 605 MB 的 CLIP 权重。视觉搜索只会加载本地文件，绝不会调用付费 API。未安装这些依赖时，search_visual 和 build_visual_index 会返回说明配置方法的错误。

可选：云端工具（watch_for、label_sounds）

watch_for 和 label_sounds 会将视频帧或音频发送到 Cloudflare Workers AI（Clef 模型）。这些工具是可选的：其他工具绝不会调用 Cloudflare，但默认关闭的影子转录试用功能除外（见下方的试用开关）。请勿将它们用于你需要保密的录音。请在服务的环境中设置以下变量：

• CLOUDFLARE_ACCOUNT_ID：你的账户 ID。
• CLOUDFLARE_API_TOKEN：具有 Workers AI 访问权限的令牌。或者，将 AGENTIC_VIDEO_CF_TOKEN_COMMAND 设置为一个命令，该命令最后输出的行是令牌（例如 wrangler auth token）；每个进程最多每 50 分钟运行一次该命令，每个分离的影子子进程都会保留自己的令牌缓存。

未设置这些变量时，两个工具都会报错并指出缺少的内容，且不会发送任何数据。

试用开关（仅维护者使用）：将 AGENTIC_VIDEO_SHADOW_CF_ASR 设置为此机器的主机名后，每次本地转录完成后都会将音频发送到 CLOUDFLARE，以便在日志中与本地结果进行比较。用户的转录文本不会改变。除非该变量的值与机器名一致，否则此功能处于关闭状态；14 天或使用 200 次后会自动停止。详情：docs/features/shadow-cf-asr.md。

可选：混合式转录文本搜索（macOS，EmbeddingGemma 2）

search_transcript 会先返回精确的关键词匹配结果，再返回语义匹配的片段。语义搜索部分需要 EmbeddingGemma 2 Core ML 模型文件夹，以及安装了 coremltools、tokenizers 和 numpy 的解释器。请将 AGENTIC_VIDEO_EG2_DIR 设置为模型文件夹，将 AGENTIC_VIDEO_EG2_PYTHON 设置为该解释器，然后重启服务。未设置这些变量时，该工具只会返回关键词匹配结果，并通过 note 说明原因。详情：docs/features/transcribe.md。

运行 MCP 服务

该服务通过 stdio 使用 MCP，每行一条 JSON 消息：

.venv/bin/python -m src.executor.mcp_server

要将其添加到 MCP 客户端（Claude Code、Claude Desktop、Cursor 等），请使用虚拟环境中的 Python，并将仓库路径加入 PYTHONPATH，这样无论从哪个文件夹启动，都能运行该服务：

{
  "mcpServers": {
    "agentic-video": {
      "command": "/absolute/path/to/agentic-video/.venv/bin/python",
      "args": ["-m", "src.executor.mcp_server"],
      "env": { "PYTHONPATH": "/absolute/path/to/agentic-video" }
    }
  }
}

请为工具提供视频的绝对路径。结果会缓存在 ~/.cache/agentic-video 下（使用 AGENTIC_VIDEO_CACHE_DIR 更改缓存位置）。

将其添加到 Claude Code（一条命令）

在克隆的文件夹中运行此命令（它会使用当前文件夹的路径）。-s user 会让该工具在每个项目中都可用，而不仅限于此文件夹：

claude mcp add -s user agentic-video -e PYTHONPATH="$PWD" -- "$PWD/.venv/bin/python" -m src.executor.mcp_server

默认情况下，结果会保持较小，适合 Claude Code 使用：图像会保存为文件，结果中会提供其 file_path（Agent 会打开该文件）。frame_at 和 spectrogram_window 会写入 PNG；联系表和帧网格（contact_sheet、review_video、overview_chunks、inspect_window、inspect_windows、inspect_moments）会写入 JPEG；较长的 transcribe 结果会列出转录文本的开头部分，并提供包含其余内容的 transcript_path 文件。能够直接渲染结果中图像的客户端可以添加 -e AGENTIC_VIDEO_INLINE_IMAGES=1；此时结果会包含 base64 图像，大小可能超过 1 MB。变更说明：早期版本默认会包含 base64 图像；如果你依赖此行为，请设置 AGENTIC_VIDEO_INLINE_IMAGES=1 以恢复该行为。

告诉你的 Agent 使用它（粘贴到 AGENTS.md 或 CLAUDE.md 中）

始终加载的说明比寄希望于 Agent 找到该工具更有效：

## Video files (agentic-video MCP)
You cannot watch video. For any .mp4/.mov/.webm question, use the agentic-video MCP tools; never guess from the filename.
- First look: `review_video` with an absolute path. It returns metadata, a contact sheet, cuts, near-black stretches and loudness. Open the JPEG at `file_path` to see the frames.
- Spoken words: `search_transcript` (when is X said) or `transcribe`. Do this before looking at frames.
- A short range: `inspect_window` (start_sec, end_sec). Counting: `count_occurrences`. Sync and audio faults: `sync_check`, `loudness_timeline`.
- Sampling can miss brief events and a missing hit is not proof. Quote the burned-in timestamps. Full guide: AGENTS.md in the agentic-video repo.

五行示例

在仓库文件夹中：进行握手、获取视频元数据，并生成 6 帧联系表（其 JPEG 路径位于 file_path 中）：

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"probe_video","arguments":{"source":"fixtures/reference_videos/flower.mp4"}}}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"contact_sheet","arguments":{"source":"fixtures/reference_videos/flower.mp4","samples":6,"cols":3}}}' \
  | .venv/bin/python -m src.executor.mcp_server

用 Python 实现相同操作：

from src.retrieval.engine import AgenticVideoEngine

engine = AgenticVideoEngine("fixtures/reference_videos/flower.mp4")
print(engine.metadata.duration_sec)                  # 5.005
print(engine.overview(samples=6, cols=3).file_path)  # contact sheet JPEG

目前的结果

以下是作者自己进行的小规模测试，并非独立基准测试。原始运行结果不属于此仓库。

• **植入的故障：**在包含 20 个故意植入故障的宣传视频中，检查器（python -m src.loop check）发现了 20 个中的 14 个，并产生 2 次误报。Gemini 的 Agentic 视频模式发现了 20 个中的 4 个。
• **bench-v1（benchmarks/bench_v1）：**在作者的小型基准测试中，使用这些工具的 Claude 在计数、查找片段和长视频搜索方面胜过了 Gemini 的 Agentic 视频模式。
• **LVBench（公开的长视频基准测试）：**得分约为 86%。Gemini 公布的得分为 88.6%，因此在这项测试中并未胜过 Gemini。

总体而言，它并未胜过 Gemini 的视频理解能力。

限制

• **图像以文件形式返回。**图像工具会返回 file_path，而非 MCP 图像内容块；structuredContent 中的 base64 副本默认关闭（设置 AGENTIC_VIDEO_INLINE_IMAGES=1 可将其包含在内）。许多客户端只会向 Agent 显示 JSON 文本，因此 Agent 必须自行打开 file_path 中的图像（例如使用其文件读取工具）。
• **抽样可能会漏掉内容。**联系表和视觉搜索会查看抽样帧；可能会漏掉采样间隔内发生的短暂内容，未发现命中也不能证明内容不存在。视觉搜索会在 CPU 上运行 CLIP，处理长视频时速度较慢。
• **转录文本可能会编造语句。**Whisper（尤其是 turbo）可能会在音乐或静音片段中编造语句。连续重复 3 次或更多次的语句会标记为 suspect；单条编造语句则不会。
• **可能会漏掉剪切点。**两张相似图片之间的硬切，如果得分低于 0.25 阈值，就可能被漏掉。
• **计数和同步采用启发式方法，**这些方法是根据作者的视频调优的。请将其输出视为需要核实的证据，而非事实依据。
• 修复循环需要额外工具。python -m src.loop run 会调用 Codex CLI 作为修复器（默认模型梯队见 src/loop.py）。可选的 --judge jev 需要环境中设置 TYPESAFE_API_KEY 或 OPENROUTER_API_KEY。
• **bench-v1 需要账户。**运行它需要 Codex CLI、环境中的 GEMINI_API_KEY、Node.js 和 macOS sandbox-exec；请参阅 benchmarks/bench_v1/README.md。
• **没有稳定的 API。**工具名称和输出可能会随提交而变化。

仓库布局

• src/：库（media/、transcript/、retrieval/、core/）、MCP 服务（executor/mcp_server.py）、检查器（loop.py）和工具架构（adapters/）。
• tests/：pytest 测试套件。evals/adversarial_runner.py 包含由 tests/test_adversarial_failures.py 运行的故障注入检查。
• benchmarks/bench_v1/：包含三个参赛者的盲测基准测试框架。其数据和答案在仓库之外。
• benchmarks/dev/count_dev/：用于计数工具的小型开发数据集。
• scripts/generate_synthetic_benchmark.py：重新生成合成测试视频。
• fixtures/：小型测试视频（参见“媒体鸣谢”）。
• docs/：架构说明和各功能页面。

媒体鸣谢

• fixtures/reference_videos/sample_10s.mp4：Big Buck Bunny（Sunflower 版本）的一段 10 秒无音频片段。版权所有（c）2008 Blender Foundation，www.bigbuckbunny.org / peach.blender.org；Sunflower 版本由 Janus Bager Kristensen 于 2013 年制作（bbb3d.renderfarming.net）。采用 Creative Commons Attribution 3.0 许可。
• fixtures/reference_videos/flower.mp4：来自 MDN Web Docs 的示例视频，以 CC0（公有领域）发布。
• fixtures/synthetic_bench_60s.mp4 及其 .srt、.vtt 文件和 fixtures/synthetic_ground_truth.json：由此仓库的 scripts/generate_synthetic_benchmark.py 生成。与代码采用相同的许可证。

许可证

MIT。请参阅 LICENSE。