claude-real-video: 透過場景感知幀提取讓 LLM 能夠觀看影片

claude-real-video: 透過場景感知幀提取讓 LLM 能夠觀看影片

概覽

claude-real-video 是一款開源工具，旨在讓 Claude、ChatGPT 和 Gemini 等大型語言模型 (LLMs) 能夠透過將影片轉換為模型易於攝取的格式來「觀看」影片。與許多僅依賴逐字稿或固定間隔幀採樣的 AI 工具不同，claude-real-video 只提取重要的幀——特別是場景變化和關鍵視覺轉變——並將其與逐字稿配對，且所有操作都在使用者的本地機器上運行。

解決固定間隔採樣的局限性

大多數現有的影片轉 LLM 流水線，包括 Gemini 的原生影片處理，通常以固定間隔採樣幀（例如每秒 1 幀）。這種方法會產生兩個主要的低效率問題：

  1. 過度採樣靜態內容： 一段 10 分鐘的靜態螢幕錄影會產生 600 幀幾乎相同的影像，浪費了上下文窗口空間並增加了成本。
  2. 欠採樣快速剪輯： 固定採樣點之間發生的快速視覺變化往往會被完全忽略。

claude-real-video 透過結合使用場景變化檢測與密度底線來解決此問題。這確保了捕捉到每一次視覺轉變，同時維持一個最小幀頻率（由 --fps-floor 定義）以確保不會忽略任何長段的影片。

關鍵技術特性

智慧型幀去重

為了進一步優化上下文窗口，該工具採用了滑動窗口去重流程。它不使用簡單的感知哈希，而是使用縮放後的 RGB 像素差異來判斷一幀是否為唯一影像。

透過將新幀與最後幾個保留的幀進行滑動窗口比較（由 --dedup-window 控制），該工具可以防止同一鏡頭被多次發送給 LLM，即使影片使用了 A-B-A 剪輯。使用者可以透過 --dedup-threshold 標籤來調整此流程的靈敏度。

多模態數據提取

除了視覺內容外，claude-real-video 還為 LLM 提供全面的數據包：

  • 逐字稿： 該工具首先嘗試使用現有的字幕（SRT/VTT）以獲得最高準確度。如果不存在，則會退而求其次使用 OpenAI 的 Whisper 進行本地音訊轉錄。
  • 音訊提取： 使用 --keep-audio 標籤，該工具會將完整的音軌保存為 audio.m4a 檔案，允許具有原生音訊能力的模型（如 GPT-4o 或 Gemini）分析語調和音樂。
  • 清單檔案： 會生成一個 MANIFEST.txt 檔案來總結提取的內容，為 LLM 提供影片組件的結構化地圖。

本地處理與隱私

所有的處理——獲取、提取和去重——都在本地發生。該工具使用 yt-dlp 進行 URL 處理，並使用 ffmpeg 進行幀和音訊提取，確保影片數據不會被上傳到雲端服務進行預處理。

安裝與使用

系統要求

claude-real-video 需要 Python 3.10+ 並在系統路徑中安裝了 ffmpeg。

安裝

使用者可以安裝核心功能或包含轉錄功能的完整套件：

# 核心幀提取與去重
pip install claude-real-video

# 包含音訊轉錄的完整套件
pip install "claude-real-video[whisper]"

基本命令

  • 從 URL 開始： crv "https://www.youtube.com/watch?v=..."
  • 從本地檔案開始： crv lecture.mp4 -o out --lang en
  • 僅提取幀： crv clip.mp4 --no-transcribe
  • 登入限制內容： crv "https://..." --cookies cookies.txt

配置選項摘要

Flag Default Description
--scene 0.30 場景變化檢測的靈敏度（數值越低 = 幀數越多）
--fps-floor 1.0 最小幀捕捉頻率（每 N 秒一幀）
--max-frames 150 提取的幀總數上限
--dedup-threshold 8 被視為新幀所需的像素變化百分比
--dedup-window 4 用於去重時比較的先前幀數量
--report off 生成 report.html 以視覺化保留/捨棄的決策

Sources