claude-real-video (Claude 實時影片) 教學

1. 專案定位

claude-real-video (Claude 實時影片)，CLI 指令別名 crv，解決的是一個很具體的痛點：LLM 沒辦法真正「看」影片。

現況盤點：

貼 YouTube 連結給 ChatGPT，它讀的是逐字稿，不是畫面
Claude 完全不接受影片檔案輸入
Gemini 雖然能原生讀影片，但要整支上傳到 Google 雲端，且用固定間隔（預設 1 fps）取樣——快速剪接的鏡頭會被跳過，靜態畫面又過度取樣

crv 的做法：在使用者自己的機器上，用 ffmpeg 做場景感知（scene-aware）的關鍵影格抽取——偵測每次場景真正改變的瞬間，而不是固定每秒抓一張；再用滑動視窗去重演算法（sliding-window dedup）拿掉近似重複的畫面；音訊則優先沿用影片自帶字幕，沒有才用 Whisper 轉錄。輸出是一個資料夾（影格 + 逐字稿 + MANIFEST.txt），任何 LLM 都能讀。

一週內（2026-06-30 建立）拿下 1224 星、74 fork、登上 Hacker News 首頁，證明這個切入點抓對了需求。作者採 open-core 模式：這個 repo 是免費版（看到「畫面」），另有付費 crv Pro（理解「怎麼拍」——運鏡、剪輯節奏、情緒起伏）。

2. 安裝指南

前置需求

ffmpeg / ffprobe 是核心依賴，無法透過 pip 安裝，需另外裝：

1# macOS
2brew install ffmpeg
3
4# Linux（Debian/Ubuntu）
5sudo apt install ffmpeg
6
7# Windows
8winget install Gyan.FFmpeg

驗證安裝：

1ffmpeg -version

安裝 crv

1# 核心功能（抽格 + 去重）
2pip install claude-real-video
3
4# 完整功能（+ 音訊轉錄）
5pip install "claude-real-video[whisper]"

環境需求：Python 3.10+，支援 macOS / Windows / Linux。

整合進 Claude Code（選用）

如果你想讓 Claude Code 自動處理使用者貼的影片連結，把內建的 skill 複製過去：

1mkdir -p ~/.claude/skills
2cp -r skills/claude-real-video ~/.claude/skills/

之後在 Claude Code 對話中貼影片連結並提問，Claude 會自動呼叫 crv 抽格分析。

3. 核心架構解析

整個 pipeline 濃縮在單一 core.py（476 行），cli.py（107 行）只負責參數解析。處理流程是線性的六個步驟：


flowchart TD
    A["輸入來源
URL 或本地檔案"] --> B["fetch_video()
yt-dlp 下載 / 本地複製"]
    B --> C{"--adaptive?"}
    C -->|否| D["extract_frames()
固定場景門檻 + fps-floor"]
    C -->|是| E["extract_frames_adaptive()
相對鄰近影格的滾動平均"]
    D --> F["dedup_frames()
滑動視窗像素差異比對"]
    E --> F
    F --> G{"是否有字幕?"}
    G -->|有| H["existing_subtitles()
沿用 srt/vtt"]
    G -->|無| I["transcribe()
Whisper 轉錄"]
    H --> J["write manifest
MANIFEST.txt"]
    I --> J
    J --> K["選用輸出
--grid / --viewer / --kb / --keep-audio"]

關鍵設計決策：

單一 ffmpeg pass 保序：extract_frames() 用一個 select 濾鏡同時處理「場景變化」與「密度下限」兩個條件（gt(scene,threshold)+not(mod(n,every_n))），而不是分兩次抽取再合併——這樣影格天生按時間順序排列，去重時比對的才是真正的時間相鄰影格。
像素差異而非感知雜湊：dedup_frames() 刻意選擇下採樣後的 RGB 像素比對，而非常見的 perceptual hash。理由寫在 docstring 裡：hash 在「同亮度不同色相」的畫面切換（例如紅色轉綠色）上會誤判為沒變化。
滑動視窗而非只比對前一張：--dedup-window（預設 4）讓去重比對最近 N 張已保留影格，能抓到 A-B-A 式的鏡頭來回切換——不會因為中間插了一張不同畫面，就讓「回到原本鏡頭」的影格被誤判為新畫面而重複送出。
字幕優先、Whisper 為 fallback：existing_subtitles() 檢查 sidecar 檔案（本地檔案旁的 .srt/.vtt）與內嵌字幕軌，兩者都有就直接用，比重新轉錄快且準；只有真的沒字幕才呼叫 Whisper。
--adaptive 用滾動平均而非固定門檻（v0.5.3，回應 issue #2）：extract_frames_adaptive() 額外跑一次 _scene_scores() metadata pass 拿到逐影格場景分數，然後判斷每個分數是否顯著高於「自己前 N 秒的平均值」，而非跟全域固定門檻比較——這樣緩慢的漸變動作（squash/stretch）才不會因為單張影格分數不夠高而被整段漏掉。

4. 主要功能詳細用法

基本用法

1# YouTube / Instagram / TikTok 連結
2crv "https://www.youtube.com/watch?v=..."
3
4# 本地檔案，指定語言與輸出目錄
5crv lecture.mp4 -o out --lang en
6
7# 只要影格，不轉錄音訊
8crv clip.mp4 --no-transcribe

輸出結構：crv-out/frames/*.jpg + crv-out/transcript.txt + crv-out/MANIFEST.txt

常用參數表

flag	預設值	說明
`-o, --out`	`crv-out`	輸出目錄
`--scene`	`0.30`	場景變化敏感度，越低抽越多影格
`--fps-floor`	`1.0`	密度下限：每 N 秒至少一張
`--max-frames`	`150`	影格數上限
`--adaptive`	off	自適應場景偵測，抓緩慢漸變
`--dedup-threshold`	`8`	判定為新畫面所需的像素變化百分比
`--dedup-window`	`4`	比對最近 N 張已保留影格
`--grid`	off	拼成 3×3 contact sheet
`--viewer`	off	產生本地 `viewer.html`
`--why`	–	告訴模型「你在看什麼」，寫入 manifest 引導分析方向
`--kb`	–	存一份帶日期的 md 筆記到指定資料夾
`--keep-audio`	off	額外保留完整原始音軌
`--report`	off	產生 `report.html` 視覺化每張影格的去重判斷

從 Python 呼叫

1from claude_real_video import process
2
3r = process("https://youtu.be/...", "out", lang="en")
4print(r.frame_count, r.transcript_path)

帶目的分析 + 存進知識庫

1crv "https://youtu.be/..." --why "找出定價策略" --kb ~/notes

--why 讓輸出的 MANIFEST.txt 帶著「閱讀者的任務」開頭，引導後續讀取這份 manifest 的 LLM 聚焦在使用者關心的問題上，而不是產生泛用摘要。

5. 應用場景

教學影片拆解：抓取程式教學、動畫教學的關鍵畫面 + 逐字稿，讓 Claude 幫忙寫成文字版教學文件
社群媒體內容分析：分析 Reel / TikTok 的節奏與內容，搭配 --grid 讓 LLM 看連續動作序列
會議/簡報影片摘要：--why "整理決策事項" 讓 LLM 聚焦在會議重點，而非逐句摘要
個人知識庫累積：--kb ~/notes 讓每次分析結果自動變成帶日期的筆記，長期累積成可搜尋的影片知識庫
一般用途關鍵影格擷取：不涉及 LLM 分析時，也可以單純當作「場景變化偵測 + 去重」的影片關鍵影格擷取工具使用
Claude Code 自動化工作流：安裝為 skill 後，使用者只要貼影片連結，Claude Code 就會自動觸發抽格分析並回答問題

6. 資安掃描報告

掃描範圍：src/claude_real_video/（core.py、cli.py、viewer.py、__init__.py、__main__.py）

掃描指令：

1grep -rn -E "eval|exec|os\.system|subprocess|shell=True|curl|wget|http|urlopen|requests|pickle|__import__|input\(|raw_input|secret|token|password|api_key|API_KEY" src/

掃描結果：僅命中 4 行，全部屬於正常、預期的用法：

行號	內容	判讀
`core.py:8`	`import subprocess`	標準函式庫 import
`core.py:12-13`	`subprocess.run(cmd, capture_output=True, text=True)`	用參數列表（list）呼叫，不是字串拼接、不是 `shell=True`，無 shell injection 風險
`core.py:40`	`src.startswith(("http://", "https://"))`	純字串判斷來源是否為 URL，非網路請求程式碼
`core.py:310`	同上	同上

綜合評級：🟢 綠燈（乾淨）

無 eval/exec/os.system/pickle/__import__ — 沒有動態程式碼執行或反序列化風險
subprocess 呼叫一律用 list 參數，未發現任何 shell=True，可避免 shell injection
對外連線全部委派給 yt-dlp/ffmpeg/whisper 這三個成熟外部 CLI 工具，本專案程式碼本身不直接發 HTTP 請求（沒有 requests/urlopen 依賴）
無硬編碼密鑰、token 或密碼；--cookies / --cookies-from-browser 都是讀取「使用者自己」的登入憑證檔案或瀏覽器 cookie，README 明確提醒「只下載你有權存取的內容，不要把憑證提交進 repo」
唯一需要使用者自行注意的風險點：輸入來源信任——crv 會對使用者提供的 URL 呼叫 yt-dlp，對本地路徑做檔案複製；若把工具包進自動化管線且來源可被外部使用者控制，需在管線層另加白名單/驗證，但這是使用情境層級的風險，非程式碼本身缺陷

7. FAQ

Q: 為什麼不直接固定每秒抽一張影格？ A: 固定間隔會讓靜態畫面（如 10 分鐘投影片）產生 ~600 張近似重複影格，快速剪接的鏡頭又會漏掉關鍵瞬間。場景感知 + 去重能把這兩種狀況都處理好。

Q: 沒有字幕的影片會怎樣？ A: 若 whisper 未安裝，manifest 會誠實記錄「沒有既有字幕，也沒裝 whisper」，而不是假裝轉錄成功；若影片本身無音軌，會記錄「這支影片沒有字幕也沒有音軌」。

Q: --adaptive 什麼時候該用？ A: 內容變化緩慢時（動畫教學的漸變效果、慢速平移鏡頭）。固定門檻的場景偵測可能永遠不會觸發，--adaptive 改成跟「自己前幾秒的平均值」比較，能抓到這種緩慢變化。

Q: --grid 跟直接讀 frames/ 資料夾有什麼差別？ A: --grid 把連續 9 張影格拼成一張 contact sheet，模型讀「一張圖裡的連續序列」比讀「9 張分散的單張圖」更容易理解動作與時間推進，且大幅減少送進 LLM 的圖片數量（省 token）。

Q: 登入才能看的影片（如私人限動）能用嗎？ A: 可以，用 --cookies cookies.txt（Netscape 格式）或 --cookies-from-browser chrome。僅限使用者自己有權限存取的內容，不要把他人憑證用於此工具。

8. 進階技巧

調校去重門檻：加 --report 產生 report.html，用顏色標示每張影格是保留（綠框）、判定重複丟棄（紅框）還是被 --max-frames 裁掉（橙框），視覺化調整 --dedup-threshold 最適合的數值
長影片先設上限：影片很長時，先加 --max-frames 60 避免一次產生過多影格，去重演算法會在裁切時盡量讓保留下來的影格均勻分布在整支影片時間軸上（而非只留前段）
只要畫面不要聲音：--no-transcribe 可以顯著加速處理，適合純視覺分析場景
保留完整聲音給多模態模型：如果後續要餵給能聽聲音的模型（GPT-4o、Gemini），用 --keep-audio 額外存一份 audio.m4a（優先無損 stream copy，失敗才轉 AAC）
本機快速預覽：跑分析前先用 --viewer 產生 viewer.html，雙擊在瀏覽器打開，肉眼確認關鍵影格網格與逐字稿內容，再決定是否要餵給 LLM

9. 整合進其他工作流

搭配 paper-tutorial / video-to-tutorial（本 workspace Layer 17）：crv 可以作為 video-to-tutorial 工作流的前處理步驟——先用 crv --grid --why "教學重點" 抽取關鍵畫面 + 逐字稿，再交給既有的教學生成流程整理成文件
搭配知識庫累積：--kb 直接指向本 workspace 的 inbox/ 或個人筆記資料夾，讓影片分析結果自動變成帶日期的 markdown，銜接既有的「新知入庫」習慣
Claude Code skill 化：把 skills/claude-real-video/ 複製進 ~/.claude/skills/ 後，日常在 Claude Code 對話中貼影片連結即可觸發，不需要額外記指令

10. 重點摘要 Checklist

已安裝 ffmpeg（ffmpeg -version 驗證通過）
已用 pip install "claude-real-video[whisper]" 安裝含轉錄功能的版本
了解 --scene / --fps-floor / --dedup-threshold / --dedup-window 四個參數如何互相影響輸出影格數量
長影片先加 --max-frames 上限，避免一次產出過多影格
緩慢變化內容記得加 --adaptive
需要聚焦分析時用 --why 引導 LLM 閱讀方向
需要長期累積筆記時用 --kb 指向知識庫資料夾
資安掃描確認：無 shell=True、無硬編碼密鑰、subprocess 皆用 list 參數 —— 🟢 綠燈可安心使用
若要整合進 Claude Code，記得複製 skills/claude-real-video/ 到 ~/.claude/skills/

11. 進一步閱讀

官方 repo：https://github.com/HUANGCHIHHUNGLeo/claude-real-video
PyPI 套件頁：https://pypi.org/project/claude-real-video/
Hacker News 討論串：https://news.ycombinator.com/item?id=48766005
付費進階版 crv Pro（運鏡分析、剪輯節奏、情緒時間軸）：https://leoaido.com/crv-pro/
Issue #2（--adaptive 功能的原始需求）：https://github.com/HUANGCHIHHUNGLeo/claude-real-video/issues/2
Issue #3（--viewer lightbox 功能的原始需求）：https://github.com/HUANGCHIHHUNGLeo/claude-real-video/issues/3

claude-real-video 教學 — 讓 Claude 真正看懂影片

Contents

claude-real-video (Claude 實時影片) 教學

1. 專案定位

2. 安裝指南

前置需求

安裝 crv

整合進 Claude Code（選用）

3. 核心架構解析

4. 主要功能詳細用法

基本用法

常用參數表

從 Python 呼叫

帶目的分析 + 存進知識庫

5. 應用場景

6. 資安掃描報告

綜合評級：🟢 綠燈（乾淨）

7. FAQ

8. 進階技巧

9. 整合進其他工作流

10. 重點摘要 Checklist

11. 進一步閱讀

Comments

claude-real-video 教學 — 讓 Claude 真正看懂影片

Contents

claude-real-video (Claude 實時影片) 教學

1. 專案定位

2. 安裝指南

前置需求

安裝 crv

整合進 Claude Code（選用）

3. 核心架構解析

4. 主要功能詳細用法

基本用法

常用參數表

從 Python 呼叫

帶目的分析 + 存進知識庫

5. 應用場景

6. 資安掃描報告

綜合評級：🟢 綠燈（乾淨）

7. FAQ

8. 進階技巧

9. 整合進其他工作流

10. 重點摘要 Checklist

11. 進一步閱讀

Related Posts

Comments