「Claudeはウェブページを読めるし、スクリプトも動かせるし、リポジトリも巡回できる。でも標準では、動画を見ることだけはできない」——これは claude-video のREADMEが冒頭で突きつける指摘です。YouTubeのリンクを貼っても、AIはタイトルから中身を推測するか、画面上の情報の9割が抜け落ちた文字起こしを引っ張ってくるくらいしかできません。
claude-video（コマンド名は /watch）は、この穴をクローンして使えるオープンソースのスキルとして埋めます。URLやローカル動画を渡すと、字幕を最優先で取り込み、シーン変化に合わせてフレームを抜き出し、必要なら文字起こしして、Claudeが実際に画面を見て・音声を聞いたうえで答えます。GitHubのスター数は4,000超で、Claude CodeだけでなくCodexやCursorなど50以上のエージェントで使えます。
30秒でわかるclaude-video
- ・Claude Codeなどに「動画を見る」能力を足すMITライセンスのスキル。URL・ローカル動画に対応
- ・仕組みは字幕優先 → 必要な分だけダウンロード → シーン検出でフレーム抽出 → 文字起こし → Claudeが各フレームを画像として読む
- ・コストの大半はフレーム（画像トークン）。detailモードと区間指定で無駄を削る
- ・50以上のホストに導入可能。字幕がある限りWhisperキーは不要
Claude Code全体の使い方は Claude Code｜2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引き をご覧ください。
claude-videoとは：Claudeが動画を「見られない」問題を解く
bradautomates/claude-video は、AI活用の発信（YouTube @bradbonanno）とビジネス向けの自動化構築（Solaris Automation）を手がけるBrad Bonanno氏が公開する、MITライセンスのOSSです。中核は skills/watch/ という自己完結したスキルで、各種エージェントに入れると /watch が使えるようになります。
発想は「見られないなら、見られる形に変換してから渡す」です。動画をフレーム（静止画）の列とタイムスタンプ付きの文字起こしに分解し、Claudeがもともと持つ「画像を読む（Read）」「テキストを読む」操作に落とし込みます。新しいモデルを足すわけではないので軽量で、特定のモデルに縛られません。本質は「動画を、AIが読める素材（フレーム＋文字起こし）に変換するパイプライン」で、ここを押さえるとdetailモードやフレーム予算の話がすべてつながります。
中身は、すべてのホストで共通の契約書である SKILL.md と、watch.py を入口にダウンロード・フレーム抽出・文字起こし・Whisperクライアント・設定・セットアップが分かれた純Pythonの scripts/ です。依存はほぼ標準ライブラリで、フォルダごとコピーされるのでどのホストでも挙動が変わりません。
READMEが挙げる使いどころは次のとおりです。
| 使いどころ | 例 |
|---|---|
| 他人のコンテンツを分析 | /watch <バズ動画のURL> どんなフックで始めた？。広告クリエイティブ、競合のローンチ動画、ポッドキャストの入り |
| 動画からバグを診断 | /watch bug-repro.mov 何が起きてる？。不具合の出るフレームを特定し、画面で何が起きているかを説明 |
| 動画を要約 | /watch <長い動画> これ要約して。構成・要点・実際に語られた/映されたこと |
| 更新動画から誇張を削ぐ | /watch <ローンチ動画> 実際に何が新しい？誇張は抜きで |
| プレイリストをノートに | シリーズに一本ずつ走らせ、動画ごとの要約をファイル化して検索できるノート集にする |
共通するのは、画面と音声の中身に自然文で質問できることです。これまで「座って再生するしかない、検索できない塊」だった登壇録画・製品デモ・チュートリアルが、ドキュメントやリポジトリと同じ土俵に乗ります。代替するのは、早送りで探すスクラブ作業と、画面を人が見て説明する手間です。問いを「2:30あたりで何が起きた？」「このデモで使われたツールは？」のように絞るほど、少ないフレーム＝低コストで的確な答えが返ります。権利上ダウンロードが許されない動画に使うのは論外で、長尺の逐一分析はコストと精度の両面で不利です。
claude-videoの仕組み：字幕優先で、必要な分だけ
SUBTITLES FIRST/watch の中身
軽い処理から順に試し、足りない分だけ重くする
-
字幕を確認
あれば DL 不要のことも
-
必要な分だけDL
yt-dlp
-
フレーム抽出
キーフレーム / シーン変化
-
重複を除去
直近の採用フレームと比較
-
文字起こし
字幕優先・無ければ Whisper
-
Claude が Read
t=MM:SS つきで並列に
| 段 | 何をするか |
|---|---|
| 入力 | yt-dlpが対応するURL（YouTube・Loom・TikTok・X・Instagramほか数百）か、.mp4 / .mov / .mkv / .webm |
| 字幕の確認 | transcript detailなら、字幕付きURLは動画をダウンロードせずに返る |
| フレーム抽出 | efficient はキーフレームのみを高速デコード、balanced / token-burner はシーン変化を優先し、不足時は尺に応じた均等サンプリング。JPEGは既定で幅512px、高さはClaudeが読める上限（1998px）にクランプ |
| 文字起こし | まずネイティブ字幕（手動/自動・無料・即時）。無ければ16kHz/64kbpsのモノラルmp3（毎分約480kB）をGroqの whisper-large-v3（推奨）かOpenAIの whisper-1 へ |
| 回答 | 各フレームを t=MM:SS 付きで出力し、Claudeが並列にRead。追質問が無ければ作業ディレクトリを掃除（パスは最後に表示されるので再利用もできる） |
課金の発生する音声処理は最後の手段です。タイムスタンプ付きで並べるので、Claudeは文字起こしの「ここを見て」といった合図を拾い、その瞬間のフレームに注目できます。
重複フレーム除去（dedup）も既定で効きます。各フレームを16×16のグレースケール縮小版にし、「直近で採用したフレーム」との平均絶対差がしきい値（2.0）以下なら捨てます。比較相手を直前ではなく直近の採用フレームにすることで、ゆっくりしたフェードも取りこぼしません。しきい値は低めで、構造ではなく絶対的な明るさを測るので、一行だけ変わったコード差分、1行スクロールしたターミナル、色だけ違うスライドは生き残ります。フレーム予算のキャップは除去の後にかかり、実行後のFrames行には「14候補から6枚を採用（重複8枚を除去）」のように表示されます。--no-dedup で無効化できます。
claude-videoのdetailモードとフレーム予算
detailモードは、速度・トークンコストと視覚的な精度をトレードオフするダイヤルです。READMEには実測値が載っています（49分08秒・1280×720・英語自動字幕の画面録画。ダウンロードは約37秒/76MBで3モード共有、抽出時間はローカルCPU）。
IMAGE TOKENSdetail モード別
コストを決めるのはフレーム（画像トークン）。字幕だけなら0
| モード | エンジン | フレーム | キャップ | 抽出時間 | 画像トークン概算 |
|---|---|---|---|---|---|
transcript |
字幕のみ | 0 | — | 約4.5秒 | 0（本文約26.6kトークン） |
efficient |
キーフレーム | 50 | 50 | 約0.5秒 | 約9.8k |
balanced（既定） |
シーン変化 | 100 | 100 | 約20.9秒 | 約19.7k |
token-burner |
シーン変化 | 116 | 上限なし | 約21.0秒 | 約22.8k |
画像トークンはAnthropicの (幅×高さ)/750 で計算され、既定512px幅の720pフレーム（512×288）は1枚あたり約197トークン。--resolution 1024 で約4倍になるので、スライドやコードの文字を読む必要がある時だけ上げます。30分をまばらにスキャンして曖昧な答えを得るより、的を絞った30秒を密に見るほうが安く正確です。
| 尺 | 既定のフレーム予算 | 得られるもの |
|---|---|---|
| 30秒以下 | 約30枚 | 密（ほぼ全ての要所） |
| 30秒〜1分 | 約40枚 | まだ密 |
| 1〜3分 | 約60枚 | 快適 |
| 3〜10分 | 約80枚 | まばらだが実用 |
| 10分超 | 100枚（キャップ時） | 「まばらなスキャン」警告 → 区間を絞って再実行推奨 |
長尺は「区間指定」がほぼ必須
- ・キャップのあるモード（efficient・既定のbalanced）では、10分を超えるとフレームが全体に薄く広がり精度が落ちる
- ・見たい箇所が決まっているなら
--start/--end。集中モードは1秒あたりの予算が上がる（上限2fps） - ・長尺を丸ごと精密に見たいときだけ token-burner。権利上ダウンロードが許される動画にのみ使うのは利用者の責任
モードには知っておくと得な性質もあります。efficient は「速い抽出」であって「フレームが少ない」わけではなく、動きの少ない映像ではキーフレームがシーン変化より多くなり、balanced より多く返すこともあります。各モードは候補を全体から検出し、最初と最後を必ず残して均等サンプリングでキャップまで絞るので、最後のフレームは常に動画の終端に来ます。token-burner が balanced と分かれるのは、シーン変化が100を超えたときだけです。既定はscene-aware・2fps上限・100枚キャップで、~/.config/watch/.env の WATCH_DETAIL で変えられます。
選ぶ順番は、要約や発言の確認なら transcript、短い区間の画面確認なら区間指定＋balanced、速くざっと見るなら efficient、長尺を漏れなく見るときだけ token-burner。必要になってから広げます。
claude-videoの導入方法：Claude Code / Codex / claude.ai
| 導入先 | コマンド／手順 |
|---|---|
| Claude Code | /plugin marketplace add bradautomates/claude-video → /plugin install watch@claude-video（更新は /plugin update watch@claude-video） |
| Codex / Cursor / Copilot / Gemini CLI ほか50+ | npx skills add bradautomates/claude-video -g（-g を外すとプロジェクト単位。-a codex -a cursor で対象を絞る、--copy でリンクの代わりに複製） |
| claude.ai（Web） | 最新リリースから watch.skill をダウンロード → 設定 → Capabilities → Skills → +。先に「コード実行とファイル作成」を有効化（内部で ffmpeg と yt-dlp を叩くため） |
| 手動 / 開発 | git clone して skills/watch を各ホストのskillsディレクトリにシンボリックリンク |
初回の /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
| 能力 | 必要なもの | コスト |
|---|---|---|
| ダウンロード＋ネイティブ字幕 | yt-dlp ＋ ffmpeg |
無料 |
| Whisperフォールバック（推奨） | GroqのAPIキー（whisper-large-v3） |
安い・速い |
| Whisperフォールバック（代替） | OpenAIのAPIキー（whisper-1） |
標準料金 |
| Whisperを完全無効化 | --no-whisper |
無料・字幕なしはフレームのみ |
Whisperが要るのは、字幕がまったく無い動画（ローカルファイル、一部TikTok/Vimeo、字幕なしアップロード）だけです。scripts/watch.py のフラグでは、--timestamps T1,T2,…（指定時刻のフレームを追加）、--resolution 1024（画面の文字を読みやすく）、--max-frames N（上限を下げる）、--whisper groq|openai（バックエンド固定）、--out-dir DIR（作業ファイルの保存先）がよく使われます。
開発者向けには、.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で合成したクリップを使うのでネットワーク不要）です。
claude-videoとclaude-real-videoの違い
同じ「Claudeに動画を見せる」コンセプトのOSSに claude-real-video（コマンド crv）があります。詳しくは claude-real-video（crv）解説｜どのLLMにも動画を「見せる」シーン検出ツール で扱っています。
TWO WAYS TO WATCH似たツールとの違い
Claude Code内で聞くならclaude-video、どのLLMにも渡すなら crv
claude-video（/watch）
スキル / プラグイン
- /watch URL 質問 でその場で回答
- Claude 中心・50以上のホスト
- detail 4段・字幕優先
claude-real-video（crv）
pip 製 CLI ＋スキル
- frames・文字起こし・MANIFEST を出力
- 任意の LLM に貼って使う
- スライディングウィンドウで重複除去
| 観点 | claude-video（/watch） | claude-real-video（crv） |
|---|---|---|
| 形態 | Claude Code等のスキル/プラグイン | pip製CLI＋Claude Codeスキル |
| 主な使い方 | /watch URL 質問 でその場で回答 |
crv URL で frames/文字起こし/MANIFESTを出力 |
| 想定モデル | Claude中心（50+ホスト） | 任意のLLM（貼り付けて使う） |
| フレーム選択 | detail 4段（字幕/キーフレーム/シーン変化） | シーン変化＋密度フロア |
| 重複除去 | 直近採用フレームとの明度差 | スライディングウィンドウ（A-B-A再送を防ぐ） |
| 立ち位置 | Claude Codeネイティブ・字幕優先で手軽 | LLM非依存・ローカル処理でプライバシー重視 |
Claude Code内で手軽に動画へ質問したいなら claude-video、どのLLMにも使い回せる抽出器が欲しい／ローカル処理でプライバシーを重視したいなら claude-real-video、という住み分けです。「見せる」ではなく「作る・編集する」側をClaude Codeに任せたいなら、claude-code-video-toolkit - Claude Codeで動画編集を自動化 が別系統のアプローチになります。
まずは手元の短い画面録画に /watch <ファイル> 何が起きてる？ と聞き、必要に応じて範囲やdetailを広げるのが、コストを抑えながら試す近道です。
参照ソース
・claude-video（bradautomates 公式リポジトリ） — 本記事が解説した一次情報。/watchの仕組み・detailモード・導入手順のすべて
・Agent Skills（skills CLI・50+ホスト対応） — Codex/Cursor/Copilot等へスキルを配布する仕組み
・yt-dlp（対応サイト一覧・公式リポジトリ） — claude-videoが動画取得と字幕取得に用いるダウンローダ
