video-perception

動画の視覚認識

claude-video-vision MCP サーバーを通じて、動画理解ツールを利用できます。

利用可能なツール

• video_analyze — ffmpeg フィルターを使って動画の構造（シーンの変化、無音、動きなど）を分析します。フレームを抽出する前に使用し、戦略を立ててください。
• video_watch — 動画からフレームを抽出し、音声を処理します。セグメントごとに FPS と解像度を変更できます。
• video_detail — 特定のセグメントを詳しく調べます。抽出と表示は別々に行うため、多くのフレームを抽出して、少しずつ確認できます。
• video_info — 処理せずに動画のメタデータを取得します。
• video_configure — 設定（バックエンド、解像度、enable_index など）を変更します。
• video_setup — 依存関係を確認・インストールします。

ワークフロー

重要：以下の手順を順番どおりに必ず実行してください。手順 2 を省略してはいけません。

1. まず必ず video_info を使い、動画の長さ、解像度、音声の有無を取得します。 ユーザーが YouTube の URL を指定した場合は、その URL を path に直接渡してください。 MCP サーバーは yt-dlp で動画をダウンロードし、文字起こしには YouTube の字幕や自動字幕を優先します。 字幕がない、空である、または明らかに不完全な場合にのみ、設定済みの音声バックエンドにフォールバックします。

2. 30 秒を超える動画では必須： フレームを抽出する前に video_analyze を呼び出します。 これは任意ではありません。構造データを取得し、適切な抽出方法を決めるために必要です。 ユーザーの質問に関連するフィルターを選択してください。

   ユーザーの意図	選択するフィルター
   「この動画では何が起きていますか？」	scene_changes, silence, transcription
   「シーンの切り替わりを見つけてください」	scene_changes, black_intervals
   「フリーズした部分や止まった部分はありますか？」	freeze, blur
   「これはトークヘッドですか、それともアクションですか？」	motion
   「音楽はいつ始まりますか？」	silence, loudness
   「照明を分析してください」	exposure
   「この講義を要約してください」	transcription, scene_changes, silence
   全般的／不明確な意図	scene_changes, silence, transcription

   動画に音声がある場合は、必ず transcription: true を含めてください。文字起こしから、 視覚的に確認すべき箇所がわかります。

   scene_changes: true はハードカット（scdet score >= 8）を報告します。より緩やかな トランジション（ディゾルブ、ゆっくりとしたフェード）が必要な場合は、scene_changes: { threshold: 4 } を渡してください。 手持ち撮影や動きの速い映像によってリストが多くなりすぎる場合は、しきい値を上げてください（例：{ threshold: 15 }）。

3. 分析結果と文字起こしを使って、フレーム抽出の方針を立てます。

   • 静的なセグメントや変化が予測できるセグメントには、低い FPS（0.1～0.5）を使います。
   • より高い FPS（1～3）は、シーンの切り替わり、動きのピーク、または発話で言及された場面（「ここを見てください」「ご覧のとおり」「お見せしましょう」）の周辺に限って使います。
   • タスクに必要な最低限の FPS を超えないでください。
   • FPS を低くしてセグメント数を少なくすることを優先してください。必要に応じて、いつでもさらに詳しく調べられます。

4. video_watch を呼び出してフレームを抽出します。

   • 短い動画（2 分未満）： view_sample を指定せずに fps: "auto" を使います。短い動画は、短い場面を見落とさないよう全体をカバーする必要があります。自動 FPS は動画の長さに合わせて調整されます。
   • 長い動画（2 分超）： 分析データに基づき、FPS を変更した segments を使い、view_sample で最初に表示するフレーム数を制限します。video_detail を使って、必要に応じてさらに詳しく調べられます。

5. video_detail を使って、特定の場面を詳しく調べます。

   • まず、注目箇所の前後 3～5 秒の範囲を指定します。
   • プレビューには view_sample: 3 を使います（最初、中間、最後のフレーム）。
   • さらに詳しく確認する必要がある場合は、view で特定のタイムスタンプを指定します。
   • 最初の表示で不十分な場合にのみ、範囲を広げます。
   • フレームの表示は二分探索のように行い、重要な部分に絞り込みます。
   • 抽出したフレームを一度にすべて表示しないでください。

6. ユーザーが同じ動画について追加の質問をした場合は、コンテキスト内にあるマニフェストを参照してください。 同じ解像度ですでに取得したフレームを再抽出しないでください。コンテキスト内にすでにあるフレームを再度要求しないでください。

パラメーターガイド

fps: 全体の概要には"auto"を使用します。フレームごとの詳細を確認するには、動画本来のfps（video_infoから取得）を使用します。特定の短い場面を分析するには5～10を使用します。長い動画には0.1～0.5を使用します。

resolution: 簡易スキャンには256～512を使用します。通常の分析には512～768を使用します。画面上のテキストや細部を読み取る場合は1024以上を使用します。

segments: 分析データがある場合に使用します。各セグメントには、それぞれfpsとresolutionを設定できます。グローバルなfps/start_time/end_timeを上書きします。

view_sample: 抽出されたフレームの中から、等間隔のN枚を返します。画像が多すぎてコンテキストがあふれるのを防ぐために使用します。

skip_audio: 映像分析のみが必要な場合は、trueに設定します。

YouTube URLs: 対応するYouTube URLは、pathとして直接渡します。transcription_source: "youtube_subtitles"はyoutube_auto_captionsより信頼性が高いものとして扱ってください。自動字幕には認識エラーが含まれる場合があります。

結果の活用

以下を受け取ります：

• マニフェスト（enable_indexが有効な場合）— 解像度とタイムスタンプごとのキャッシュ済みフレームのインデックスです。重複したリクエストを避けるために使用します。
• フレーム（画像）— 映像で何が起きているかを把握するために確認します
• 音声の文字起こし（タイムスタンプ付き）— 発話の内容を読み取ります
• 音声タグ— 発話以外のイベント（音楽、音など）です
• 分析データ— シーンの切り替わり、無音区間、動きのレベルなどです

すべての情報を組み合わせて、全体を把握してください。分析データと文字起こしを参考に、映像を確認する箇所を決めます。分析データは出来事がいつ起きるかを示し、フレームは何が起きるかを示します。