Claude Codeに動画を見せるOSS「claude-video」の仕組みと特徴

「Claude Code にこの動画を見せて、要点を抜き出してほしい」——AI コーディングエージェントを業務に組み込み始めたエンジニアであれば、一度はこう思ったことがあるはずです。ところが実際に URL を貼り付けても、Claude はタイトルと説明文からの推測しか返してくれず、期待した「視聴した上での回答」には至りません。

Claude 標準機能では動画ファイルを直接読み取れず、字幕だけを渡してもスライド・グラフ・UI 操作といった画面上の情報は失われます。かといって「動画を見せる」用途の OSS は近い時期に複数リリースされており、名前も機能もよく似ています。どれを自プロジェクトに採用すべきか、コスト・依存関係・対応ホストの判断材料が揃わないと動きにくい、というのが正直なところではないでしょうか。

本記事では、そうした選定の起点になりやすい OSS のひとつ「claude-video」（bradautomates/claude-video）を、公式 README とリポジトリメタデータに基づいて解説します。あくまでドキュメントベースの整理であり、動作検証や実測の追試は行っていません。仕組み・detail モードの選び分け・類似 OSS との差分を順に見ていき、「自プロジェクトで採用すべきか」の判断材料を提示することを目的とします。

以下のセクションでは、claude-video の概要、Claude が動画を扱えない前提と解消の仕組み、/watch コマンドの内部フロー、detail モード 4 種のトークン量比較、主要ユースケース、マルチホスト対応のインストール、そして類似 OSS との違いと制約までを順にたどります。

claude-video とは

claude-video は、Claude Code などの AI コーディングエージェントに「動画を視聴させる」ための Agent Skill / プラグインです。GitHub リポジトリは bradautomates/claude-video に公開されており、/watch <URL または ローカルパス> <質問> という一つのコマンドで、動画のダウンロード・フレーム抽出・音声書き起こしを一括して行い、その結果を Claude に渡します。

リポジトリの基本情報は以下のとおりです（GitHub API 取得値）。

執筆時点でアーカイブされておらず、フォーク元でもない本家リポジトリで、最終更新は 2026 年 7 月とアクティブに保守されている状態です。ライセンスは MIT のため、業務利用時の制約も比較的軽い部類に入ります。

なお、本記事の位置付けについて先に断っておきます。本記事は claude-video の README と公式リポジトリ、および同種の類似 OSS の公開情報を突き合わせて整理した資料であり、動作検証（インストール・実行・スクリーンショット取得）は行っていません。数値・仕様は原則としてリポジトリメタデータおよび README の記述に依拠しています。実装レイヤの検証が必要な場合は、必ず公式リポジトリで最新の README を確認してください。

解決する課題 — なぜ Claude は動画を直接「読めない」のか

Claude Code や Claude デスクトップに YouTube の URL を貼り付けて「これ要約して」と依頼すると、動画のタイトルと説明文、あるいは検索結果のスニペットからの推測に基づく回答が返ります。動画本編のフレーム、話者の音声、画面に映る UI やコードといった、動画が本来持つ情報の大部分は、Claude に届いていません。

かといって字幕（キャプション）だけを渡す方式にも限界があります。プレゼン動画の多くはスライドと図表で情報が伝達されており、UI 操作解説動画では画面遷移そのものが本体です。字幕テキストだけを Claude に渡しても、こうした画面情報は最初から欠落したままになります。

claude-video が持ち込むのは、「時刻付きフレーム画像」と「時刻付きトランスクリプト」を組にして Claude に一括で渡す仕組みです。フレームは Claude の画像入力機能（内部の Read ツールで画像として読み取る）に載り、トランスクリプトはテキストとして時刻情報つきで渡されます。この構造によって、Claude は「観て」「聴いた」上で回答できる状態に近づきます。

言い換えれば、claude-video は「Claude を動画対応に改造する」プラグインではなく、「Claude が扱える形（画像 + テキスト）に動画を変換して渡す」中間層です。動画理解の推論そのものは Claude の既存能力に委ねられており、claude-video が受け持つのは前処理のパイプラインだという設計思想が、のちほど扱う類似 OSS との棲み分けの理解にも効いてきます。

claude-video の主な特徴

README を横断的に読んで整理すると、claude-video の特徴は次の 5 点に集約できます。「何ができるのか」と「どこまで自プロジェクトの制約に合うのか」を最初に俯瞰しておくためのマップとして活用してください。

URL とローカルファイル、両対応の入力インターフェース

/watch コマンドの引数には、URL とローカルファイルパスのどちらでも渡せます。URL 側は yt-dlp が対応する数百サイト（YouTube / Loom / TikTok / X / Instagram / Vimeo など）を利用でき、社内 CDN のダウンロード URL でも問題ありません。ローカルファイル側は .mp4 / .mov / .mkv / .webm に対応します。スクリーン録画から SNS の短尺動画まで、同じインターフェースで扱えるのは実務上のメリットが大きい部分です。

字幕優先＋ Whisper フォールバックの二段構え

トランスクリプト取得は、まず yt-dlp で native captions（動画側が公式に提供している字幕）の取得を試みます。字幕が存在する動画はここで完結し、Whisper 側の API コールと課金は発生しません。字幕が無い動画に限って Whisper へフォールバックする、という順序です。Whisper バックエンドは Groq の whisper-large-v3（推奨）と、代替として OpenAI の whisper-1 が指定可能で、いずれも使いたくない場合は --no-whisper でフレームのみを Claude に渡す運用もできます。

4 段階の detail モードでトークン予算を制御できる

フレーム抽出の密度は transcript / efficient / balanced / token-burner の 4 段階で切り替えます。使い分けの目安と、49:08 の動画で計測された実測データはのちほど詳しく整理します。トークン量が実運用で読める形で示されていることは、claude-video の設計上の大きな特徴です。

フレーム重複除去（frame dedup）による静的スライド動画の節約

デフォルトで有効になっているフレーム重複除去は、抽出した JPEG を 16×16 グレースケールサムネイルに縮小して直前フレームとの差分を計算し、閾値以下であれば「重複」として捨てる仕組みです。スライドが数十秒間動かない録画セミナー動画のような素材では、動きの無い部分を圧縮できるため、フレームバジェットを「独立した画面」に使い切れます。

Agent Skills 標準に準拠し、複数ホストで動く

claude-video のスキル本体は Agent Skills 標準 に沿って SKILL.md を含むフォルダ構成で配布されており、Claude Code だけでなく Codex / Cursor / Copilot / Gemini CLI など 50 以上のホストに同一のスキルとして展開できるとされています。特定エージェント専用ではないため、社内で複数のコーディングエージェントを併用しているチームでも取り回しやすい設計です。

動作の仕組み — /watch コマンドの内部フロー

/watch コマンドの内部処理は、README の「How it works」セクションに 7 ステップで示されています。実装の詳細は変更されうるため、最新の記述は公式 README（bradautomates/claude-video の README.md）で確認してください。以下は執筆時点の整理です。

1. 動画の URL または ローカルパスと、動画に対する質問を受け取る
2. yt-dlp が字幕（native captions）の取得を試みる。字幕があれば動画本体のダウンロードを最小化する
3. ffmpeg がフレームを抽出する。detail モードに応じて keyframe / scene-change / 均等サンプリングを使い分ける
4. トランスクリプトを確定する。字幕が取れなかった場合のみ Whisper へフォールバックする
5. フレーム画像（時刻情報つき）とトランスクリプト（時刻情報つき）を Claude へ渡す
6. Claude は各フレームを画像として読み取り、音声書き起こしと突き合わせて回答を生成する
7. 作業ディレクトリをクリーンアップする（デフォルト挙動）

コマンド呼び出し自体は極めてシンプルで、README には次のような例が示されています。

/watch https://youtu.be/dQw4w9WgXcQ what happens in this video?

（出典: bradautomates/claude-video README.md、コード引用は原文からの改変なし）

この 7 ステップの分業を押さえておくと、「なぜ ffmpeg と yt-dlp と Whisper API が同時に必要なのか」「自環境のどこに依存があるのか」が見通しやすくなります。オフライン運用や API キー管理の面で制約がある場合は、のちほど扱う類似 OSS 比較の中で選択肢を検討する余地が出てきます。

detail モード 4 種の使い分け

detail モードは claude-video の運用上もっとも意識するべきパラメータで、動画長・用途・トークン予算の 3 軸のバランスをここで取ります。README「Detail modes — measured」に、49:08 の YouTube 動画で計測された実測データが掲載されています。

4 モードの比較（49:08 の実測値）

（出典: bradautomates/claude-video README.md の Detail modes — measured セクション）

画像トークンの算出式は Anthropic 公式ルールに準拠しており、(width × height) / 750 で見積もられます。デフォルトのフレーム幅は 512px で、720p の動画では 512×288 の 1 フレームがおよそ 197 トークンに相当します。文字が細かい画面（コードやダッシュボード等）を鮮明に読ませたい場合は --resolution 1024 を指定できますが、その場合は 1 フレームあたりのトークン量が約 4 倍になる点に注意が必要です。

選び方の目安

• 音声情報だけで足りる（ポッドキャスト、対談動画等） → transcript モード。字幕が取れるならほぼ無料
• 資料共有型の動画で概要をつかみたい → efficient モード。keyframe だけを拾うため軽い
• 動きの多い動画、UI 操作の追跡が必要 → balanced モード。scene-change ベースで密度が上がる
• 見落としを最小化したい / 短尺で最大精度を出したい → token-burner モード。cap を外して scene-change を拾い切る

フレームバジェット（動画長ごとの目安）

README にはフレーム密度の目安も動画長別に整理されています。

（出典: bradautomates/claude-video README.md）

長尺動画は --start / --end で focused 化する

10 分を超える長尺動画では、capped モード（efficient / 既定 balanced）だとフレーム間隔が疎になるため、着目したい区間だけを --start HH:MM:SS / --end HH:MM:SS で指定する focused モードが推奨されています。focused モードでは指定区間内で最大 2 fps までフレームバジェットを密に使えるため、「1 時間半のカンファレンス動画のうち Q&A の 10 分だけを詳しく解析したい」といった場面で効果を発揮します。全編を高密度で解析したい場合は --detail token-burner を選ぶ、という使い分けです。

主要なユースケース

README「What people actually use it for」で挙げられているユースケースは、いずれもエンジニアがコーディングエージェントを業務に組み込む文脈で見覚えのある用途に寄っています。導入判断時には、自チームの現状の作業と重ね合わせてみてください。

他人のコンテンツ解析（バイラル動画・広告クリエイティブ）

競合ローンチ動画、バイラルショート、広告クリエイティブの「hook（掴み）」や訴求構造を分解する用途です。文字起こしとフレームを組にして渡せるため、「何を映しているか」と「何を語っているか」を突き合わせた分析ができます。

スクリーン録画からのバグ再現・原因特定

/watch bug-repro.mov what's going wrong? のように、QA が録画したバグ再現手順の動画を Claude に見せ、再現手順の抽出や原因仮説の生成を依頼するパターンです。issue に貼られた録画を人間が全部見返す時間を圧縮する目的で使えます。

動画要約

/watch <URL> summarize this のパターンです。字幕が取れる YouTube 動画であれば transcript モードで実質無料に近い形で要約を得られます。

ローンチ動画から「本当の変更点」を抽出する

what's actually new — skip the hype のような依頼で、新製品発表動画から演出やハイプを差し引いた実質的な変更点だけを取り出す用途です。

プレイリスト・動画シリーズのノート化

動画シリーズを検索可能なノート集合に変換する用途で、--start / --end を組み合わせて章単位で処理する運用が想定されています。

インストールと初回セットアップ

claude-video の配布・インストール手段は複数用意されており、対応ホストの幅広さがそのまま採用判断に影響する部分です。以下は README で示されている手段を整理したものです。

Claude Code の場合（プラグイン）

Claude Code の内蔵プラグインシステムから直接インストールできます。

/plugin marketplace add bradautomates/claude-video
/plugin install watch@claude-video

（出典: bradautomates/claude-video README.md、コード引用は原文からの改変なし）

Codex / Cursor / Copilot / Gemini CLI ほか（Agent Skills 経由）

Agent Skills 標準に対応した 50 以上のホストに、共通の CLI で追加できます。

npx skills add bradautomates/claude-video -g

（出典: bradautomates/claude-video README.md と Agent Skills 公式サイト、コード引用は原文からの改変なし）

Agent Skills は SKILL.md を持つスキルフォルダを丸ごとコピーまたはシンボリックリンクする方式で、各ホストが個別にプラグイン仕様を持っていても共通の配布経路を保てます。マルチエージェント環境の運用チームにとって、この標準化されたインストール経路は導入判断で無視できない要素です。

claude.ai（Web 版）の場合

Web 版の claude.ai を使う場合は、claude-video の Releases ページ から watch.skill をダウンロードし、Web の Settings → Capabilities → Skills から追加する手順が案内されています。CLI を使わない Web ユーザにも導線が用意されている点は珍しい対応です。

手動インストール（開発者向け）

リポジトリを git clone して skills/watch をホストの skills ディレクトリにシンボリックリンクする方式もあります。フォークして自分の環境に合わせて改変したい開発者向けの選択肢です。

初回起動時の依存自動セットアップ

初回に /watch を実行すると scripts/setup.py --check が走り、依存パッケージの導入コマンドを OS ごとに案内する仕様になっています。README によれば、macOS では brew install ffmpeg yt-dlp を自動実行、Linux では apt / dnf / pipx の正確なコマンドを表示、Windows では winget / pip のコマンドを表示します。API キーが未設定のときは ~/.config/watch/.env（パーミッション 0600）に GROQ_API_KEY / OPENAI_API_KEY の scaffold を作成する挙動です。

類似 OSS との比較 — どれを選ぶかの判断軸

Claude Code に動画を扱わせる用途では、claude-video 以外にも近い時期にいくつかの OSS が公開されています。それぞれ目的と得意領域が微妙に異なるため、選択の起点として差分を整理しておきます。以下は執筆時点で確認できた各リポジトリの README・公開情報に基づく整理であり、詳細は必ず各公式リポジトリで確認してください。

jordanrendric/claude-video-vision — MCP サーバー実装で対話的にセットアップ

jordanrendric/claude-video-vision は、コンセプト自体は claude-video と近い「Claude Code に動画を見せる」ためのプロジェクトですが、Agent Skill ではなく MCP サーバーとして実装されている点が最大の違いです。setup wizard で backend の選択やフレーム設定を対話的に構成でき、npx 経由の auto-install に対応します。フレームと音声ファイルを一時ディレクトリに置いた後、即削除するプライバシー面の挙動が明示されているのも特徴です。「MCP を基盤に統一したい」「セットアップを対話式で任せたい」チームには、こちらのアーキテクチャが合う可能性があります。

alexlarcheveque/claude-watch — クリエイター用途特化・batch モード内蔵

alexlarcheveque/claude-watch は、汎用ではなくクリエイター向けに用途を絞ったスキルです。hook 分析 / retention 分析 / バルクライブラリ取り込みの 3 プリセットが最初から内蔵されており、--batch モードで CSV から複数動画を一括処理できます。ショート動画マーケティングや広告クリエイティブの継続分析が主目的であれば、claude-video より現場に近い抽象度で作業を進められます。

mathiaschu/watch — bradautomates のフォークで API キー不要のオフライン運用

mathiaschu/watch は bradautomates/claude-video のフォークで、Whisper 部分を mlx-whisper に置き換えることでローカル文字起こしを可能にしたバージョンです。Apple Silicon の Mac 上で API キーを持たずに動かせるため、社外への通信を最小化したい環境や個人開発でのオフライン運用に向いています。トランスクリプト精度は mlx-whisper の性能に依存する点だけ、事前に把握しておきたいポイントです。

参考: browser-use/Video Use — 「動画編集」を自動化する隣接ツール

同じ「動画」領域ですが、browser-use 系の Video Use は動画の「編集」を自動化する目的で作られています。素材動画をフォルダに置いて Claude Code に指示すると編集を代行する、というワークフローに寄っており、視聴・分析用途の claude-video とは目的が異なります。動画の中身を理解させたいのか、動画を編集させたいのか、で選ぶ側を明確にする必要があります。

どれを選ぶかの判断軸

上記を踏まえると、選定は次の 4 軸で整理できます。

• 目的: 視聴・分析なら claude-video / claude-video-vision / claude-watch。編集自動化なら Video Use 系
• 稼働環境: マルチホスト（Codex / Cursor / Copilot 等）で共通運用したいなら Agent Skills 標準準拠の claude-video が強い
• オフライン制約: 社外通信を避けたい、API キー管理を持ちたくないなら mathiaschu/watch
• 用途特化度: hook 分析・retention 分析を継続運用するなら claude-watch のプリセットを活用

いずれもドキュメントベースの整理であり、実運用の精度や安定性は自環境での試験で確認する必要があります。ここで示したのは、あくまで「候補を絞り込む」ための粗い判断軸です。

制約と注意点

導入前に把握しておきたい制約と、公式ドキュメント上で明示されている注意点を整理します。

10 分を超える動画は capped モードでは疎になる

README「Limits」に明記されているとおり、10 分を超える動画で efficient や既定の balanced を使うと、フレーム抽出間隔が疎になり "Sparse scan" 警告が出ます。「10 分」は capped モードでの目安であってハードリミットではありませんが、長尺動画では --start / --end の focused 実行、または --detail token-burner の使用が推奨されています。

依存ツールと OS 対応

Python が動く環境が前提で、ffmpeg・yt-dlp・Whisper API（または --no-whisper）を組み合わせて使います。macOS では brew、Linux では apt / dnf / pipx、Windows では winget / pip を使ったセットアップが README で案内されていますが、自組織の運用ポリシーで許容される依存かどうかは事前確認が必要です。

ライセンスと作者情報

ライセンスは MIT で、業務利用のハードルは相対的に低い設定です。作者は Brad Bonanno 氏（YouTube チャンネル @bradbonanno、Solaris Automation 創業）と README に記載されています。

活発度の目安

執筆時点（2026 年 7 月）で、最終プッシュ日時は 2026-07-01、スター数は 7,023、フォーク数は 785 と、中規模ながら派生プロジェクトが多く、活発に更新されている状態です。数値は変動するため、最新値は GitHub 上の bradautomates/claude-video で直接確認してください。

まとめ — claude-video が選ばれるケース

本記事では claude-video を、README とリポジトリメタデータに基づいて整理しました。要点は次のとおりです。

• claude-video は「Claude を動画対応に改造する」ものではなく、「動画をフレーム + トランスクリプトに変換して Claude に渡す」中間層 OSS
• detail モードは 4 段階で、トークン予算に応じて transcript / efficient / balanced / token-burner を使い分けられる
• Agent Skills 標準に準拠しており、Claude Code だけでなく Codex / Cursor / Copilot / Gemini CLI など 50 以上のホストに同一のスキルとして展開できる
• 類似 OSS には MCP 実装の claude-video-vision、クリエイター用途に特化した claude-watch、mlx-whisper でオフライン動作する mathiaschu/watch、目的が異なる Video Use などがある

以上を踏まえると、claude-video が最も向くのは、Claude Code を中心にしつつ他ホスト（Codex / Cursor 等）にも同じスキル体験を横展開したいチーム、そして detail モードとトークン予算を細かく制御したい運用チームです。一方で、社外通信を避けたい要件が強い場合は mathiaschu/watch のオフライン運用が、クリエイター用途に絞った継続分析が目的であれば claude-watch のプリセットが、動画編集の自動化が本命であれば Video Use 系がそれぞれ候補に上がります。

最終的な採用判断は、自プロジェクトの依存ポリシー・API キー管理・想定動画長・想定トークン予算と突き合わせた上で、公式リポジトリ（bradautomates/claude-video）の最新 README を確認して行ってください。