claude-video 是 Brad Bonanno 開源的 Claude Skill,指令名稱 /watch。它用 yt-dlp 下載影片、ffmpeg 依場景抽格、原生字幕或 Whisper 轉錄聲音,再把畫面與逐字稿一起交給 Claude 分析。你可以問某個時間點發生什麼、摘要整支影片、或診斷螢幕錄影裡的問題。支援 YouTube、TikTok、Loom、Vimeo 等 100+ 平台與本機檔案。
大型語言模型不能直接「看」影片,但它能讀圖、能讀文字。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 在哪一秒壞掉。
相依套件是 ffmpeg 與 yt-dlp——macOS 會自動用 brew 裝好,Linux / Windows 會印出對應指令讓你執行。Whisper 轉錄是選配:大多數公開影片有原生字幕、免費就能用,只有抓不到字幕時才會退回 Whisper,那時才需要 Groq(建議)或 OpenAI 的 API key。首次執行會在 ~/.config/watch/.env 生成放金鑰的樣板。
透過 skills CLI 一行全域安裝,適用 50 種以上的 AI coding host:
自己 clone 再把 skills/watch 軟連結到 Claude 的 skills 目錄:
watch.skill,進 Settings → Capabilities → Skills → + 匯入即可;網頁版需要開啟 code execution 能力。相依套件不必自己張羅——ffmpeg 與 yt-dlp 會透過 brew / apt 自動安裝,字幕優先、Whisper 只在必要時才啟動。
/watch 的核心是 --detail 這顆旋鈕,它決定抽多少格、用哪種抽格引擎,直接換算成速度與 image token。下方數字量測自同一支 49 分 08 秒的影片。其餘旗標則是更細的取景、轉錄與預算控制。實務上,大多數影片直接用預設的 balanced 就夠;只有在長片某段、螢幕文字、或要完整覆蓋時,才需要動其他旗標。
--start 2:15 --end 2:45。預算更密、token 更低。--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」之間精準拿捏,而不是每次都盲目跑預設。
yt-dlp 會先嘗試抓原生字幕——免費、即時,涵蓋多數公開影片。只有在抓不到字幕時,才退回 Whisper API 轉錄。所以大多數情況你根本不需要任何 API key。
預設預算由影片長度自動計算:≤30 秒約 30 格、1–3 分約 60 格、3–10 分約 80 格。超過 10 分鐘會被壓到上限 100 格並印出「sparse scan」提示。
來源 · README · Frame Budget影格預設 512px 寬。要讀螢幕上的 UI 文字、程式碼、字幕時,用 --resolution 1024 拉高;代價是 image token 會明顯增加,別對整支長片濫用。
去重預設開啟:每格縮成 16×16 灰階縮圖,與上一張「保留」的影格算平均絕對差,差值 ≤2.0 就丟棄。預算在去重「之後」才套用。要保留每一格用 --no-dedup。
需要轉錄時,Groq 在成本與速度上較優,是預設偏好;OpenAI 為替代方案。用 --whisper groq|openai 明確指定,金鑰放在首次執行生成的 ~/.config/watch/.env。
轉錄字幕的 token 相對便宜,真正的成本來自影格。token 隨影格數與解析度放大——這也是為什麼 token-burner 與 --resolution 1024 要留給真的需要的場合。
以下是一段典型情境:你錄了一段螢幕操作,結帳按鈕在某個瞬間變成灰色不能按,但你不記得是哪一步觸發的。與其自己一格一格拉時間軸,不如把影片和問題一起丟給 /watch,讓它抽格、讀字幕、指出時間點。接著再示範一次對長片用 --start / --end 聚焦某段。
git status,
在 12:47 貼上一段 npm run build 的輸出,
13:02 畫面出現紅色錯誤,他改了一行設定後重跑通過。
關鍵在於 /watch 把影片翻譯成 Claude 原生就能讀的兩種輸入:畫面幀與帶時間戳的字幕。所以它給的答案是根據實際畫面,而不是靠檔名或描述猜。時間戳讓它能明確指出「00:41 變灰」,字幕與畫面互相對照又能交叉驗證。
兩個例子也示範了成本控制:本機檔案用預設的 balanced、去重砍掉三分之二的重複影格;長片則用 --start / --end 只看要看的 45 秒,預算更密、token 更省。看不清楚時再加 --resolution 1024,不必整支影片都拉高。
efficient 或 balanced 這類有上限的模式時,影格會被壓到 100 格,腳本會印出「sparse scan」提示。改用 --start / --end 聚焦某段,或用 --detail token-burner 取得不設上限的完整覆蓋。
--resolution 1024 與 token-burner 都會顯著推高成本。長片、高動態內容跑完整覆蓋前,先想清楚是不是真的需要每一格。
brew、Linux 透過 apt 自動安裝,但環境裡必須裝得起來。本機檔案只支援 .mp4、.mov、.mkv、.webm。
~/.config/watch/.env 生成樣板;沒設定時,無字幕影片就只有畫面、沒有逐字稿。
--no-dedup。
--detail 一顆旋鈕決定;除了既有旗標外,沒有獨立微調解析度與 fps 的細粒度控制。要更精準就靠 --start / --end、--timestamps 與 --resolution 組合。
基本用法是 /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。