claude-video

bradautomates/claude-video — Agent Skill /watch · yt-dlp + ffmpeg + captions/Whisper · v0.2.0

1 — 概要

何をするか

エージェントに動画入力を足すスキル。URL（yt-dlp が扱えるサイト）またはローカルパス（.mp4 / .mov / .mkv / .webm）を渡し、キャプションまたは Whisper のタイムスタンプ付き文字起こしと、JPEG フレームを揃えてから Read で画像を読む。

/watch

スラッシュコマンド

detail モード

50+

Agent Skills ホスト

MIT

ライセンス

/watch https://youtu.be/dQw4w9WgXcQ what happens at the 30 second mark?

ゼロ設定で開始: 初回に setup.py が ffmpeg / yt-dlp を確認する。macOS は Homebrew で自動インストール。公開動画の多くはネイティブキャプションだけで足り、Whisper API キーはキャプション無しのときだけ必要。

典型ユース

他人の動画のフック・構成分析
画面録画からのバグ診断
長尺の要約・ハイプ除去
プレイリストをノート化

製品の境界

本体は CLI ではなくスキル契約 SKILL.md
scripts/watch.py は実装エントリ
自己完結フォルダ skills/watch/ を単位で配布
ハーネス固有の CLAUDE_SKILL_DIR に依存しない

2 — 処理の流れ

ランタイム

ユーザーがソースと質問を渡すと、エージェントは preflight → watch.py → 全フレーム Read → 回答 → 作業ディレクトリ掃除、の順で動く。

setup --check → download / captions → frames + dedup → transcript → Read frames → answer + cleanup

flowchart TD
  A["/watch source + question"] --> B["setup.py preflight"]
  B --> C{"captions?"}
  C -->|yes + transcript detail| D["report without video download"]
  C -->|need pixels / no captions| E["yt-dlp download"]
  E --> F["ffmpeg frames"]
  F --> G["dedup near-duplicates"]
  C -->|no captions| H["Whisper audio"]
  D --> I["timestamped transcript"]
  G --> I
  H --> I
  I --> J["Claude Read each JPEG"]
  J --> K["grounded answer"]
  K --> L["rm work dir if done"]

キャプション優先: transcript detail ではキャプション付き URL なら動画ダウンロードをスキップできる。
フレーム抽出: efficient はキーフレーム、balanced / token-burner はシーン変化（不足時は均一サンプリング）。既定幅 512px、高さ上限 1998px。
文字起こし: ネイティブ字幕 → 失敗時は mono 16 kHz 64 kbps mp3 を Whisper（Groq 優先、OpenAI 代替）。
回答: フレームパスに t=MM:SS、トランスクリプトにタイムスタンプ。全フレームを並列 Read。

3 — Detail モード

速度とトークンのダイヤル

--detail または ~/.config/watch/.env の WATCH_DETAIL。既定は balanced。測定例は 49:08 / 1280×720 の画面録画（英語 auto-captions）に対する実測。

Mode	Engine	Cap	抽出時間（例）	画像トークン目安
`transcript`	なし（captions）	—	~4.5 s（yt-dlp 1 回）	0（テキストのみ）
`efficient`	keyframe	50	~0.5 s	~9.8k
`balanced`	scene-change	100	~20.9 s	~19.7k
`token-burner`	scene-change	uncapped	~21.0 s	~22.8k（例では 116 枚）

512px 幅の 720p フレームは約 197 tokens/frame（Anthropic の (w×h)/750）。
候補を全範囲から取り、even-sample（先頭・末尾は必ず残す）で cap まで間引く。モード差は候補ソースと cap だけ。
efficient は「速い」意味。低モーションではキーフレーム数がシーンカットより多くなり得る。

4 — フレーム予算と dedup

トークンはフレームが支配

尺	フル動画の目安	備考
≤30 s	~30 frames	密
30 s – 1 min	~40	密
1 – 3 min	~60	余裕あり
3 – 10 min	~80	疎め
> 10 min	cap まで疎	sparse scan 警告 → `--start`/`--end` 推奨

フォーカスモード

ユーザーが時刻を指定したら --start / --end。秒あたり予算が上がり、上限は 2 fps。長尺の全体スキャンより有用。

近傍重複の除去

既定で dedup が走る（--no-dedup で無効）。各 JPEG を 16×16 グレースケールにし、直前に残したフレームとの mean absolute difference ≤ 2.0 なら落とす。cap は dedup 後に適用。

transcript-cue frames: プレゼンターの「look here」などは視覚変化が小さい。トランスクリプトを読んで --timestamps T1,T2,... を足す。cue は cap に対して先に予約され、even-sample で落ちない。

5 — インストール

面ごとの入れ方

Surface	Install
Claude Code	`/plugin marketplace add bradautomates/claude-video` → `/plugin install watch@claude-video`
Codex / Cursor / Copilot / +50	`npx skills add bradautomates/claude-video -g`
claude.ai（web）	Release の `watch.skill` を Capabilities → Skills に追加（Code execution 必須）
Manual / dev	clone 後 `skills/watch` をホストの skills へ symlink

# Claude Code
/plugin marketplace add bradautomates/claude-video
/plugin install watch@claude-video

# Agent Skills CLI（グローバル）
npx skills add bradautomates/claude-video -g

# 更新
npx skills update watch -g

初回セットアップ

macOS: brew install ffmpeg yt-dlp を自動実行
Linux / Windows: 表示された apt / dnf / winget 等を実行
キー: ~/.config/watch/.env（mode 0600）に GROQ_API_KEY（優先）または OPENAI_API_KEY
キー無しでも完了可。キャプション無し動画は --no-whisper でフレームのみ

6 — 使い方とフラグ

呼び出し例

/watch https://youtu.be/abc what language is this in?
/watch ~/Movies/bug-repro.mov what's going wrong?
/watch "$URL" --start 2:15 --end 2:45
/watch video.mp4 --detail efficient --max-frames 40
/watch "$URL" --detail transcript --timestamps 4:32,7:10

Flag	役割
`--detail …`	`transcript` / `efficient` / `balanced` / `token-burner`
`--start` / `--end`	区間フォーカス（`SS` / `MM:SS` / `HH:MM:SS`）
`--timestamps`	絶対時刻の cue フレーム（カンマ区切り）
`--max-frames N`	cap 上書き
`--resolution W`	幅（既定 512。画面文字なら 1024）
`--fps F`	auto-fps 上書き（上限 2）
`--whisper groq\|openai`	Whisper バックエンド固定
`--no-whisper`	文字起こしフォールバック無効
`--no-dedup`	近傍重複を残す
`--out-dir DIR`	作業ディレクトリ指定

7 — 構成

リポジトリレイアウト

.
├── skills/watch/                 # 配布単位（SKILL.md + scripts/）
│   ├── SKILL.md                  # 全ホスト共通の契約
│   └── scripts/
│       ├── watch.py              # オーケストレータ
│       ├── download.py           # yt-dlp
│       ├── frames.py             # ffmpeg + auto-fps + dedup
│       ├── transcribe.py         # VTT / Whisper オーケストレーション
│       ├── whisper.py            # Groq / OpenAI（stdlib）
│       ├── config.py / setup.py
│       └── build-skill.sh        # dist/watch.skill
├── hooks/                        # Claude Code SessionStart
├── .claude-plugin/ · .codex-plugin/ · .agents/plugins/
├── tests/                        # pytest（合成クリップ、ネットワーク無し）
└── .github/workflows/release.yml # タグで watch.skill を添付

SKILL_DIR は「今 Read した SKILL.md の親ディレクトリ」。すべての python3 "${SKILL_DIR}/scripts/…" はこの解決に依存する。

8 — 制約・権限

精度とセキュリティ

cap 付きモード（efficient / balanced）は ~10 分超で疎になる。区間再実行か token-burner。
ユニバーサル上限 2 fps。250 フレーム超で soft warning。
動画本体は API に送らない。送るのはキャプション欠落時の抽出音声のみ。
yt-dlp は公開データのみ。ログイン・Cookie・投稿はしない。
キーは stdout/stderr/成果物に出さない。永続は作業 dir と ~/.config/watch/.env のみ。

コスト目安: 80 枚 @ 512px でおおよそ 50–80k image tokens。1024px は約 4 倍。同一セッションの追質問ではスクリプトを再実行しない。

9 — 参考リンク

公式・関連

GitHub: bradautomates/claude-video — 本体
Releases — watch.skill 配布
Agent Skills — ホスト横断のスキル仕様
Groq API keys — Whisper 優先バックエンド
OpenAI API keys — Whisper 代替
yt-dlp · ffmpeg

出典: README.md · skills/watch/SKILL.md · AGENTS.md · CHANGELOG.md