claude-real-video: シーン認識フレーム抽出によるLLMの動画視聴の実現

claude-real-video: シーン認識フレーム抽出によるLLMの動画視聴の実現

概要

claude-real-videoは、Claude、ChatGPT、Geminiなどの大規模言語モデル（LLM）が動画を「視聴」できるように、動画をモデルが容易に読み込める形式に変換するオープンソースツールです。トランスクリプト（書き起こし）や固定間隔のフレームサンプリングのみに依存する多くのAIツールとは異なり、claude-real-videoは、シーンの変化や重要な視覚的変化といった、重要なフレームのみを抽出し、それらをトランスクリプトと組み合わせて、ユーザーのマシン上でローカルに実行します。

固定間隔サンプリングの限界の解決

Geminiのネイティブな動画処理を含む、既存のほとんどの動画からLLMへのパイプラインは、通常、固定の間隔（例：1秒間に1フレーム）でフレームをサンプリングします。このアプローチには、主に2つの非効率性があります。

  1. 静止コンテンツの過剰サンプリング: 10分間の静止したスクリーンキャストでは、ほぼ同一のフレームが600枚生成され、コンテキストウィンドウのスペースを浪費し、コストを増大させます。
  2. 高速なカットの過小サンプリング: 固定サンプリングポイントの間で発生する急速な視覚的変化が、完全に見逃されることがあります。

claude-real-videoは、シーン変化検出と**密度フロア（density floor）**を組み合わせることで、この問題に対処します。これにより、すべての視覚的遷移がキャプチャされる一方で、--fps-floorで定義される最小フレーム頻度を維持し、動画の長い区間が無視されないようにします。

主な技術的特徴

インテリジェントなフレーム重複排除

コンテキストウィンドウをさらに最適化するために、このツールはスライディングウィンドウ方式の重複排除プロセスを採用しています。単純な知覚ハッシュではなく、縮小されたRGBピクセル差分を使用して、フレームがユニークであるかどうかを判断します。

新しいフレームを、保持された直近の数フレームのスライディングウィンドウ（--dedup-windowで制御）と比較することで、ツールは、動画がA-B-Aカットバックを使用している場合でも、同じショットがLLMに複数回送信されるのを防ぎます。ユーザーは、--dedup-thresholdフラグを使用して、このプロセスの感度を調整できます。

マルチモーダル・データ抽出

視覚情報だけでなく、claude-real-videoはLLM向けに包括的なデータパッケージを提供します：

  • トランスクリプト: ツールはまず、最大限の精度を得るために既存の字幕（SRT/VTT）の使用を試みます。字幕が存在しない場合は、ローカルでの音声書き起こしのためにOpenAIのWhisperにフォールバックします。
  • Audio Extraction: --keep-audioフラグを使用すると、ツールはサウンドトラック全体をaudio.m4aファイルとして保存し、ネイティブな音声機能を持つモデル（GPT-4oやGeminiなど）がトーンや音楽を分析できるようにします。
  • Manifest File: 抽出されたコンテンツを要約するためにMANIFEST.txtファイルが生成され、LLMに動画の構成要素の構造化されたマップを提供します。

ローカル処理とプライバシー

フェッチ、抽出、重複排除を含むすべての処理はローカルで行われます。ツールはURLの処理にyt-dlpを、フレームおよび音声の抽出にffmpegを使用し、動画データが前処理のためにクラウドサービスにアップロードされないことを保証します。

インストールと使用方法

システム要件

claude-real-videoには、Python 3.10以上、およびシステムパスにインストールされたffmpegが必要です。

インストール

ユーザーは、コア機能または書き起こしを含むフルスイートをインストールできます：

# Core frames and deduplication
pip install claude-real-video

# Full suite including audio transcription
pip install "claude-real-video[whisper]"

基本コマンド

  • From a URL: crv "https://www.youtube.com/watch?v=..."
  • From a local file: crv lecture.mp4 -o out --lang en
  • Frames only: crv clip.mp4 --no-transcribe
  • Login-gated content: crv "https://..." --cookies cookies.txt

設定オプションの要約

Flag Default Description
--scene 0.30 シーン変化検出の感度（値が低いほど、より多くのフレームを抽出）
--fps-floor 1.0 最小フレームキャプチャ頻度（N秒ごとに1フレーム）
--max-frames 150 抽出するフレームの最大合計数
--dedup-threshold 8 新しいフレームとしてカウントするために必要なピクセル変化率
--dedup-window 4 重複排除のために比較対象となる直近のフレーム数
--report off 保持/破棄の決定を可視化するためにreport.htmlを生成

Sources