Watch Video

watch-video

让 Claude（或任何 MCP 客户端）观看视频。为其提供本地文件或 URL（YouTube 及 yt-dlp 支持的 1,500 多个其他网站），即可获得带时间戳的转录文本和若干通过场景选择的关键帧；只有在需要时，才会进一步查看精确帧。无需云端转录，无需 API 密钥。

> Watch https://www.youtube.com/watch?v=jNQXAC9IVRw and tell me what he says about the elephants.

$ video-cli overview https://www.youtube.com/watch?v=jNQXAC9IVRw --max-frames 8
# Me at the zoo
duration: 00:19
transcript: platform-subs:en, language=en, 6 segments, took 0.4s
keyframes: 3 scene-selected at 00:00, 00:05, 00:11
total time: 6.7s

## Transcript
[00:01] All right, so here we are, in front of the elephants
[00:05] the cool thing about these guys is that they have really... really really long trunks and that's cool
[00:16] and that's pretty much all there is to say
IMAGE: ~/.cache/video_mcp/Youtube_jNQXAC9IVRw/sheets_8/sheet_01.jpg

Claude: He stands in front of the elephants (00:01) and says the cool thing about them is
their really long trunks (00:05). That is the whole video (00:16).

为什么选择它

	watch-video	云端视频 API（例如 Gemini）	仅转录文本的工具
能看到屏幕内容（代码、幻灯片、图表、UI）	能：关键帧、高分辨率帧、OCR	能	不能
在本地运行，不上传任何内容	能	不能：视频会发送给服务提供方	视情况而定
API 密钥或账号	无需	必需，按次计费	视情况而定
无字幕的视频	本地 Parakeet / Whisper	支持	通常无法处理
视觉分析的 token 成本	每张联系表约 20 帧（成本约等于 1.5 张完整图像）	按视频时长计费	无（不含视觉内容）
私人录制内容（会议、错误复现）	安全：绝不离开本机	会上传	视情况而定

它包含两个部分：

• video MCP 服务，提供七种工具（见下文）。
• watch-video 技能，教 Claude 采用低成本优先的工作流：先概览，再查看帧，最后查看时间范围。

工作原理

步骤	处理方式
转录文本	如果视频有平台字幕，则使用字幕（数秒即可）；否则使用 Parakeet TDT 0.6B v3（int8、CPU、25 种欧洲语言）；其他语言则使用 faster-whisper large-v3-turbo（GPU，或 language="auto"）。
关键帧	仅以缩略图尺寸解码关键帧，剔除重复帧和静态幻灯片，然后填补最大的时间间隔。选取方式会根据视频画面的变化程度调整（屏幕录制与动作场景有所不同）。
联系表	将带标签的帧平铺成网格：约 20 帧的 token 成本相当于 1.5 张完整帧。自动裁掉黑边。
深入查看	get_frames 会跳转到精确时间戳，并以 1280 px 分辨率读取（便于查看代码和图表）。对于 URL，它会在视频流中跳转，无需下载整个视频。

所有内容都会缓存在 ~/.cache/video_mcp 中，因此重复调用可即时完成。

在中端 CPU（i5-11400，无 GPU）上的测量结果：35.7 分钟的本地视频，约 2.6 分钟即可完成概览；带字幕的 YouTube 视频约需 7 秒；深入查看一帧约需 0.5 秒。

安装

要求：Python 3.10+，并将 ffmpeg（包括 ffprobe）添加到 PATH 中。

Claude Code：一条命令（插件）

同时安装 MCP 服务和技能。需要使用 uv 来运行 uvx。

/plugin marketplace add marwanm7moud/watch-video
/plugin install watch-video@watch-video

任何 Agent：软件包、服务、技能

pipx install watch-video-mcp          # or: uv tool install watch-video-mcp / pip install watch-video-mcp
# optional extras: Whisper (non-European languages / GPU) and OCR (on-screen text as text)
pipx install "watch-video-mcp[whisper,ocr]"
# latest from GitHub instead of PyPI:
pip install git+https://github.com/marwanm7moud/watch-video

无需安装即可试用 CLI：uvx --from watch-video-mcp video-cli hw。

使用 winget install Gyan.FFmpeg（Windows）、brew install ffmpeg（macOS）或 sudo apt install ffmpeg（Linux）安装 ffmpeg。首次转录时会下载 Parakeet 模型（约 650 MB）。

注册 MCP 服务

Claude Code：

claude mcp add video --scope user -- video-mcp

Claude Desktop（claude_desktop_config.json）或任何其他 MCP 客户端：

{ "mcpServers": { "video": { "command": "video-mcp" } } }

如果 video-mcp 不在 PATH 中，请使用可执行文件的完整路径，或运行 python -m video_mcp.server。

安装技能

无论是否安装 MCP 服务，该技能都能使用：它会回退到 video-cli，并在首次使用时安装它。 复制技能文件夹，让你的 Agent 知道何时以及如何使用这些工具：

# macOS / Linux
mkdir -p ~/.claude/skills && cp -r skills/watch-video ~/.claude/skills/
# Windows (PowerShell)
Copy-Item -Recurse skills\watch-video $HOME\.claude\skills\

然后向 Claude 提问："观看 https://youtu.be/... 并总结内容"，或 "他们在哪个时间点解释了止损？当时图表显示了什么？"

工具

工具	用途
video_overview(source, max_frames=40, ocr=False)	从这里开始：元数据、章节、完整转录文本、联系表。ocr=True 会添加屏幕上的文字。
get_frames(source, timestamps, hi_res=True)	获取精确帧（"12:30"、"1:02:05" 或秒数），最多 20 帧。
scan_range(source, start, end, count=12)	在一张表中均匀采样帧，以跟踪动作或演示。
find_cuts(source, start, end, threshold=0.2)	硬切（镜头或屏幕变化）以及每分钟的切换次数，用于评估节奏。
get_transcript(source, start, end)	转录文本片段。
search_transcript(source, query)	返回包含任意指定词语的带时间戳结果，优先精确匹配短语；如果使用了 ocr=True 概览，也会搜索屏幕上的文字。
check_hardware()	检测到的工具、GPU 以及正在使用的转录配置。

命令行

无需 MCP 也可以执行相同的操作：

video-cli overview video.mp4 --max-frames 16
video-cli overview demo.mp4 --ocr          # also read code/slides on screen
video-cli frames https://youtu.be/... 12:30 13:05
video-cli range video.mp4 10:00 10:30 --count 12
video-cli cuts ad.mp4                       # hard cuts + cuts per minute
video-cli search video.mp4 "stop loss"
video-cli hw

配置

变量	默认值	作用
VIDEO_MCP_CACHE	~/.cache/video_mcp	缓存目录（删除即可释放空间）。
VIDEO_MCP_LANG	en	默认转录语言；auto 会使用 Whisper 自动检测语言。
VIDEO_MCP_THREADS	4 (CPU)	CPU 转录使用的线程数。
VIDEO_MCP_AVX512	unset	设置为 1 可让 Whisper 使用 AVX-512（速度更快，但会持续带来极重的负载）。

在 CPU 上，服务以低于正常水平的优先级运行，一次只处理一个繁重任务，并限制 Whisper 使用 AVX2，因此长时间转录不会让桌面卡死。

限制

• 除非传入 language，否则默认使用英语。Parakeet 可在 CPU 上处理 25 种欧洲语言（language="de"、"fr"、"es" 等）。其他语言（阿拉伯语、中文、日语、印地语等）需要使用 Whisper，而 Whisper 在 CPU 上速度较慢。
• 这里只会采样部分帧，而非分析每一帧；转录文本可能会误听名称和术语。此技能会要求 Claude 引用时间戳，并通过高分辨率帧确认屏幕上的精确文字。
• 仅用于你有权访问和处理的视频；请遵守各网站的条款和版权规定。

开发

pip install -e ".[dev]"
ruff check .
pytest

许可证

MIT。请参阅 LICENSE。