claude-video（/watch）解説｜Claude Codeに動画を「見せる」スキルの全貌

「Claudeはウェブページを読めるし、スクリプトも動かせるし、リポジトリも巡回できる。でも標準では、動画を見ることだけはできない」——これは claude-video のREADMEが冒頭で突きつける、地味だが本質的な指摘です。YouTubeのリンクを貼っても、AIはタイトルから中身を推測するか、画面上の情報の9割が抜け落ちた文字起こしを引っ張ってくるくらいしかできません。

claude-video（コマンド名は /watch）は、この「AIは動画を見られない」という穴を、クローンして使えるオープンソースのスキルとして埋めるツールです。URLやローカル動画を渡すと、字幕を最優先で取り込み、シーン変化に合わせてフレームを抜き出し、必要なら文字起こしして、Claudeが実際に画面を見て・音声を聞いたうえで答える。GitHubのスター数は4,000を超え、Claude CodeだけでなくCodexやCursorなど50以上のエージェントで使えます。本記事では、この claude-video が何をするツールで、どう動き、どう導入し、どうすればトークンを無駄にせず使えるのかを、公式リポジトリの一次情報にもとづいて解説します。

Claude Code全体の使い方は Claude Code完全ガイド2026：インストールから本番運用まで をご覧ください。

1. claude-video とは — Claudeが動画を「見られない」問題を解く

bradautomates/claude-video は、AI活用の発信者Brad Bonanno氏が公開する、MITライセンスのオープンソースです。中核は skills/watch/ という自己完結したスキルで、これを各種エージェントに入れると /watch というコマンドが使えるようになります。

このスキルが解決するのは、たった一つですが根の深い問題です。LLMは動画そのものを「見る」手段を標準では持っていません。YouTubeのURLを貼っても、モデルはタイトルや概要欄から中身を想像するか、字幕テキストだけを頼りにするしかない。画面に映っているUI、コードの差分、スライドの図——こうした「映像でしか伝わらない情報」は、まるごと欠落します。

claude-videoの発想はシンプルです。「見られないなら、見られる形に変換してから渡せばいい」。具体的には、動画をフレーム（静止画）の列とタイムスタンプ付きの文字起こしに分解し、Claudeが得意な「画像を読む（Read）」「テキストを読む」という操作に落とし込みます。結果として、Claudeは「概要欄によれば」ではなく、「実際に30秒地点のフレームを見たところ」という根拠で答えられるようになります。

——ここを押さえると、後述のdetailモードやフレーム予算の話がすべて腑に落ちます。

この変換で鍵になるのが、Claudeがもともと持っている画像を読む能力（Readツール）です。claude-videoは新しいモデルや特別な推論エンジンを足すわけではありません。あくまで「Claudeが既にできること（画像を読む・テキストを読む）」に合わせて、動画を前処理するだけ。だからこそ軽量で、特定のモデルに縛られず、50以上のホストで同じように動きます。スクリプトが各フレームを t=MM:SS というタイムスタンプ付きで並べ、Claudeがそれを並列に読み込むことで、「この瞬間に画面で何が起きていたか」を時間軸に沿って把握できるわけです。

もう一つ設計上の特徴が、自己完結したスキル（self-contained skill）であることです。中身は SKILL.md（スキルの契約書＝すべてのホストで共通の真実の源）と、その下の scripts/（watch.py を入口に、ダウンロード・フレーム抽出・文字起こし・Whisperクライアント・設定・セットアップが分かれた純Pythonのランタイム）。この一式がフォルダごとコピーされるため、どのホストに入れても挙動が変わりません。依存はほぼ標準ライブラリで、外部の重いパッケージを持ち込まない点も、導入のハードルを下げています。

そしてこのスキルは、Claude Code専用ではありません。READMEは、Codex・Cursor・Copilot・Gemini CLIをはじめとする50以上のAgent Skillsホストで同じスキルが動くことを明記しています。導入方法もホストごとに用意されており、yt-dlp と ffmpeg は初回実行時にmacOSなら自動インストール、Linux/Windowsなら正確なコマンドを提示してくれる「ゼロコンフィグ」設計です。作者のBrad Bonanno氏は、AI活用の発信（YouTube @bradbonanno）とビジネス向けの自動化構築（Solaris Automation）を手がける実務家で、「動画をスクラブして探す時間」を減らすという実利から逆算してこのスキルを設計しています。

2. claude-video で実際にできること

claude-videoが「何を解決するか」は、READMEが挙げる具体的な使いどころを見ると一気に鮮明になります。単なる文字起こしツールではなく、「動画の中身に踏み込んで質問する」ための道具だとわかります。

・他人のコンテンツを分析する：/watch <バズ動画のURL> どんなフックで始めた？ と聞けば、Claudeは冒頭フレームと導入部の文字起こしを見て、構成を分解する。広告クリエイティブ、競合のローンチ動画、ポッドキャストの入り——「何を」だけでなく「どう」見せているかが重要な素材に効く
・動画からバグを診断する：壊れた挙動の画面録画を渡されたとき、/watch bug-repro.mov 何が起きてる？ で、Claudeが不具合の出るフレームを特定し、画面上で何が起きているかを説明する。ファイルを開く前に原因を捉えることも多い
・動画を要約する：/watch <長い動画> これ要約して は、構成・要点・実際に語られた/映されたことを引っ張ってくる。2倍速で見るより速い
・更新動画から誇張を削ぎ落とす：/watch <ローンチ動画> 実際に何が新しい？誇張は抜きで で、「ゲームチェンジャー」的な煽りを外し、本当に重要な数点だけを取り出す
・プレイリストをノートに変える：シリーズ動画に一本ずつ走らせ、動画ごとの要約をファイル化すれば、チャンネルや講座が「座って見るしかない時間の塊」から「検索できるノート集」に変わる

これらに共通するのは、「画面と音声の中身に対して、自然文で質問できる」という体験です。読者が当サイトのOSS解説に求める「①結局何ができる／②何を解決する／③何を代替できる」に当てはめれば、claude-videoは「①動画に質問して中身で答えさせる／②AIが動画を見られない欠落を埋める／③手作業のスクラブ（早送りで探す作業）や、画面を人が見て説明する手間を代替する」ツールだと言えます。

とりわけ効いてくるのが、「動画を情報源として扱えるようになる」という変化です。これまで、動画に含まれる知識は「座って再生するしかない、検索できない塊」でした。技術カンファレンスの録画、製品デモ、チュートリアル——価値ある情報が動画に閉じ込められていても、テキストのように grep したり要約したりはできなかった。claude-videoは、その動画を「Claudeに質問できるテキスト＋画像の素材」に変換することで、動画を他の情報源（ドキュメント、リポジトリ、記事）と同じ土俵に乗せます。結果として、「この30分の登壇動画、実装に関係する部分だけ教えて」といった問いに、Claudeが該当箇所のフレームと発言を根拠に答えられるようになります。単に文字起こしを出すだけのツールとは、ここが決定的に違います。

もちろん万能ではありません。権利上ダウンロードが許されない動画に使うのは論外ですし、フレームを大量に取り込む長尺の逐一分析は、コストと精度の両面で不利になります。claude-videoが最も輝くのは、「動画のどこか特定の部分に、具体的な問いを投げたい」ときです。漠然と「全部見て」ではなく、「2:30あたりで何が起きた？」「このデモで使われたツールは？」のように問いを絞るほど、少ないフレーム＝低コストで的確な答えが返ってきます。

3. claude-video の仕組み — 字幕優先の6ステップ

claude-videoの一番の設計思想は、「できるだけ安く、必要な分だけ」です。いきなり動画をまるごとダウンロードして全フレームを送るのではなく、字幕で済むなら字幕で済ませ、フレームが要るときも必要な範囲・必要な密度だけを抽出します。動画解析ツールというと「重い処理を一括で回す」印象を持たれがちですが、claude-videoはむしろ逆で、軽い処理から順に試し、足りない分だけを足していく発想で作られています。READMEが示す動作を、当サイト向けに図解します。

READMEの説明を順に追うと、次のようになります。

第一に、URLか動画パスと質問を渡す。URLはyt-dlpが対応するもの（YouTube・Loom・TikTok・X・Instagramほか数百）、ローカルなら .mp4 / .mov / .mkv / .webm。第二に、yt-dlpがまず字幕を確認する。transcript detailなら、字幕付きURLは動画をダウンロードせずに返ります。第三に、ffmpegがフレームを抽出する。efficient はキーフレームのみを高速デコード、balanced/token-burner はシーン変化フレームを優先し、不足時は尺に応じた均等サンプリングにフォールバックします。JPEGは既定で幅512px、Claudeが読める高さ上限（1998px）にクランプされます。

第四に、文字起こしは二系統。まずyt-dlpがソースからネイティブ字幕（手動/自動）を取得（無料・即時）。無ければ、16kHz/64kbpsのモノラルmp3（毎分約480kB）を抽出してWhisperへ——Groqの whisper-large-v3（推奨・安価で高速）かOpenAIの whisper-1。ここが賢いのは、課金の発生する音声処理を「最後の手段」に回している点です。字幕がある動画では音声を一切ダウンロードせず、テキストだけで済ませる。字幕が無い動画に限って、圧縮した軽量の音声をWhisperに送る。無駄な通信とAPI課金を発生させない設計思想が、ここにも一貫しています。

第五に、フレームと文字起こしがClaudeに渡される。スクリプトは各フレームを t=MM:SS マーカー付きで出力し、Claudeが並列にReadします。JPEGはそのまま画像としてコンテキストに展開されます。この「タイムスタンプ付きで並べる」ことが重要で、Claudeは文字起こしを先に読んで「ここを見て」「ご覧のとおり」といった発話者の合図を拾い、その瞬間のフレームに注目する、といった時間軸に沿った読み方ができます。第六に、Claudeが画面と音声を根拠に回答し、追質問が無ければ作業ディレクトリを掃除します。スクリプトは最後に作業ディレクトリのパスを表示するので、追加で質問したい場合はその素材を再利用できます。

この一連の流れで一貫しているのは、「一回きりの重い処理」ではなく「必要に応じて段階的に重くする」という発想です。まず一番軽い字幕だけを試し、足りなければフレームを足し、それでも足りなければ音声をWhisperへ——という順序が、そのままコストの順序になっています。動画解析というと「全部を解析してから答える」イメージを持ちがちですが、claude-videoはむしろ「質問に答えるのに必要な最小限だけを解析する」方向に振り切っています。

重複除去の設計は、細部までよく考えられています。しきい値はあえて低めに、しかも構造ではなく絶対的な明るさを測るように作られています。これにより、一行だけ変わったコードの差分、1行スクロールしたターミナル、色だけ違う2枚のフラットなスライドといった「わずかだが意味のある変化」は生き残ります。逆に、まったく同じ画面が続く区間だけがきれいに畳まれる。しかもフレーム予算のキャップは重複除去の後に適用されるため、予算は「異なる中身のフレーム」に対して使われます。実行後のFrames行には「14候補から6枚を採用（重複8枚を除去）」のように何が畳まれたかが表示され、常に動いている映像では何も捨てられず、本来払うだけのコストになります。地味ですが、この一手間が長尺・静止の多い動画でのトークン消費を大きく左右します。

4. detailモードとフレーム予算 — トークンを無駄にしない

claude-videoを賢く使う鍵は、detailモードという一本のダイヤルにあります。速度・トークンコストと視覚的な精度をトレードオフする設計で、READMEには実測値まで載っています（49分08秒・1280×720・英語自動字幕の画面録画に対する計測。ダウンロードは約37秒/76MBで3モード共有、抽出時間はローカルCPU）。

ここから読み取れる実務的な結論はこうです。まず字幕で足りるなら transcript が圧倒的に安い（フレームゼロ）。速さ重視なら efficient（約0.5秒）。既定の balanced はシーン変化を100枚まで拾うバランス型。長尺を漏れなく見たいときだけ token-burner でキャップを外します。画像トークンはAnthropicの (幅×高さ)/750 で計算され、既定512px幅の720pフレームは512×288で1枚あたり約197トークン。--resolution 1024 に上げると約4倍になるので、スライドやコードの文字を読む必要がある時だけ上げるのが正解です。

なぜここまでフレームを気にするのか——理由は単純で、トークンコストの大半をフレーム（画像）が占めるからです。文字起こしがどれだけ長くてもテキストトークンは比較的安価ですが、フレームは1枚ごとに画像として課金され、枚数がそのままコストに直結します。30分の動画をまばらにスキャンして曖昧な答えを得るくらいなら、的を絞った30秒の窓を密に見たほうが、安く・正確です。auto-fps（尺に応じた自動フレーム割り当て）のロジックは、まさにこの「コンテキスト予算をフレームで浪費しない」ために存在します。

もう一つの軸がフレーム予算（frame budget）です。トークンコストはフレームが支配するため、尺に応じて自動でフレーム数を割り当てる仕組みが入っています。

5. 導入方法 — Claude Code / Codex / claude.ai / 手動

claude-videoの導入は、ホストごとに一行で完結します。READMEの表を要点だけ整理します。

Claude Codeが最も手軽で、マーケットプレイス経由なので自動更新も効きます（更新は /plugin update watch@claude-video）。Codexなどでは Agent Skills のCLIが、検出したエージェントにスキルを入れてくれます。-g はユーザー全体へのグローバル導入、外せばプロジェクト単位です。-a codex -a cursor のように対象ホストを絞ったり、--copy（シンボリックリンク非対応のファイルシステム向けにファイルを複製）といったフラグも用意されています。claude.aiのWeb版で使う場合は、Capabilitiesで「コード実行とファイル作成」を先に有効化してください——スキルは内部で ffmpeg と yt-dlp を叩くため、これが無いと動きません。

開発者向けの手動導入も用意されています。リポジトリをクローンし、自己完結したスキルフォルダ（skills/watch）を各ホストのskillsディレクトリにシンボリックリンクすれば、作業ツリーを編集しながら常に最新の状態で試せます。claude.aiにアップロードする .skill バンドルは skills/watch/scripts/build-skill.sh で生成できます。リリースは vX.Y.Z タグをpushするとGitHub Actionsが dist/watch.skill を自動ビルドしてリリースに添付する仕組みで、バージョンは SKILL.md・.claude-plugin/plugin.json・.codex-plugin/plugin.json の間で揃える運用です。テストは python3 -m pytest -q で走り、ffmpegで合成したクリップを使うためネットワーク不要——このあたりの整備の丁寧さも、単なる思いつきのスクリプトではなく「配って使ってもらう」ことを前提に作られている証左だと言えます。

初回の /watch では scripts/setup.py --check が走り、ffmpeg / yt-dlp が無ければmacOSは自動で brew install、Linux/Windowsは正確なコマンドを提示します。Whisperキーは ~/.config/watch/.env（パーミッション0600）に雛形が作られます。以降のプリフライトは100ミリ秒未満の無言チェックなので、動作を邪魔しません。

実際の使い方は、URLか動画パスに質問を添えるだけです。

# 30秒地点で何が起きるかを聞く
/watch https://youtu.be/dQw4w9WgXcQ what happens at the 30 second mark?

# ローカルの画面録画でUIが壊れる箇所を特定
/watch ~/Movies/screen-recording.mp4 when does the UI break?

# 見たい区間だけを密に見る（トークン節約）
/watch https://youtu.be/abc --start 2:15 --end 2:45

字幕がある限りWhisperキーは不要で、公開動画の多くはこれでカバーできます。Whisperのフォールバックが要るのは、字幕がまったく無い動画（ローカルファイル、一部TikTok/Vimeo、字幕なしアップロード）に限られます。必要な能力とコストの関係は、READMEが表で整理しています。

さらに、細かな挙動は scripts/watch.py に渡すフラグで調整できます。とくに使用頻度が高いものを挙げると、--timestamps T1,T2,… は指定した各絶対時刻のフレームを追加で取得します（発話者が「ここを見て」と示した瞬間をピンポイントで押さえられる）。--resolution 1024 はフレーム幅を上げて画面の文字（スライド・ターミナル・コード）を読みやすくします。--max-frames N はフレーム上限を下げてトークン予算を締め、--whisper groq|openai はWhisperのバックエンドを固定、--out-dir DIR は作業ファイルの保存先を指定します。いずれも「必要な時だけ精度・範囲を足す」ためのつまみで、既定のままでも十分実用的です。

6. claude-video の注意点と、類似ツール claude-real-video との違い

導入前に押さえておきたい注意点は、主に精度とコストのトレードオフです。前述のとおり、キャップのあるモードでは10分超で精度が落ちるため区間指定が推奨されます。detailは一本のダイヤルで、既定はscene-aware・2fps上限・100枚キャップ。~/.config/watch/.env の WATCH_DETAIL で既定を変えられます。また、当然ながら権利上ダウンロードが許される動画にのみ使う——ここは利用者の責任範囲です。

実務的なモード選びの目安を一つにまとめると、こうなります。まず「要約や発言内容の確認」なら transcript で字幕だけを取り込むのが最安。「短い区間で画面を確認したい」なら区間指定（--start/--end）＋既定 balanced。「速く全体をざっと見たい」なら efficient。「長尺を漏れなく見たい」ときだけ token-burner——という順に、必要に応じて重くしていくのがコスト効率の良い使い方です。最初から token-burner で全編を最高解像度で流すのは、多くの場合オーバースペックです。問いを絞り、モードを絞り、必要になってから広げる。この順序を守るだけで、claude-videoは驚くほど安く動きます。

もう一つ、当サイトの読者から質問が多いのが「似たツールとの違い」です。実は同じ「Claudeに動画を見せる」というコンセプトのOSSに、claude-real-video（コマンド crv）があります。両者は目的こそ近いものの、設計思想が異なります。詳しくは claude-real-video（crv）解説｜どのLLMにも動画を「見せる」シーン検出＋重複除去ツール で扱いますが、要点を比較しておきます。

ざっくり言えば、Claude Code内で手軽に動画へ質問したいなら claude-video、どのLLMにも使い回せる汎用の抽出器が欲しい／ローカル処理でプライバシーを重視したいなら claude-real-video、という住み分けです。どちらも「AIが動画を見られない」という同じ問題に、別の角度から答えています。両者は競合というより、目的に応じて使い分ける補完関係だと捉えるのが実態に近いでしょう。

なお、detailモードの挙動には知っておくと得な細かな性質があります。READMEによれば、efficient（キーフレーム）は「速い抽出」を意味するのであって「フレームが少ない」わけではありません。動きの少ない映像ではキーフレームがシーン変化より多くなり、balanced より多くのフレームを返すこともあります。また各モードは、候補フレームを全体から検出したうえで、最初と最後を必ず残しつつ均等サンプリングでキャップまで絞るため、最後のフレームが常に動画の終端に来る（途中で切れない）よう設計されています。token-burner が balanced と分岐するのはキャップを超えた時だけで、シーン変化が100を超える高密度な映像では、balanced が100枚に間引く一方 token-burner は全部を残します。こうした挙動を理解しておくと、「なぜこのモードでこの枚数になったのか」に納得しながら使えます。

まとめ

本記事では、Claude Codeなどのコーディングエージェントに「動画を見る」能力を足すOSS、claude-video（/watch）を、公式リポジトリの一次情報にもとづいて解説しました。その本質は、動画をフレーム＋タイムスタンプ付き文字起こしというAIが読める素材に変換し、Claudeに「見て・聞いて」答えさせるパイプラインにあります。

設計の芯は「できるだけ安く、必要な分だけ」。字幕で足りるなら字幕で済ませ、フレームが要るときも重複を除去し、detailモードとフレーム予算で画像トークンを制御します。Claude Code・Codex・Cursorなど50以上のホストに導入でき、字幕がある限り追加のAPIキーも不要。他人の動画の構成分析、画面録画からのバグ診断、長尺の要約——「動画をスクラブして探す時間」を、コマンド一つの質問に置き換えてくれます。同じ課題に別アプローチで挑む claude-real-video と読み比べれば、自分の用途に合うほうが見えてくるはずです。

導入は一行で済み、初回に ffmpeg と yt-dlp が自動で整うため、試すコストはほぼゼロです。まずは手元の短い画面録画に対して /watch <ファイル> 何が起きてる？ と聞いてみる——それだけで、「AIが動画を見る」体験がどれほど作業を変えるかが実感できるはずです。動画が情報源として扱えるようになると、これまで「見るしかなかった」多くの素材が、質問し、要約し、引用できる知識に変わります。

参照ソース

・claude-video（bradautomates 公式リポジトリ） — 本記事が解説した一次情報。/watchの仕組み・detailモード・導入手順のすべて
・Agent Skills（skills CLI・50+ホスト対応） — Codex/Cursor/Copilot等へスキルを配布する仕組み
・yt-dlp（対応サイト一覧・公式リポジトリ） — claude-videoが動画取得と字幕取得に用いるダウンローダ