claude-video参数速查表：watch.py全部8个选项的完整参考

claude-video参数速查表：watch.py全部8个选项的完整参考

【免费下载链接】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

claude-video是一个让 Claude 拥有"看视频"能力的开源技能：粘贴视频链接或本地文件，/watch命令就会下载视频、自动抽帧、生成带时间戳的转录文本，让 Claude 真正"看过"视频后再回答问题。整套流程的核心是入口脚本 watch.py，它的行为全部由1 个必传参数 + 8 个可选参数控制。本文是这 8 个参数的完整速查表，每个选项的默认值、适用场景和常用组合一次讲清。

一、watch.py 8 个参数速查总表

先看全局，后文逐项展开：

💡 全部参数定义集中在 watch.py，官方用法速记见 SKILL.md 与 README.md。

命令行直接调用格式为python3 scripts/watch.py "<source>" [选项]。如果你还没有代码，手动安装只需：

git clone https://gitcode.com/GitHub_Trending/cl/claude-video ~/.claude/skills/watch

二、source：URL 与本地文件二选一

source是唯一的必传参数，两类输入都支持：

• URL：任何 yt-dlp 支持的站点，如 YouTube、TikTok、Vimeo、Loom、X 等，几百个平台开箱即用。
• 本地路径：.mp4、.mov、.mkv、.webm等格式，直接原地探测，不经过下载。

# URL：问一个具体问题 python3 scripts/watch.py "https://youtu.be/abc" "第30秒发生了什么？" # 本地文件：排查录屏中的问题 python3 scripts/watch.py ~/Movies/screen-recording.mp4 "界面在哪里出错了？"

⚠️ 注意：该技能不登录任何平台账号，私有/需登录的内容无法访问。

三、--start / --end：一键聚焦时间段，效果立竿见影

这是收益最高的两个参数。只传--start或--end时，区间自动补全到视频开头/结尾；两者传齐则精确截取。

时间格式支持SS、MM:SS、HH:MM:SS三种写法（解析逻辑见 frames.py），且会做合法性校验——--end小于--start、起点超出片长都会直接报错退出（watch.py）。

# 只看 2:15 到 2:45 的 30 秒 python3 scripts/watch.py "$URL" --start 2:15 --end 2:45 # 从 1 小时 12 分处看到结尾 python3 scripts/watch.py "$URL" --start 1:12:00

为什么强烈推荐？一旦进入聚焦模式，脚本会切换到更密的帧预算（frames.py）：

对比全片扫描（超过 10 分钟的视频仅稀疏取 100 帧），聚焦模式在同样 token 预算下细节密度高出一个量级。转录文本也会自动过滤到同一时间区间，帧时间戳保持为视频绝对时间，方便对齐。

四、--fps 与 --max-frames：控制 token 成本的两道闸门

claude-video 的 token 开销主要来自抽帧图片（约 80 帧 512px 就要消耗 5–8 万图像 token），这两个参数就是你的节流阀。

--max-frames N：压帧数上限

默认 80 帧，超过 100 会被强制压回 100（watch.py）：

python3 scripts/watch.py "$URL" --max-frames 40 # 更省 token

--fps F：覆盖自动抽帧率

不传时脚本按片长自动计算 fps（预算逻辑见 frames.py：≤30s 约 30 帧、1–3 分钟约 60 帧、3–10 分钟约 80 帧）。手动指定时会被钳制在 2 fps 硬顶内：

python3 scripts/watch.py "$URL" --start 2:15 --end 2:45 --fps 3 # 3 会被钳制为 2 fps，实际取满该区间最高密度

典型决策：全片粗扫用默认值 → 答案不够细 → 加--start/--end聚焦重跑（而不是盲目调高--fps，那样只会烧 token）。

五、--resolution：需要读屏上文字时升到 1024

默认每帧宽 512px，对"看动作、看画面"足够。但如果 Claude 需要读出屏幕上的文字（幻灯片、终端、代码截图），升到 1024px 是正确姿势：

python3 scripts/watch.py "$URL" --resolution 1024 "她提到的工具名字是什么？"

⚠️ 代价要心里有数：分辨率翻倍后单帧图像 token 约为原来的 4 倍，只在确实需要读字时使用。

六、--whisper 与 --no-whisper：转写的三档开关

转录文本有两条来源：yt-dlp 直接拉取平台原生字幕（免费、首选）；没有字幕时才走 Whisper API 转写。两个参数控制后者：

# 强制走 OpenAI 转写 python3 scripts/watch.py "$URL" --whisper openai # 本地纯看画面，不花一分钱转写费 python3 scripts/watch.py demo.mp4 --no-whisper

📌 两个 API 密钥都存放在~/.config/watch/.env，首次运行 setup.py 会自动生成模板（Groq 优先）。绝大多数公开视频都有免费字幕，Whisper 主要服务于本地文件和少数无字幕视频。

七、--out-dir：让工作文件留在指定位置

默认情况下，下载的视频、抽帧 JPEG、音频片段都写进一个自动生成的watch-前缀临时目录，用完即弃。加--out-dir可以指定固定位置，方便复查抽帧结果或留存转录：

python3 scripts/watch.py "$URL" --out-dir ~/watch-work

工作目录路径会在脚本结束时的报告末尾打印，追问完视频内容后记得清理。

八、3 个高频参数组合，直接抄作业

1. 长视频问局部（最常用）——超过 10 分钟的全片扫描会触发"稀疏警告"，聚焦重跑才是正解：

   python3 scripts/watch.py "$URL" --start 12:00 --end 13:30 "这段讲了什么？"

2. 读屏上文字——演示录屏、课件视频：

   python3 scripts/watch.py lecture.mp4 --resolution 1024 --start 5:00 --end 8:00

3. 省 token 粗扫——预算紧张时压低帧数：

   python3 scripts/watch.py "$URL" --max-frames 40

九、新手常见疑问快答

• Q：80 帧和 100 帧上限为什么是死的？帧数直接决定图像 token 成本，watch.py 与 frames.py 双重封顶（--max-frames默认 80、硬顶 100、--fps硬顶 2），防止一条命令打爆上下文。
• Q：视频多长效果最好？10 分钟以内最佳；更长请配合--start/--end。
• Q：Whisper 转写会传整个视频吗？不会，只上传 16kHz 单声道音频片段，上限 25MB（约 50 分钟音频）。
• Q：Windows 下要注意什么？用python而不是python3调用脚本。

十、附录：参数背后的源码位置

把这张速查表存在手边，下次调/watch时按场景选参：局部细节用--start/--end，读屏用--resolution，控成本用--max-frames，其余场景默认值就是最优解。

【免费下载链接】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