核心组件解读：claude-video的watch.py入口点全解

核心组件解读claude-video的watch.py入口点全解【免费下载链接】claude-videoGive Claude the ability to watch any video. /watch downloads, extracts frames, transcribes, hands it all to Claude.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-videoclaude-video是一个让 Claude 学会看视频的技能插件输入/watch加一个链接或本地文件路径Claude 就会自动下载视频、抽取帧画面、生成带时间戳的逐字稿最终基于亲眼看到 亲耳听到的内容回答你的问题。整条流水线的大脑就是入口脚本 scripts/watch.py——本文带你逐段读懂它。1️⃣ claude-video 能做什么先花 30 秒建立整体印象。你只需要在 Claude Code 里这样用/watch https://youtu.be/xxxx 视频第 30 秒发生了什么 /watch ~/Movies/录屏.mp4 界面在哪里开始报错背后发生的事可以概括成一条流水线下载视频 → 抽取帧画面 → 提取字幕/音频转写 → 输出 Markdown 报告 → Claude 逐帧阅读并作答其中大脑就是watch.py其余环节由四个小模块分工完成。2️⃣ 全局鸟瞰一个总指挥与四个执行者打开 scripts/watch.py你会发现它自身不实现任何具体功能而是在文件头部一次性引入四个搭档watch.py 第 18-21 行模块文件一句话职责依赖的外部工具scripts/download.py下载视频并顺带抓字幕yt-dlpscripts/frames.py探测元数据、按自动帧率抽帧ffmpeg/ffprobescripts/transcribe.py解析字幕文件VTT并去重无scripts/whisper.py无字幕时调用 Groq/OpenAI 语音转写仅 Python 标准库watch.py的全部业务逻辑集中在一个main()函数里watch.py 第 24-226 行按固定顺序调度上面四个模块最后把结果汇总成一份 Markdown 报告打印到标准输出——这份报告就是 Claude 的观看笔记。3️⃣ 入口点逐步拆解一次 /watch 的完整旅程第一步命令行参数解析菜单main()用argparse定义了一个精简的菜单watch.py 第 25-47 行新手最常打交道的就这几项参数作用新手建议source必填视频 URL 或本地文件路径直接粘贴--start/--end只分析某一段支持SS、MM:SS、HH:MM:SS长视频强烈建议用--max-frames帧数上限默认 80硬顶 100想省 token 就调低--resolution帧宽度默认 512px要看屏幕上的文字再调 1024--no-whisper完全禁用语音转写只出画面无 API Key 时可用这里有一个值得注意的小细节用户传的--max-frames会被强制压到 100 以内watch.py 第 49 行因为每一帧都是一张图帧数直接决定 token 开销——这是贯穿全脚本的成本意识。第二步准备工作目录脚本优先使用--out-dir指定的目录否则用tempfile.mkdtemp自动生成一个watch-前缀的临时目录watch.py 第 51-56 行。下载的视频、抽出的帧、转写的音频全部放在这里用完即弃不污染你的文件。第三步判断来源——下载还是直接读download.py里的 is_url() 只做一个判断是不是http/https链接是链接→ 交给yt-dlp下载同时尝试抓取英文 VTT 字幕手动字幕优先自动字幕兜底见 download.py 第 69-85 行。它还贴心地处理了字幕下载失败但视频成功的边界情况——以视频文件存在为成功标准。是本地文件→ 跳过下载校验扩展名.mp4/.mov/.mkv等后原地使用。第四步自动帧率——新手最该理解的省钱魔法抽帧前脚本先用ffprobe探测视频时长、分辨率、编码frames.py 第 58-91 行再调用 auto_fps() 计算该用多快的帧率。核心思路是按帧数预算而不是固定帧率视频时长默认帧预算体感≤ 30 秒约 30 帧密集几乎不遗漏30 秒 - 1 分钟约 40 帧依然密集1 - 3 分钟约 60 帧舒适3 - 10 分钟约 80 帧略稀疏 10 分钟100 帧会打印稀疏扫描警告如果你指定了--start/--end脚本自动切换到聚焦模式预算 auto_fps_focus()——同样的帧数花在你最关心的片段上画面密度更高。无论哪种模式帧率都被硬性限制在 MAX_FPS 2.0。第五步双通道字幕策略——免费优先付费兜底逐字稿是听的能力来源watch.py按优先级尝试两条通道原生字幕免费、即时如果下载时顺带拿到了 VTT 字幕就交给 parse_vtt() 解析成带起止时间的片段。它专门处理了 YouTube 自动字幕滚动重复的怪癖通过 _dedupe() 折叠重复行再用 filter_range() 把字幕裁剪到--start/--end指定的区间。Whisper 兜底需 API Key没有字幕时才触发。脚本先用ffmpeg提取一段单声道 16kHz 的小体积 mp3每分钟仅约 0.5MB再上传到 Groq优先便宜又快或 OpenAI 的 Whisper 接口全程只用 Python 标准库实现见 whisper.py 第 264-304 行。内置指数退避重试遇到限流会自动等待再试。两条通道都失败时脚本不会崩溃而是提示你运行 scripts/setup.py 配置环境然后继续以纯画面模式出报告——优雅降级这是它对新手最友好的设计。第六步输出 Markdown 报告交棒给 Claude一切就绪后main()打印一份结构固定的报告watch.py 第 148-224 行头部信息标题、UP 主、时长、分辨率、帧数、字幕来源captions还是whisper (groq)Frames 清单每张帧的绝对路径 tMM:SS时间戳按时间排序并附一句指令——请用 Read 工具逐张读取Transcript 全文带[MM:SS]时间戳可与画面逐句对齐长视频警告超过 10 分钟且未指定区间时主动建议用--start/--end重跑聚焦段落。报告末尾还会打印工作目录路径方便 Claude 在追问结束后清理。到这里watch.py的活干完了——接下来 Claude 会把所有帧并行读成图片结合字幕作答。4️⃣ 三个值得新手学习的工程设计薄入口 厚模块watch.py只负责编排下载、抽帧、字幕、转写各自独立成文件甚至可以单独运行调试每个模块末尾都自带__main__入口。想改帧策略只动frames.py想换转写服务商只动whisper.py。处处有预算意识100 帧硬顶、2fps 硬顶、512px 默认宽度、长视频主动警告——因为图像 token 是大头成本意识直接写进了默认值。失败不致命缺依赖会提示安装命令缺 Key 会提示配置路径字幕解析失败会降级到 WhisperWhisper 失败则退回纯画面。新手遇到任何报错脚本本身就会告诉你下一步做什么。5️⃣ 上手实操三种典型用法场景命令示例要点概括长视频/watch 长视频链接 summarize this超 10 分钟会提示稀疏可加区间重跑追问具体时刻/watch 链接 --start 2:15 --end 2:45 发生了什么聚焦模式帧更密、更省钱分析本地录屏/watch 录屏.mp4 哪里报错了本地文件免下载无字幕时可配 Whisper首次运行时Claude 会先跑一次环境自检 scripts/setup.pymacOS 上自动安装ffmpeg和yt-dlpLinux/Windows 会打印精确的安装命令之后每次调用都只剩不到 100ms 的静默检查不影响速度。6️⃣ 相关文件速查入口脚本scripts/watch.py下载封装scripts/download.py抽帧与帧率策略scripts/frames.py字幕解析scripts/transcribe.pyWhisper 客户端scripts/whisper.py环境自检与安装scripts/setup.py技能契约Claude 如何调用脚本SKILL.md命令定义commands/watch.md会话启动状态钩子hooks/hooks.json7️⃣ 总结watch.py用最少的代码完成了一次漂亮的编排200 行入口 四个各司其职的模块把下载 → 抽帧 → 转写 → 汇报串成一条对 token 成本精打细算、对缺失依赖层层降级的流水线。读懂它你不仅理解了 claude-video 的运转原理也能学到一套写AI 技能脚本的实用范式——让 AI 看视频先给它一份结构清晰的观看笔记。【免费下载链接】claude-videoGive Claude the ability to watch any video. /watch downloads, extracts frames, transcribes, hands it all to Claude.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-video创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考