bradautomates/claude-video

让 Claude 具备”观看视频”能力的 Agent Skill（/watch）。下载/抽帧/转录一条龙，把视频拆成帧图 + 时间戳转录文本喂给 Claude 的 Read，MIT 协议，5.2k stars。

核心问题

Claude 能读网页、跑脚本、翻仓库，但不能”看视频”——用户丢一个 YouTube 链接，Claude 只能猜标题或拉一份缺失大半画面信息的字幕。

/watch 的做法：拿到 URL 或本地路径后，先抓字幕，再按需下载，用 ffmpeg 抽取场景感知帧（或 efficient 模式下的快速关键帧），拉取带时间戳的转录文本（有字幕用字幕，没字幕上 Whisper），最后把每一帧当图片喂给 Claude 的 Read 工具。回答时 Claude 是”真看过+真听过”，不是”根据标题猜”。

核心机制

字幕优先：yt-dlp 先查原生字幕（人工或自动生成），免费、即时、大致准确
帧抽取：ffmpeg 按 --detail 档位抽帧——efficient 只解关键帧（~0.5s，超快）；balanced/token-burner 走场景变化检测，不足时回退均匀采样
Whisper 兜底：没字幕时抽 mono 16kHz 音轨（~480KB/分钟）送 Groq whisper-large-v3（首选，更便宜更快）或 OpenAI whisper-1
帧去重：默认对每帧做 16×16 灰度缩略图对比，与上一张被保留的帧算平均绝对差值，低于阈值（2.0）判定近似重复丢弃——静态画面/暂停画面/长镖幕不会占满帧预算
帧预算自适应：按视频长度自动分配帧数（≤30s ~30帧密集覆盖，>10分钟固定100帧上限并提示”稀疏扫描”警告）

Detail 档位对比（实测 49 分钟视频）

模式	引擎	帧数	抽取耗时	覆盖范围	预估图片 token
`transcript`	仅字幕	0	~4.5s	全文本	0（≈26.6k 文本 token）
`efficient`	关键帧	50（上限）	~0.5s	全程	~9.8k
`balanced`	场景变化	100（上限）	~20.9s	全程	~19.7k
`token-burner`	场景变化	116（无上限）	~21.0s	全程	~22.8k

典型用法

/watch https://youtu.be/dQw4w9WgXcQ what happens at the 30 second mark?
/watch ~/Movies/screen-recording.mp4 when does the UI break?
/watch https://youtu.be/abc --start 2:15 --end 2:45   # 聚焦片段，帧预算更密

常见场景：分析爆款视频开场钩子、从录屏诊断 bug、视频摘要、剥离营销号的”炒作水分”、把播放列表批量转成笔记。

安装

# Claude Code（推荐，marketplace 自动更新）
/plugin marketplace add bradautomates/claude-video
/plugin install watch@claude-video

# Codex / Cursor / Copilot / Gemini CLI 等 50+ host
npx skills add bradautomates/claude-video -g

首次运行会自动检测 ffmpeg/yt-dlp（macOS 自动 brew install），并引导配置 Whisper API key（可选，无字幕视频才需要）。

项目结构

claude-video/
├── skills/watch/
│   ├── SKILL.md          # skill 契约，跨 host 唯一真源
│   └── scripts/
│       ├── watch.py       # 入口：下载→抽帧→转录 编排
│       ├── download.py    # yt-dlp 封装
│       ├── frames.py      # ffmpeg 抽帧 + auto-fps 逻辑
│       ├── transcribe.py  # VTT 解析 + 去重 + Whisper 编排
│       ├── whisper.py     # Groq / OpenAI 客户端（纯 stdlib）
│       └── setup.py       # 预检 + 安装引导
├── hooks/                # Claude Code SessionStart 状态 hook
└── tests/                # pytest（ffmpeg 合成测试片段，无网络依赖）

与相关工具的关系

依赖 yt-dlp（下载/字幕抓取）+ ffmpeg（抽帧转码）+ Claude 多模态 Read（图片理解）
Whisper 转录走 Groq 或 OpenAI API，非本地推理

资源

GitHub: https://github.com/bradautomates/claude-video
作者: Brad Bonanno（@bradbonanno）
License: MIT

zhaoweiguo 的知识库

目录