把影片,變成 Claude 能讀懂的畫面與字幕。
大型語言模型不能直接「看」影片,但它能讀圖、能讀文字。claude-video 就是補上中間這一層:把一支影片拆成畫面幀(frames)加上帶時間戳的逐字稿,交給 Claude 平行處理。指令名稱是 /watch,作者是 Brad Bonanno。它建立在既有工具上——yt-dlp 負責下載、ffmpeg 負責抽格、Whisper 負責補字幕——本身只封裝成一個 Claude Skill。
流程分七步:你給一段影片網址或本機路徑加上一個問題;yt-dlp 先嘗試抓原生字幕(免費、即時);ffmpeg 依你選的細節模式,用場景偵測或關鍵格挑出畫面;字幕若抓不到,才退回 Whisper API 轉錄(Groq 優先、OpenAI 為備援);畫面加上時間戳字幕一起送進 Claude 平行讀圖;Claude 根據實際的畫面與聲音回答,而不是靠 metadata 猜;最後印出工作目錄,沒有後續追問就清理。
它支援 YouTube、Loom、TikTok、X、Instagram、Vimeo,以及透過 yt-dlp 的 100+ 平台;本機檔案吃 .mp4、.mov、.mkv、.webm。典型用途包括:問影片某個時間點發生什麼、摘要一小時的演講、或診斷螢幕錄影裡 UI 在哪一秒壞掉。
URL / 檔案
yt-dlp 下載
ffmpeg 抽格
字幕 / Whisper
Claude 讀圖
據實回答
「Claude answers based on the actual visual and audio content of the video — not its metadata.」 Claude 根據影片實際的畫面與聲音回答,而不是靠 metadata 猜。
四種路徑, 挑一種貼上即可。
相依套件是 ffmpeg 與 yt-dlp——macOS 會自動用 brew 裝好,Linux / Windows 會印出對應指令讓你執行。Whisper 轉錄是選配:大多數公開影片有原生字幕、免費就能用,只有抓不到字幕時才會退回 Whisper,那時才需要 Groq(建議)或 OpenAI 的 API key。首次執行會在 ~/.config/watch/.env 生成放金鑰的樣板。
Claude Code(建議)
# 加入 marketplace 後安裝 watch 外掛
/plugin marketplace add bradautomates/claude-video
/plugin install watch@claude-video其他 Agent:Codex、Cursor、Copilot、Gemini CLI 等 50+ host
透過 skills CLI 一行全域安裝,適用 50 種以上的 AI coding host:
npx skills add bradautomates/claude-video -g手動 / 開發者
自己 clone 再把 skills/watch 軟連結到 Claude 的 skills 目錄:
git clone https://github.com/bradautomates/claude-video.git
ln -s "$(pwd)/claude-video/skills/watch" ~/.claude/skills/watch用一顆旋鈕換精度與 token。
/watch 的核心是 --detail 這顆旋鈕,它決定抽多少格、用哪種抽格引擎,直接換算成速度與 image token。下方數字量測自同一支 49 分 08 秒的影片。其餘旗標則是更細的取景、轉錄與預算控制。實務上,大多數影片直接用預設的 balanced 就夠;只有在長片某段、螢幕文字、或要完整覆蓋時,才需要動其他旗標。
模式 · 01
--detail transcript
純字幕
只用字幕、抽 0 格,約 4.5s、0 image token。演講、podcast 等文字型影片最省。
模式 · 02
--detail efficient
關鍵格
keyframe 抽格、上限 50 格,約 0.5s、約 9.8k token。低動態、求快時用。
模式 · 03
--detail balanced
場景偵測
預設值。scene-change 抽格、上限 100 格,約 20.9s、約 19.7k token。覆蓋均衡。
模式 · 04
--detail token-burner
完整覆蓋
scene-change 不設上限,約 21s、約 22.8k token。高動態影片、要全抓時用。
取景 · 05
--start / --end
時間窗
只看指定區段,例如 --start 2:15 --end 2:45。預算更密、token 更低。
取景 · 06
--timestamps T1,T2,…
定點抽格
在絕對時間點各抓一格,額外加進 detail 預算。要盯特定畫面時好用。
取景 · 07
--resolution W
影格解析度
預設 512px;螢幕上有小字時設 1024 讀得更清楚,但 token 也隨之上升。
轉錄 · 08
--whisper groq|openai
轉錄後端
指定 Whisper 後端;Groq 在成本與速度上較優,OpenAI 為備援。
轉錄 · 09
--no-whisper
只要畫面
關掉轉錄,只送影格。不需要逐字稿、想省成本時用。
預算 · 10
--max-frames / --no-dedup
上限與去重
預設會去掉近乎重複的影格;--max-frames N 壓低上限,--no-dedup 保留全部。
要分析什麼,就選哪個模式
| 你要分析的內容 | 建議模式 / 旗標 | 為什麼 |
|---|---|---|
| 演講、podcast、以口語為主 | --detail transcript | 只靠字幕、0 影格,最快也最省。 |
| 低動態、想快速掃過 | --detail efficient | keyframe 抽格,約 0.5s、token 最低。 |
| 一般影片(預設情境) | --detail balanced | 場景偵測、覆蓋與成本平衡。 |
| 高動態、要完整不漏 | --detail token-burner | 不設上限,覆蓋最完整、token 最高。 |
| 長片只看其中一段 | --start / --end | 聚焦區段,預算更密、避免稀疏掃描。 |
六個決定成本與精度的設定。
以下六點全部出自官方 README,是理解 /watch 行為的關鍵。搞懂它們,你就能在「看得夠清楚」與「不燒太多 token」之間精準拿捏,而不是每次都盲目跑預設。
機制 01 · 字幕優先,Whisper 才是備援
yt-dlp 會先嘗試抓原生字幕——免費、即時,涵蓋多數公開影片。只有在抓不到字幕時,才退回 Whisper API 轉錄。所以大多數情況你根本不需要任何 API key。
來源 · README · How It Works
機制 02 · 影格預算跟著時長走
預設預算由影片長度自動計算:≤30 秒約 30 格、1–3 分約 60 格、3–10 分約 80 格。超過 10 分鐘會被壓到上限 100 格並印出「sparse scan」提示。
來源 · README · Frame Budget
機制 03 · 螢幕小字調高解析度
影格預設 512px 寬。要讀螢幕上的 UI 文字、程式碼、字幕時,用 --resolution 1024 拉高;代價是 image token 會明顯增加,別對整支長片濫用。
來源 · README · Key Flags
機制 04 · 近似影格會自動去重
去重預設開啟:每格縮成 16×16 灰階縮圖,與上一張「保留」的影格算平均絕對差,差值 ≤2.0 就丟棄。預算在去重「之後」才套用。要保留每一格用 --no-dedup。
來源 · README · Frame Deduplication
機制 05 · Whisper 後端 Groq 優先
需要轉錄時,Groq 在成本與速度上較優,是預設偏好;OpenAI 為替代方案。用 --whisper groq|openai 明確指定,金鑰放在首次執行生成的 ~/.config/watch/.env。
來源 · README · Dependencies & Keys
機制 06 · image token 由影格數主導
轉錄字幕的 token 相對便宜,真正的成本來自影格。token 隨影格數與解析度放大——這也是為什麼 token-burner 與 --resolution 1024 要留給真的需要的場合。
來源 · README · Detail Modes
用 /watch 抓出 UI 在哪一秒壞掉。
以下是一段典型情境:你錄了一段螢幕操作,結帳按鈕在某個瞬間變成灰色不能按,但你不記得是哪一步觸發的。與其自己一格一格拉時間軸,不如把影片和問題一起丟給 /watch,讓它抽格、讀字幕、指出時間點。接著再示範一次對長片用 --start / --end 聚焦某段。
$ You › /watch ~/Movies/checkout-bug.mov 結帳按鈕在哪一秒變成不能按?
claude: Claude ›
hl: 按鈕在 00:41 變灰。
序列是這樣:
· 00:38 你把數量從 1 改成 0
· 00:41 小計變成 $0.00,「結帳」隨即轉為 disabled
· 00:44 你點按鈕沒反應——因為它已經被停用
旁白在 00:42 說「欸怎麼按不動」,和畫面一致。
根因不是按鈕本身,是數量為 0 時沒有擋下、卻讓小計歸零。
$ You › /watch https://youtu.be/<id> --start 12:30 --end 13:15 這段在示範什麼指令?
claude: Claude ›
這 45 秒在示範終端機操作:講者先下 git status,
在 12:47 貼上一段 npm run build 的輸出,
13:02 畫面出現紅色錯誤,他改了一行設定後重跑通過。
「Give Claude the ability to watch any video.」 讓 Claude 具備看懂任何影片的能力。
這個流程為什麼有用
關鍵在於 /watch 把影片翻譯成 Claude 原生就能讀的兩種輸入:畫面幀與帶時間戳的字幕。所以它給的答案是根據實際畫面,而不是靠檔名或描述猜。時間戳讓它能明確指出「00:41 變灰」,字幕與畫面互相對照又能交叉驗證。
兩個例子也示範了成本控制:本機檔案用預設的 balanced、去重砍掉三分之二的重複影格;長片則用 --start / --end 只看要看的 45 秒,預算更密、token 更省。看不清楚時再加 --resolution 1024,不必整支影片都拉高。
先知道邊界, 再開始用。
把 /watch 調成你的用法。
基本用法是 /watch <URL 或路徑> <你的問題>,不加旗標就跑預設的 balanced。真正的差異來自你怎麼組合旗標。以下是幾條值得記住的進階路徑。
進階玩法地圖
**1. 用時間窗控制長片成本。**長片別整支跑;用 --start / --end 只看關鍵區段,例如 --start 1:12:00。區段預算更密、token 更省,也避開 sparse scan。
**2. 定點抽格盯特定畫面。**已知要看哪幾個時間點時,用 --timestamps 在絕對時間各抓一格,額外加進 detail 預算,不必靠場景偵測碰運氣。
**3. 螢幕錄影拉高解析度。**要逐字讀 UI 文字、程式碼或字幕時,加 --resolution 1024(預設 512);只在需要的那次用,避免整支影片都燒 token。
4. 依需要挑轉錄後端。--whisper groq 求成本與速度,--whisper openai 為備援;完全不需要逐字稿時用 --no-whisper 只送畫面。
**5. 裝到你慣用的 Agent。**不用 Claude Code 也行——npx skills add bradautomates/claude-video -g 可裝進 Codex、Cursor、Copilot、Gemini CLI 等 50+ host,工作流程不必換工具。
最該讀的三個連結
① github.com/bradautomates/claude-video——官方 README,含旗標、細節模式與相依套件的完整說明。 ② YouTube · @bradbonanno——作者 Brad Bonanno 的頻道,示範與背景。 ③ solarisautomation.io——作者所屬的 Solaris Automation。
「Built on yt-dlp, ffmpeg, Claude's multimodal Read tool, and Whisper via Groq or OpenAI.」 站在既有工具之上,只補上「理解」這一層。