7.0
热点
AI SCORE
编程提效2026-07-30 01:21
Claude Code 视频理解插件
GitHub Trending#Claude Code#多媒体#插件
Editor brief · 编辑速览
Claude Code 插件，自动下载、提取视频帧、转录，让 Claude 理解视频内容。扩展 AI 的多模态认知能力。
Claude Code（推荐——通过 marketplace 自动更新）：
/plugin marketplace add bradautomates/claude-video
/plugin install watch@claude-video
Codex、Cursor、Copilot、Gemini CLI 或其他 50+ Agent Skills 平台：
npx skills add bradautomates/claude-video -g
（-g 为全局安装，可在所有项目中使用。去掉 -g 则仅限当前项目。）
更多安装选项（claude.ai 网页版、手动安装）详见下方安装部分。
零配置开始——yt-dlp 和 ffmpeg 在首次运行时自动通过 brew 安装（macOS 上；Linux/Windows 打印确切命令）。绝大多数公开视频的字幕免费覆盖。仅在视频无字幕时才需要 Whisper API 密钥。
Claude 可以读网页、运行脚本、浏览代码仓库。但开箱即用，它做不了一件事：看视频。粘贴一个 YouTube 链接，它要么只能从标题猜测，要么拉取一份缺少屏幕内容 90% 的转录稿。
用 Claude Video 的 /watch，你粘贴一个 URL 或本地路径、提出一个问题，Claude 先获取字幕，仅下载需要的部分，提取帧（场景感知或高效的关键帧），拉取带时间戳的转录稿（免费字幕如可用，否则用 Whisper API），逐帧读取每一张图像。回答时，它已经看过视频、听过音频。
/watch https://youtu.be/dQw4w9WgXcQ what happens at the 30 second mark?
分析别人的内容。 /watch https://youtu.be/<viral-video> what hook did they open with? Claude 看前几帧、读开头转录、拆解结构。同样适用于广告素材、竞争对手产品发布、播客开场——任何"怎么做"和"做什么"一样重要的地方。
从视频诊断 bug。 有人给你发了一个屏幕录制，东西坏了。/watch bug-repro.mov what's going wrong? Claude 看录制、找问题出现的帧、描述屏幕上的内容，通常不用你打开文件就能抓住原因。
总结视频。 /watch https://youtu.be/<long-thing> summarize this 干显而易见的事——提取结构、关键时刻、实际所说所示。比看 2 倍速快得多。
剔除更新视频中的炒作。 /watch https://youtu.be/<launch-video> what's actually new 把"改变游戏规则"的功能发布精简到真正重要的几样，获得干货而不是十分钟的开场白和营销过度。
把播放列表变成笔记。 /watch https://youtu.be/<video> summarize this to a note 跨一个系列运行、归档每个视频摘要，一个频道或课程变成可搜索的笔记集，而不是你必须看完的数小时。
粘贴一个视频和一个问题。URL（任何 yt-dlp 支持的——YouTube、Loom、TikTok、X、Instagram，以及数百个其他平台）或本地路径（.mp4、.mov、.mkv、.webm）。
yt-dlp 先检查字幕。在转录稿详情度，带字幕的 URL 返回而无需下载视频。否则，或当 Whisper 需要音频时，仅下载这次运行需要的部分。
ffmpeg 在选定的详情度提取帧。efficient 仅解码关键帧（瞬间完成）；balanced/token-burner 倾向于场景变化帧，在产生不足时回落到时长感知的均匀采样器。JPEG 默认 512px 宽，高度限制在 1998px 以满足 Claude Read 兼容性。
转录稿来自两个地方之一。首先尝试：yt-dlp 从源拉取原生字幕（手动或自动生成）。免费、即时、准确度不错。回退方案：提取单声道 16 kHz 64 kbps mp3 音频片段（约 480 kB/分）并发送至 Whisper——Groq 的 whisper-large-v3（首选——更便宜更快）或 OpenAI 的 whisper-1。
帧 + 转录稿送给 Claude。脚本打印带 t=MM:SS 标记的帧路径和带时间戳的转录稿。Claude 并行读每一帧——JPEG 直接作为图像在其上下文中渲染。
Claude 基于屏幕上和音频中的实际内容回答。不是"根据描述"或"按标题所说"。它看过帧。它听过转录。它的回答方式如同看过视频的人。
清理。脚本在最后打印一个工作目录。如果你不追问，Claude 移除它。
Token 成本由帧主导。每一帧都是一张图像；图像 token 快速累积。脚本的自动 fps 逻辑存在是为了你不会在一个 30 分钟视频的稀疏扫描上炸掉上下文预算，而这会更好地回答一个聚焦的 30 秒窗口。
当用户命名时刻（"大约 2:30"、"最后 30 秒"、"从 0:45 到 1:00"）时，传递 --start / --end。聚焦模式获得更密集的每秒预算，上限 2 fps。远比稀疏扫描整个视频有用。
帧选择——关键帧（efficient）、场景变化检测（balanced/token-burner）或它回落到的均匀采样器——仍可能表面近乎相同的帧：一个屏幕录制保持一张幻灯片 90 秒会产生十几张，每一张都计为一张单独的图像。一个去重过程在帧到达 Claude 前删除它们。默认在每个帧模式上运行（--no-dedup 关闭它）：
一次 ffmpeg 调用将每个提取的 JPEG 缩放到 16×16 灰度缩略图。之后全是纯标准库 Python——无图像库。
对每一帧，计算与保留的最后一帧的平均绝对差（平均每像素亮度变化，0–255 刻度）。
如果差异在阈值 2.0 或以下，帧是近重复且被删除。否则被保留并成为新参考。
帧预算上限在去重后适用，所以预算花在不同的帧上。
与最后保留的帧比较（不是前一帧）捕捉从未触发逐帧阈值的缓慢淡入。阈值刻意很低并测量绝对亮度而非结构，所以单行代码差异、终端滚动一行、或两张不同颜色的平面幻灯片都幸存。
帧行报告折叠内容，例如 6 selected from 14 candidates (… 8 near-duplicates dropped …)。在始终运动的镜头上什么都不被删除，你付出与之前一样的代价。
--detail 拨号在速度和 token 成本与视觉保真度间权衡。下面的数字来自针对 49:08 YouTube 视频（1280×720，英文自动字幕）的实际运行——一个长的、大多静态的屏幕录制，最能压力测试上限的情况。提取时间是本地 CPU 针对预下载副本；一次性下载约 37 秒 / 76 MB，由三种帧模式共享。
图像 token 使用 Anthropic 的 (width × height) / 750——在默认 512px 宽度，这些 720p 帧是 512×288，约 197 token/帧；--resolution 1024 大约 4 倍。转录稿在每个带字幕模式和长视频上表面，通常是较大的成本。
一条贯穿帧模式的采样规则。每个跨完整范围检测所有候选，然后均匀采样（首尾总保留）降到其上限。模式仅在候选源（关键帧 vs 场景切割）和上限上不同，从不在覆盖如何分散——所以最后帧始终在末尾，不在中途。
efficient 是速度级（约 0.5 秒）——仅重构关键帧，约 40 倍快于场景模式，后者解码每一帧以找切割。在低运动镜头上它也能返回比 balanced 更多帧（关键帧比场景切割多）；"efficient"意思是快速提取，不是更少帧。
token-burner 仅在超过上限时与 balanced 偏离。这个片段有 116 个切割，所以 balanced 采样 100，token-burner 保留全部 116。在有数百个切割的高运动视频上，token-burner 保留一切（并触发 >250 帧 token 警告）而 balanced 精简到 100。
从冷 URL 端到端，转录稿模式远是最便宜的；帧模式在上面加共享的约 37 秒下载加提取时间。
/plugin marketplace add bradautomates/claude-video
/plugin install watch@claude-video
稍后用 /plugin update watch@claude-video 更新。
Agent Skills CLI 将技能安装到它检测到的任何 agent 中：
npx skills add bradautomates/claude-video -g
-g 为全局安装到用户（~/.codex/skills、~/.cursor/skills 等）；去掉它则安装到当前项目。有用的标志：
-a, --agent <names…> — 目标特定平台，例如 -a codex -a cursor
-l, --list — 列出此仓库中的技能而不安装
--copy — 复制文件而非符号链接（对于不支持符号链接的文件系统）
CLI 从 skills/watch/SKILL.md 发现技能并复制整个文件夹——SKILL.md 加其 scripts/ 运行时——作为自包含单元。SKILL.md 相对于它被安装的任何地方解析自身脚本，所以在每个平台上工作一致。
稍后用 npx skills update watch -g 更新。
从最新发布下载 watch.skill。
进入设置 → 能力 → 技能。
点击 + 并放入文件。
首先启用"代码执行和文件创建"在能力下——技能调用 ffmpeg 和 yt-dlp，所以没有它不会运行。
克隆仓库并将自包含的技能文件夹符号链接到你的平台技能目录——符号链接在编辑时保持安装同步到工作树：
git clone https://github.com/bradautomates/claude-video.git
ln -s "$(pwd)/claude-video/skills/watch" ~/.claude/skills/watch # or ~/.codex/skills/watch
对于 claude.ai，从源构建 .skill 包：bash skills/watch/scripts/build-skill.sh 产生 dist/watch.skill。
第一次 /watch 调用时，技能运行 scripts/setup.py --check。如果 ffmpeg / yt-dlp 不在你的 PATH，或未设置 Whisper API 密钥，它引导你修复：
macOS — 自动运行 brew install ffmpeg yt-dlp。
Linux — 打印确切的 apt / dnf / pipx 命令。
Windows — 打印 winget / pip 命令。
API 密钥 — 脚手架 ~/.config/watch/.env（模式 0600），包含 GROQ_API_KEY（首选）和 OPENAI_API_KEY 的注释占位符。
设置后，预检沉默，/watch 就工作。检查是子 100ms 查找，所以不会在后续运行中拖慢你。
字幕免费覆盖绝大多数公开视频。Whisper 回退仅在视频真正没有字幕轨道时启动——通常本地文件、TikTok、某些 Vimeo 和偶发的无字幕 YouTube 上传。
/watch https://youtu.be/dQw4w9WgXcQ what happens at the 30 second mark?
/watch https://www.tiktok.com/@user/video/123 summarize this
/watch ~/Movies/screen-recording.mp4 when does the UI break?
/watch https://vimeo.com/123 what tools does she mention?
聚焦于特定部分——更密集的帧预算、更低的 token 成本：
/watch https://youtu.be/abc --start 2:15 --end 2:45
/watch video.mp4 --start 50 --end 60
/watch "$URL" --start 1:12:00 # from 1h12m to end
其他旋钮（传递给 scripts/watch.py）：
--detail transcript|efficient|balanced|token-burner — 保真度/速度拨号。transcript 跳过帧（仅转录稿）；efficient 使用快速关键帧（上限 50）；balanced 使用场景感知帧（上限 100）；token-burner 是场景感知且无上限。
--timestamps T1,T2,… — 在每个绝对时间戳抓一帧（SS/MM:SS/HH:MM:SS）。Claude 先读转录稿，然后目标演示者标记的时刻（"看这里"、"如你所见"）。加在详情帧之上（针对上限保留）；窗口外的提示在聚焦模式下被删除；带 --detail transcript 这些成为仅有的帧。
--max-frames N — 降低帧上限以获得更紧凑的 token 预算。
--resolution W — 当 Claude 需要读屏幕文本（幻灯片、终端、代码）时，将帧宽提升到 1024 px。
--fps F — 覆盖自动 fps 计算（仍限 2 fps）。
--whisper groq|openai — 强制特定 Whisper 后端。
--no-whisper — 完全禁用转录；仅帧。
--no-dedup — 保留近重复帧。默认帧增量过程删除视觉上近乎相同于前面的帧（保持幻灯片、静态屏幕录制、暂停视频），所以帧预算花在不同内容上；此标志关闭它。
--out-dir DIR — 将工作文件保留在特定位置（默认：自动生成 tmp 目录）。
长视频准确度取决于详情模式。在有上限的模式（efficient、默认 balanced）上，覆盖在超过约 10 分钟后精简——帧上限分散在整个片段上，所以脚本打印"稀疏扫描"警告，你最好用 --start/--end 重新聚焦运行。token-burner 提升上限并跨完整视频保留每个场景变化帧，所以它在更长片段上保持完整，成本是更多图像 token。10 分钟标记是有上限模式的指引，不是硬性上限。
详情是一个拨号。默认值是 balanced：场景感知帧、2 fps 最大、100 帧上限。对快速 50 帧关键帧过程使用 --detail efficient，或对无上限场景候选使用 --detail token-burner。在 ~/.config/watch/.env 中设置 WATCH_DETAIL 以改变默认值。
.
├── skills/watch/ # self-contained skill — copied as a unit by every installer
│ ├── SKILL.md # skill contract — the source of truth across all surfaces
│ └── scripts/
│ ├── watch.py # entry point — orchestrates download → frames → transcript
│ ├── download.py # yt-dlp wrapper
│ ├── frames.py # ffmpeg frame extraction + auto-fps logic
│ ├── transcribe.py # VTT parsing + dedupe + Whisper orchestration
│ ├── whisper.py # Groq / OpenAI clients (pure stdlib)
│ ├── config.py # shared config (~/.config/watch/.env)
│ ├── setup.py # preflight + installer
│ └── build-skill.sh # build dist/watch.skill for claude.ai upload (dev-only)
├── hooks/ # SessionStart status hook (Claude Code only)
├── .claude-plugin/ # plugin.json + marketplace.json (Claude Code)
├── .codex-plugin/ # plugin.json — Codex/agents manifest ("skills": "./skills/")
├── .agents/plugins/ # marketplace.json — Agent Skills marketplace listing
├── AGENTS.md → CLAUDE.md # generic-agent entry point
├── tests/ # pytest suite (ffmpeg-synthesized clips, no network)
└── .github/workflows/ # release.yml — auto-builds watch.skill on tag push
# 运行测试套件（stdlib + pytest；帧测试需要 ffmpeg）：
python3 -m pytest -q
# 构建 claude.ai 上传包：
bash skills/watch/scripts/build-skill.sh # → dist/watch.skill
发布：tag vX.Y.Z、push tag。工作流构建 dist/watch.skill 并附到 GitHub 发布。保持版本在 skills/watch/SKILL.md、.claude-plugin/plugin.json 和 .codex-plugin/plugin.json 间同步。
详见 CHANGELOG.md 以了解版本历史。
构建在 yt-dlp、ffmpeg 和 Claude 的多模态 Read 工具之上。Whisper 转录通过 Groq 或 OpenAI。
由 Brad Bonanno 构建——我在 YouTube 频道（@bradbonanno）制作关于用 AI 构建的内容，在 Solaris Automation 为企业构建 AI 操作系统。如果 /watch 救你脱离拖过视频，在频道上打个招呼吧。
github.com/bradautomates/claude-video · @bradbonanno · Solaris Automation · LICENSE