watch-video

動画を視聴する

Claude は動画を直接ストリーミングできません。このスキルでは、代わりに Python パイプラインを使用します。これは scripts/ の下にある bradautomates/claude-video からベンダー提供されたもので、動画をダウンロードし、ffmpeg で自動スケーリングした JPEG フレームを抽出し、タイムスタンプ付きの文字起こし（まずネイティブ字幕を使用し、利用できない場合は Whisper API にフォールバック）を取得して、すべてのフレームパスを列挙した Markdown レポートを出力します。Claude は各フレームを Read で読み込み、話されたテキストと照合して、構造化されたメモファイルを作成します。

呼び出すタイミング

スラッシュコマンド専用です。 ユーザーが /watch-video と文字どおり入力した場合にのみ、このスキルを実行してください。これが唯一のトリガーです。

次の場合は呼び出さないでください。

• 「この動画を見て」「これを要約して」「この YouTube 動画のメモを取って」「このリールを分析して」といった何気ない表現
• 質問とともに貼り付けられた YouTube URL のみ（「この動画にはどんな役立つヒントがある？」＋ URL）
• 明示的な /watch-video コマンドを含まない、動画に関する自然言語での依頼

スラッシュコマンドなしで YouTube について質問された場合のデフォルト： 利用可能な最速の方法で文字起こしを取得します。YouTube ページを取得する、yt-dlp の字幕を使う、文字起こしサイトを利用するなどして内容を確認し、それをもとに回答します。ユーザーが /watch-video で明示的に求めない限り、フレーム抽出パイプラインは過剰です。

自動トリガー動作にしたい場合は、上の description: 行を、Claude が起動するキーワードに合わせて編集してください（例：「ユーザーが Claude に動画の視聴、分析、またはメモの作成を求めた場合に使用します」）。このリポジトリでは、長い動画で意図せずトークンを消費しないよう、デフォルトでスラッシュコマンドのみをトリガーにしています。

依存関係

• ffmpeg + ffprobe が PATH 上にあること — フレームと音声の抽出に使用します
• yt-dlp が PATH 上にあること — ダウンロードと字幕の取得に使用します
• Python 3.9+ — 同梱スクリプトでは from __future__ import annotations を使用しているため、3.9 で動作します
• 任意： ネイティブ字幕がない動画では Whisper API キーが必要です。GROQ_API_KEY（推奨 — 低コストかつ高速で、whisper-large-v3 を実行）または OPENAI_API_KEY を ~/.config/watch/.env に設定します。どちらも設定しなくても字幕付き動画は問題なく動作しますが、字幕のない動画ではフレームのみが返されます。

python scripts/setup.py --check を実行して依存関係を確認するか、python scripts/setup.py を実行して .env を作成し、バイナリを確認します。macOS では、インストーラーが Homebrew を使って不足しているバイナリを自動的にインストールします。Linux/Windows では、具体的なインストールコマンドが表示されます。

パイプライン

処理は scripts/watch.py で行われます。動画をダウンロードし、フレームを抽出し、文字起こしを行い、すべてのフレームパスを列挙した Markdown レポートを標準出力に出力します。パイプラインは動画の長さに応じてフレーム数の上限を自動調整するため（上限 100 フレーム／秒間 2 フレーム）、間隔を手動で調整する必要はありません。

python scripts/watch.py "<youtube-url-or-local-path>" [flags]

知っておくと便利なフラグ：

• --start T / --end T — 範囲を指定します（SS、MM:SS、または HH:MM:SS）。指定した範囲内では fps が自動的に高くなります。特定の瞬間について質問された場合や、10 分を超える動画でユーザーの質問が一部分に関する場合に使用します。
• --max-frames N — トークン予算を抑えるために上限を下げます（デフォルトは 80、最大 100）。
• --resolution W — フレームの幅をピクセル単位で指定します（デフォルトは 512。画面上のテキストが読めない場合のみ 1024 に上げます）。
• --whisper groq|openai — Whisper のバックエンドを指定します（デフォルトでは両方のキーがある場合、Groq を優先します）。
• --no-whisper — 字幕がない場合、文字起こしを完全にスキップします。フレームのみを出力します。
• --out-dir DIR — 作業ファイルの保存先を指定します（デフォルトは自動生成された一時ディレクトリ）。

自動 fps の上限（動画全体モード）：

• ≤30s → 最大 30 フレーム
• 30s～1min → 約 40 フレーム
• 1～3min → 約 60 フレーム
• 3～10min → 約 80 フレーム
• >10min → まばらに 100 フレーム（警告を表示します。--start / --end の使用を検討してください）

手順ごとのワークフロー

1. パイプラインを実行する

フラグなしでのデフォルトの呼び出し：

python scripts/watch.py "<source>"

長い動画で、ユーザーが特定の場面について質問した場合は、--start／--end を指定します。

python scripts/watch.py "<source>" --start 2:15 --end 2:45

スクリプトはすべてのファイルを一時作業ディレクトリに書き込み、Markdown レポートを標準出力に出力します。標準出力を取得してください。次の内容が含まれています。

• ヘッダー（タイトル、投稿者、再生時間、文字起こしのソース：captions／whisper (groq)／whisper (openai)／none available）
• ## Frames セクションと、- \` (t=MM:SS)` 形式の行
• ## Transcript セクションと、[MM:SS] text... 形式の行
• レポートの末尾にある Work dir: <path>

2. すべてのフレームを読む

一覧にあるすべてのフレームパスを、1 つのメッセージで読み込みます（Read ツールを並列で呼び出します）。Read ツールは JPEG を画像として表示します。各フレームのファイル名とレポートに記載された t=MM:SS から、そのフレームが発生した時刻を確認し、同じタイムスタンプの文字起こしの行と各フレームを対応付けます。

非常に長い動画（10 分超、疎なモード）の場合、上限はすでに 100 フレームに設定されているため、すべて読み込んで問題ありません。

3. 要約を書く

デフォルトの出力ファイル：<work-dir>/<slug>-notes.md。ユーザーが「メモを永続的な場所に保存して」と言った場合は、保存先を尋ねます。

Markdown は次のような構成にします。

# <Title>

**Source:** <URL or local path>
**Duration:** <mm:ss>
**Uploader:** <if from YouTube>
**Transcript source:** <captions / whisper (groq) / whisper (openai) / none>

## One-line summary
<≤20 words — the core claim or hook of the video>

## TL;DR
<3–5 bullet points capturing the main arguments, moments, or beats>

## Timeline
- **[00:00]** <what's happening visually + the key line being said>
- **[00:15]** ...
<one row per meaningful beat, not per frame>

## Key quotes
> "<verbatim quote>" — [mm:ss]

## Visual notes
<what the video shows that the transcript alone would miss — setting, B-roll, on-screen text, graphics, transitions, subject's emotion>

## Takeaways (optional)
<Only include if the content is directly relevant to the user's domain or goals. Omit otherwise.>

4. クリーンアップする

.md ファイルを書き込んだ後、作業ディレクトリを削除します（サイズの大きい、ダウンロード済みの動画とフレームが含まれています）。スクリプトはレポートの末尾に Work dir: <path> を出力します。そのパスを rm -rf に渡します。

ユーザーが一時ディレクトリ以外の --out-dir を指定した場合は、削除する前に確認してください。

よくある落とし穴

• YouTube Shorts／年齢制限付き／メンバー限定 — yt-dlp が失敗することがあります。標準エラー出力をそのまま伝え、黙って再試行しないでください。
• 字幕なし + Whisper キーなし — レポートには Transcript: none available と記載され、setup.py が示されます。Whisper を使うには ~/.config/watch/.env に Groq キーを追加するか、フレームのみの場合は --no-whisper を使えることをユーザーに伝えてください。
• 音声トラックのないローカルファイル — Whisper による抽出はエラーを適切に処理して終了します。フレームのみの場合は --no-whisper を使います。
• 非常に長い動画（30 分超） — 実行する前にユーザーに確認してください。パイプラインは上限を 100 フレームに設定しているため処理量は限られますが、60 分の動画を 100 フレームで疎にスキャンしても、あまり役に立ちません。ほとんどの場合、特定のセクションに絞って実行するほうが適切です。
• Groq での Cloudflare 403 — whisper.py はすでにカスタム User-Agent を設定し、Cloudflare によるデフォルトの Python User-Agent のブロックを回避します。403 が表示された場合は、それが失敗の原因です。
• Groq から OpenAI への自動フォールバックはありません — スクリプトは各実行の開始時に Whisper バックエンドを 1 つ選択し（キーが設定されていれば Groq、そうでなければ OpenAI）、そのバックエンドを使い続けます。Groq でレート制限が発生した場合、スクリプトは Groq で 2 回再試行した後、エラーになります。代わりに OpenAI を使うには、--whisper openai を指定します。

してはいけないこと

• タイトルやサムネイルをもとに内容を想像して、動画を「見た」ことにしないでください。パイプラインが失敗した場合は、その旨を伝えてください。
• 実際にフレームを読む前に要約を書かないでください。文字起こしだけでは視覚的な文脈（B ロール、画面上のテキスト、感情、グラフィック、トランジション）が把握できません。
• クリーンアップを省略しないでください。フレームの出力ファイルとダウンロードした動画はサイズが大きくなります。
• 動画 URL に対して自動的に実行しないでください。スラッシュコマンドのみです。「呼び出すタイミング」を参照してください。

エンジンの帰属表示

scripts/ 内のパイプラインスクリプトは、bradautomates/claude-video（MIT）からベンダー提供されています。上流ライセンスの全文については、THIRD_PARTY_NOTICES.md を参照してください。