claude-real-video：讓 LLM 真的看見影片，而不是只讀字幕
Let Claude (or any LLM) actually watch a video — scene-aware, deduplicated frames + transcript, from a URL or local file. Runs locally, MIT.
秒懂
- 它是什麼？
- 這個 Python 工具在本機用 ffmpeg 做場景偵測、去重、抽音訊轉錄，輸出一份任何 LLM 都能讀的資料夾。它解決的是固定取樣漏掉快剪的問題，代價是你得自己把 frames 貼進模型。
- 適合誰用？
- 如果你要處理的是剪接密集的影片、螢幕錄影或訪談，而且在意素材不離開本機，crv 值得裝起來試；如果你只是偶爾問一句 YouTube 影片在講什麼，ChatGPT 讀字幕已經夠用，多裝一層 ffmpeg 與 Whisper 只是負擔。動手前先確認兩件事：一是字幕來源，URL 執行依賴來源自帶字幕，沒有字幕又需要逐字稿時得靠 Whisper 這條路；二是你的重點畫面是不是小字，是的話先決定 --frame-width 要拉到多少，否則關鍵影格抓對了、細節卻在縮圖裡糊掉。
- 可以商用嗎？
- 可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 5 天前。
- 用什麼語言寫的？
- 主要是 Python（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
它要解的不是「讀不到影片」，而是「讀到的影片是假的」
把 YouTube 連結貼進 ChatGPT，模型讀的是字幕，不是畫面。Claude 直接不收影片檔。Gemini 雖然原生吃影片，但影片要上傳到 Google，而且取樣是固定間隔，README 寫預設 1 fps，於是快速剪接的片段會整段滑過去。crv 針對的是後面這一層：不是「能不能餵影片」，而是「餵進去的影格是不是真的代表這支影片」。
README 給的對照很具體：同一支 58 秒的短片，固定 1 fps 取樣會得到 58 張，crv 只留下 26 張真正有差異的，再用 --grid 壓成 3 張 contact sheet。目標讀者是那些要對影片內容下判斷的人：看訪談整理逐字稿、看螢幕錄影找某個操作步驟、看教學影片抓投影片。對這些人來說，餵 58 張幾乎一樣的圖不只是浪費 token，還會讓模型把注意力稀釋在重複畫面上。
反過來說，如果你的問題只是「這支影片大概在講什麼」，字幕就足以回答，那 crv 這一層處理就是多餘的。它的價值出現在畫面本身攜帶資訊、而字幕沒有描述那些資訊的時候。
場景偵測、去重、轉錄：三個步驟各自處理什麼
從 README 與輸出結構可以看出流程是串起來的。第一步是場景偵測，抽幀的依據是畫面變化，不是固定配額，所以切點密集的地方影格自然變多，長鏡頭的地方自然變少。第二步是去重，把近似重複的影格丟掉，這是 58 張變 26 張的來源。第三步是音訊轉錄，走 Whisper。
輸出落在 crv-out/ 底下：frames/*.jpg 是影格本體，frames.json 帶每一張的對應時間戳，transcript.txt 與 transcript.json 是逐字稿，MANIFEST.txt 是給模型看的清單。這個設計的關鍵在 frames.json 與 MANIFEST.txt：模型拿到的不只是圖片，還有「這張圖出現在第幾秒」，所以它可以引用時間點回答，而不是只能描述畫面。
--grid 是壓縮層。它把影格排成 contact sheet，用一張圖換多張圖的資訊量，代價是單張影格的解析度被攤掉。要判斷值不值得，取決於你的重點畫面是不是靠細節取勝。
--viewer 是另一條路，它寫出一份本機的 viewer.html，裡面有影片、關鍵影格網格與逐字稿，README 說不需要網路也不需要額外安裝，直接雙擊開啟。這在你要先確認「模型會看到什麼」再決定要不要貼進 LLM 的時候有用。
安裝與實際會打的三種指令
最基本的一行是 pip install "claude-real-video[whisper]"，然後 crv "<url>" 就能跑，README 說明 CLI 單獨使用時只要這個 pip 安裝即可。輸出會落到 crv-out/。
要在 Claude Code、Cursor、Codex、Copilot、Gemini CLI 這類 agent host 裡用的話，多一行 npx skills add HUANGCHIHHUNGLeo/claude-real-video，它會把 skill 裝進這些 host。README 也給了手動路徑：git clone 之後把 skills/claude-real-video 複製到 ~/.claude/skills/。Claude Code 另有 plugin marketplace 的裝法，/plugin marketplace add HUANGCHIHHUNGLeo/claude-real-video 再接 /plugin install claude-real-video@claude-real-video，README 提到可以在 /plugin 的 Marketplaces 裡開啟自動更新。
不想碰終端機的人有 crv-web，會開一個本機頁面，介面有繁體中文、簡體中文與英文，貼連結或檔案路徑、按 Analyze、開結果檢視器。README 明確寫分析與輸出產生都在本機，來源影片不會上傳；但如果你之後把抽出來的影格或逐字稿貼進雲端 LLM，那筆資料就會送到該供應商。
時間窗用 --from 28:00 --to 43:00。README 說 ffmpeg 會直接 seek 而不是解碼整個檔案，Whisper 也只聽這個區間，影格預算花在窗內，而 crv 回報的時間戳仍然是原始影片的時間碼，可以直接拿去跟同事對照。這對「90 分鐘會議裡只有 10 分鐘螢幕分享有意義」的情境是省時間的關鍵。
--adaptive 與 --text-anchors 各自補哪種破洞
預設的場景偵測靠單一影格的變化量觸發，這對硬切有效，對漸變無效。README 舉的例子是 2 到 3 秒的 squash-and-stretch，這種動畫不會在任何單一影格上產生尖峰，所以預設模式會漏掉。--adaptive 改成拿影格跟它的滾動鄰域比較，而不是跟固定門檻比較，慢速平移、漸變、動畫教學這類內容才收得進來。
--text-anchors 處理的是另一種失敗：畫面幾乎不變，但講者一直在講。它會在字幕 cue 的時間點強制插入額外影格，讓每一段口述都有對應的視覺。這裡有個硬限制，README 寫得很清楚：需要外掛的 .srt/.vtt 或內嵌字幕軌，燒進像素裡的字幕偵測不到。另外強制影格的上限是每秒一張，場景偵測本身不受影響。
--speakers 是第三個補丁，針對訪談、podcast、會議這類多講者內容，逐字稿每一行會加上 [SPEAKER_00]、[SPEAKER_01] 這種標籤，讓模型能追誰說了什麼。它跑的是本機的 diarization 模型，45 MB，下載一次，不需要帳號或 token，安裝要加上 pip install "claude-real-video[speakers]"。
三個旗標指向三種不同的內容形態，這也是判斷這個工具適不適合你的最快方式：你的影片是硬切為主、漸變為主，還是畫面不動但聲音在動。
畫面裡的關鍵是小字時，抽幀正確還不夠
README 自己點出一個很容易被忽略的失敗模式：終端機、試算表、IDE 這類內容，重點在於小字。它寫得很直白，影格選擇是難的部分而 crv 已經做了，但在 1920 寬的螢幕錄影上以 640px 抽幀，正確的時刻被找到了，然後讓這個時刻值得被找的細節被丟掉了。
解法是 --frame-width 1600。這不是調校參數，而是承認抽幀與可讀性是兩個獨立的問題：前者決定你拿到哪幾秒，後者決定那幾秒能不能讀。預設值服務的是「畫面主體夠大」的一般影片，螢幕錄影不在那個假設裡。
這個限制的另一面是成本。拉高 frame-width 等於每一張影格都變大，如果你之後要貼進 LLM，token 用量跟著上升，而 --grid 的壓縮效果也會被抵銷。這裡沒有免費的選擇，只能依你的內容決定把預算放在哪裡。
還有一個邊界是字幕。--text-anchors 依賴字幕檔或字幕軌，燒進畫面的字幕不行。而 URL 執行在 v0.10.2 之後改用來源自帶的字幕，這意味著來源沒有字幕時，那條路就斷了。
不碰 LLM 也能用的部分，以及付費版本的界線
README 提到，不做 LLM 工作的人也可以把它當一般用途的關鍵影格抽取器：場景變化偵測加去重，不需要下載任何 ML 模型。這其實是這個專案比較少被談到的定位，因為它的名字與行銷都綁在 LLM 上，但抽幀這件事本身跟模型無關。
付費的部分要講清楚，避免混淆。crv 是 claude-real-video 這個 PyPI 套件的簡稱，免費版讓你「看見」影片。付費加值叫 crv Pro，在 Capafy 上的商品名是 llm-real-video Pro，README 寫一次買斷 29 美元，另外有 Lemon Squeezy 的刷卡結帳連結。Pro 加的是免費版沒有的層次：鏡頭怎麼拍（剪接節奏、運鏡），以及影格看不出來的時間軸資訊，包含手勢、表情、語音音高變化、情緒、聲音事件。
這個切分方式值得注意：免費版處理的是「畫面裡有什麼」，Pro 處理的是「畫面之外發生什麼」。如果你的分析需要判斷語氣或情緒，免費版不會給你這些，而這不是靠調參數能補的。
授權是 MIT。這表示你可以自由使用、修改、再散布這個套件，但 MIT 只涵蓋開源程式碼本身，crv Pro 是另外販售的商品，不在同一個授權範圍內。README 沒有說明 Pro 的授權條款，這部分需要直接看它的銷售頁，本文無法從現有材料判斷。
跟 Gemini 原生影片、跟純字幕流程的差別在哪
最直接的替代方案是 Gemini 的原生影片輸入。差別有兩層。第一層是取樣策略：README 說 Gemini 預設以 1 fps 固定間隔取樣，crv 則依場景變化決定在哪裡取，所以快剪內容的取樣密度不是常數。第二層是資料流向：Gemini 必須把影片上傳到 Google，crv 的處理在本機完成，只有你之後主動貼進 LLM 的影格與文字會離開你的機器。
第二個替代方案是純字幕流程，也就是把逐字稿丟給模型。這個做法便宜、快，而且對「這支影片在講什麼」這類問題通常夠用。它的失效點是畫面本身攜帶的資訊：示範操作、投影片上的圖表、畫面裡的錯誤訊息，字幕不會描述這些。crv 的 frames.json 讓模型能引用時間點，這是純字幕給不了的。
第三個是拿 ffmpeg 自己寫腳本抽幀。這在技術上完全可行，crv 底層也是 ffmpeg。差別在於它已經處理掉去重、時間戳對齊、輸出結構這幾件事，而且 frames.json 與 MANIFEST.txt 的格式是為了餵模型而設計的。如果你已經有一套自己的抽幀流程，換過來的價值主要在輸出格式與那些旗標，不在抽幀本身。
這三個替代方案的取捨其實是同一條線：你要花多少前置成本，換取模型對畫面的掌握程度。
維護節奏與該先驗證的事
從 release 紀錄看，這個專案在 2026 年 8 月下旬的改版相當密集：v0.10.1 修視窗問題，v0.10.2 讓 URL 執行改用來源自帶的字幕，v0.10.3 調整字幕標題不再展開逐字稿。改版訊息顆粒度很細，都是行為層面的修正，這對採用者是好消息也是提醒：行為還在動，尤其是 URL 路徑的字幕來源在 0.10.2 才改過。
相依成本要算進去。whisper 與 speakers 是兩個獨立的 extras，diarization 模型 45 MB 下載一次。ffmpeg 是底層依賴，README 沒有列出它是否需要另外安裝，這點在動手前要先確認。Python 版本要求是 3.10 以上。
crv-web 開的是本機頁面，README 說分析與輸出都在本機，來源影片不上傳。但這只涵蓋 crv 這一段，後續貼進雲端 LLM 的資料仍然會離開你的機器，這個界線在評估資料敏感度時要分開看。
要驗證的第一件事是字幕來源：你的目標影片有沒有自帶字幕，沒有的話就得走 Whisper，而 Whisper 的品質與語言支援是另一個變數。第二件是 frame-width 的預設值在你的內容上夠不夠，特別是螢幕錄影。第三件是輸出格式能不能直接餵進你實際在用的模型，因為 crv 交付的是一份資料夾，最後那一步的貼上動作仍然是人做的。
編輯結論
如果你要處理的是剪接密集的影片、螢幕錄影或訪談，而且在意素材不離開本機，crv 值得裝起來試；如果你只是偶爾問一句 YouTube 影片在講什麼，ChatGPT 讀字幕已經夠用，多裝一層 ffmpeg 與 Whisper 只是負擔。動手前先確認兩件事：一是字幕來源，URL 執行依賴來源自帶字幕，沒有字幕又需要逐字稿時得靠 Whisper 這條路；二是你的重點畫面是不是小字，是的話先決定 --frame-width 要拉到多少，否則關鍵影格抓對了、細節卻在縮圖裡糊掉。
社群筆記