/watchでClaudeに動画を見せるclaude-videoの処理経路と費用管理

タイトルではなく画面と音声を渡す/watch

claude-videoは、Claudeに動画を視聴させるための/watch commandを追加するprojectです。READMEでは、YouTube URLやlocal pathを入力し、質問を添えると、字幕を取得し、必要なvideoをdownloadし、frameを抽出し、timestamp付きtranscriptを作り、frameとtranscriptをClaudeへ渡すと説明されています。

例として、/watch https://youtu.be/dQw4w9WgXcQ what happens at the 30 second mark?が示されています。Claudeはframeをimageとして、transcriptをtextとして読み、titleからの推測ではなく、画面に表示された内容と音声に基づいて回答するという位置づけです。動画の要約、画面録画のbug調査、広告やpodcastの構成確認、playlistからのnote作成などの用途がREADMEに挙げられています。

これはvideo全体を人間と同じ条件で無制限に見る機能ではありません。どのframeを残すか、字幕があるか、音声認識が必要かで結果と費用が変わります。質問する時間帯が決まっているなら、全編を渡す前に対象区間を固定し、回答の根拠となるframeとtimestampを保存します。

Claude CodeとAgent Skillsへの導入

Claude Codeでは、READMEがmarketplaceを追加し、watch@claude-videoをinstallする手順を推奨しています。/plugin marketplace add bradautomates/claude-videoの後に/plugin install watch@claude-videoを実行する流れです。Codex、Cursor、Copilot、Gemini CLIなど50以上のAgent Skills hostでは、npx skills add bradautomates/claude-video -gでglobal installし、-gを外せばproject単位にできます。

claude.ai webやmanual installの選択肢もREADMEのInstall節へ案内されています。hostごとにskill bundleの置き場所、更新方法、実行権限が異なるため、同じcommandがすべての環境で同じ動きをすると仮定しません。global installを使う場合は、全projectへ機能が見える範囲と更新担当を明確にし、project installでは対象repositoryと共有範囲を記録します。

初回実行時にmacOSではbrewでyt-dlpとffmpegをinstallし、LinuxとWindowsでは必要なcommandを表示するとREADMEは説明しています。zero configという表現は、外部依存や権限が不要という意味ではありません。取得したbinaryの版、実行user、PATH、installされた場所を確認し、動画を扱う環境へ勝手に追加されないようにします。

yt-dlpからClaude Readまでの七段階

処理の最初は、yt-dlpが対応するURLまたはlocal pathを受け取ることです。READMEはYouTube、Loom、TikTok、X、InstagramなどのURLと、mp4、mov、mkv、webmのlocal fileを例に挙げています。次にyt-dlpがcaptionを先に確認します。transcript detailでcaptionが取得できれば、videoをdownloadせずに返せると説明されています。

captionがない場合やWhisperへaudioを渡す場合は、runに必要な範囲をdownloadします。ffmpegは選択されたdetailに応じてframeを抽出し、efficientではkeyframe、balancedとtoken-burnerではscene changeを優先します。frameが少なすぎるときは、durationを考慮したuniform samplerへfallbackします。JPEGは既定で幅512px、Claude Readとの互換性のため高さ1998pxに制限されます。

transcriptは、sourceのnative captionまたはWhisper fallbackから作られます。fallbackではmono、16kHz、64kbpsのmp3を作り、Groqのwhisper-large-v3またはOpenAIのwhisper-1へ送るとREADMEにあります。最後にframe pathへt=MM:SS markerを付け、timestamp付きtranscriptと一緒にClaudeへ渡します。処理終了時はworking directoryを表示し、follow-upがなければClaudeが削除します。

字幕優先とWhisper fallbackの境界

公開videoの多くはcaptionが使えるため、字幕がある場合は無料で処理できるとREADMEは説明しています。manual captionとauto-generated captionのどちらを取得したかを記録し、captionの欠落、誤変換、話者の混同、画面上の文字との不一致を確認します。字幕があることは、音声内容が完全に文字化されていることの保証ではありません。

字幕trackがないvideo、local file、一部のTikTok、一部のVimeo、一部のYouTube uploadではWhisper fallbackが必要になる場合があります。Groq API keyまたはOpenAI API keyを用意し、READMEではGroqをpreferredとして挙げています。keyを設定したら、どのbackendへaudioが送られるか、audio fileの保存時間、失敗時の再試行、API利用料を別に管理します。

--whisperでtranscriptを無効にすることもできます。画面だけを確認したい場合の選択肢ですが、音声の説明や会話を根拠にする質問には向きません。caption、Whisper、no-whisperを同じ結果として比較せず、質問が求める根拠が画面なのか音声なのかを先に分けます。

frame budgetが回答品質と費用を決める

READMEは、token costの多くがframeから生じると説明しています。既定のframe budgetは、30秒以下で約30枚、30秒から1分で約40枚、1分から3分で約60枚、3分から10分で約80枚です。10分を超える動画はcapped modeで100枚となり、sparse scan warningが表示されます。

全編を粗く見るより、質問の時間を絞る方が適切な場合があります。利用者が2:30付近、最後の30秒、0:45から1:00のようにmomentを指定した場合は、--startと--endを使います。focused modeは秒あたりのbudgetを密にし、上限は2fpsです。長いvideoの全体像と特定場面の確認を同じ設定で行わず、質問に必要な範囲を選びます。

token-burnerは上限なしでscene-change frameを保持するモードとして説明されていますが、画像tokenを多く使います。費用を抑えたい場合はtranscriptやefficientを入口にし、見落としが疑われる区間だけbalancedやtoken-burnerで再実行します。各実行のduration、detail、frame数、API利用、回答の根拠を記録し、便利さと費用を同時に評価します。

重複frameを落とす計算

scene changeやkeyframeで選んでも、同じ画面が長く続くvideoでは近いframeが多数残ります。READMEのdedupは全frame modeで既定有効で、--no-dedupで無効にできます。90秒同じslideを表示するscreen recordingのような素材では、重複frameを減らし、異なる画面へbudgetを使う目的です。

処理は、ffmpegで各JPEGを16×16のgrayscale thumbnailへ縮小し、その後はPythonの標準libraryだけで計算します。各frameと、直前に保持したframeとのmean absolute differenceを計算し、brightness changeが0から255の尺度でthreshold 2.0以下ならnear-duplicateとして破棄します。保持したframeを次の比較基準にすることで、少しずつ変化するfadeも判定対象になります。

この方法は画像の構造そのものではなくabsolute brightnessを測ります。READMEは、一行のcode差分、terminalのscroll、色だけが違うflat slideも残る場合があると説明しています。Frames行には、選択数、候補数、破棄したnear-duplicate数が表示されます。動きの多いvideoでは何も落ちず、dedupが費用を減らすとは限りません。

efficient、balanced、token-burnerの選択

detail modeは、frameの取り方と処理量を調整します。efficientはkeyframeだけを使い、短時間で全体を粗く確認する経路です。balancedはscene-change frameを優先し、token-burnerは同じ考え方で上限を外して、場面の変化を多く残します。transcriptはframeを生成せず、captionまたはWhisperによる音声の文字起こしを中心にします。

READMEには49分08秒、1280×720、英語auto captionのYouTube videoを使った測定例があります。transcriptは約4.5秒で約26.6k text token、efficientは約0.5秒で50 frameと推定9.8k image token、balancedは約20.9秒で100 frameと約19.7k token、token-burnerは約21.0秒で116 frameと約22.8k tokenと記載されています。これらはREADMEの特定条件における測定で、すべてのvideoの所要時間や費用ではありません。

既定の512px幅では720p frameが512×288となり、1枚あたり約197 tokenという計算も示されています。低motionではkeyframeの方がscene cutより多くなる場合があるため、efficientがbalancedよりframeを多く返すこともあります。mode名の印象ではなく、質問、画面の変化、文字の細かさ、許容するtoken量で選びます。

MITライセンスと安全な試行範囲

claude-videoのlicenseはMITです。利用、改変、再配布を考える場合は、採用版のLICENSE、yt-dlp、ffmpeg、Whisper provider、Claudeの利用条件、取得するvideoの著作権と公開範囲を別々に確認します。MITは、videoの再利用許可、API dataの保持、OCRや音声認識の精度、security、supportを保証しません。

素材のrelease metadataにはv0.2.0、v0.1.3、v0.1.2が記録されています。取得日時は2026年8月29日で、GitHub metadataにはmain branch、16392 stars、1627 forks、135 open issuesがあります。これらは公開活動と取得時点の情報であり、処理品質や将来の互換性を保証する数字ではありません。

このskillが向くのは、videoの視覚情報と音声をClaudeへ渡し、特定場面の質問、要約、bug調査、構成分析を行いたい利用者です。最初は権利を確認できる短いlocal videoで、caption、efficient、balanced、dedup、out-dir、削除を順番に試します。次にURL、Whisper、長時間videoを検討し、frame数、transcriptの誤り、API key、保存先、費用、回答根拠を記録できた範囲だけを日常運用へ広げます。

編集部の結論

claude-videoは、動画のタイトルや説明だけでなく、画面frameと音声transcriptをClaudeへ渡して内容を質問したい利用者向けのAgent Skillです。READMEはYouTubeなどのURLとlocal file、字幕優先、Whisper fallback、scene-awareなframe抽出、重複除去、複数のdetail modeを説明していますが、長い動画ほどframe budgetと画像tokenの管理が必要です。導入前に対象動画の権利、取得経路、API key、保存先、detail、startとend、削除手順を決め、短い動画で処理結果と費用を確認してください。

公式情報源

1. Official README
2. Project repository
3. Release notes