watch-video

/watch-video — 任意の動画を、指定した深さで文字起こしして分析する

以前の youtube-transcript スキルを置き換え、機能を拡張します。YouTube は数あるソースのひとつになり、分析の深さはユーザーが指定できます。

ステップ 1 — 入力を解析する

以下を受け付けます。

• YouTube：完全な URL、youtu.be/<id>、youtube.com/shorts/<id>、11 文字の生 ID
• Loom：loom.com/share/<id> または loom.com/embed/<id>
• Vimeo：vimeo.com/<id>
• Riverside：ダウンロード URL またはローカルファイル
• Zoom：ダウンロードした録画のローカル .mp4
• X / IG / TikTok の動画：URL — メタデータの取得は social-fetch に委ね、ファイルには yt-dlp を使用します
• ローカルファイル：.mp4 / .mov / .webm / .mkv の任意のパス

URL パターンまたはファイル拡張子からソースを判定します。特定できない場合は確認します。

ステップ 2 — 分析の深さを解析する

呼び出し方	モード	得られるもの
/watch-video <url>	transcript（デフォルト）	整形済みテキスト、メタデータ、必要に応じてチャプター
/watch-video <url> transcript	transcript	デフォルトと同じ
/watch-video <url> visual	visual	文字起こし + 一定間隔のフレーム + 重要な場面を特定する Claude の画像分析
/watch-video <url> multimodal	multimodal	Gemini へのネイティブ動画入力（$GEMINI_API_KEY が設定されている場合）。それ以外は Claude による高密度のフレームごとの画像分析

分析の深さが指定されておらず、動画が 10 分を超える場合は、デフォルトを適用する前に確認します（長い動画の visual / multimodal モードは実費がかかります）。

ステップ 3 — メタデータを取得する

URL ソースには yt-dlp を使用します。

yt-dlp --print "%(title)s|%(uploader)s|%(duration_string)s|%(upload_date>%Y-%m-%d)s|%(description)s" \
  --print "%(chapters)j" --skip-download "<url>"

以下を取得します：タイトル、アップローダー／チャンネル、長さ、アップロード日、説明（最初の段落）、チャプター（JSON または null）。

ローカルファイルには ffprobe を使用します。

ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "<file>"

ステップ 4 — 作業ディレクトリを作成する

~/Documents/videos/<source>-<slug>-<date>/

項目：

• source：youtube / loom / vimeo / riverside / zoom / local
• slug：タイトルをケバブケースにしたもの（先頭 4〜6 語、最大 50 文字）
• date：YYYY-MM-DD

ステップ 5 — 文字起こしを取得する

バックエンドの選択順：

1. 完全な内容と思われるプラットフォーム提供の文字起こしがある場合：

   • YouTube：yt-dlp --write-sub --write-auto-sub --skip-download --sub-lang en --sub-format vtt
   • Loom：https://www.loom.com/share/<id> ページのメタデータ、または $LOOM_API_KEY が設定されている場合は Loom API から取得
   • Riverside：録画の共有ページから組み込みの文字起こしを利用可能
   • プラットフォームの文字起こしにタイムスタンプがある場合は、それを使用します。Whisper はスキップします。

2. MLX-Whisper ローカル（Apple Silicon 搭載 Mac ではデフォルト）：

   # Install once: pip install mlx-whisper
   python3 -c "import mlx_whisper; mlx_whisper.transcribe('<file>', path_or_hf_repo='mlx-community/whisper-large-v3-turbo')" \
     > "<workdir>/transcript-raw.json"
   

   または CLI 経由：mlx_whisper <file> --model mlx-community/whisper-large-v3-turbo --output-dir <workdir>

3. Apple Silicon 以外（Linux、Intel Mac、Windows、クラウドエージェント）：faster-whisper（pip install faster-whisper、CPU または CUDA）または whisper.cpp。同じモデルサイズで、出力の処理方法も同じです。

URL の場合は、まず動画ファイルをダウンロードします（yt-dlp を使用。Loom / Vimeo / YT に対応）。

yt-dlp -f "bv*[height<=720]+ba/b[height<=720]" -o "<workdir>/video.%(ext)s" "<url>"

文字起こしとフレーム分析には 720p で十分です（ダウンロードサイズが小さくなり、処理も速くなります）。

文字起こしを整形する（ローリング字幕が使われている YouTube の自動字幕にのみ必要です。Whisper の出力はすでに整形済みです）。

# YouTube VTT cleanup — de-dup rolling captions, strip tags, paragraph-break on cue gaps >2s
awk '
  /^WEBVTT/ || /^Kind:/ || /^Language:/ || /^NOTE/ { next }
  /-->/ { in_cue = 1; last = ""; next }
  /^$/ { if (last) print last; in_cue = 0; last = ""; next }
  in_cue { gsub(/<[^>]+>/, "", $0); last = $0 }
  END { if (last) print last }
' "<workdir>/transcript.en.vtt" | awk '!seen[$0]++' > "<workdir>/transcript.txt"

最終版を <workdir>/transcript.txt に保存します。

ステップ 6 — transcript モードの場合：ここで終了する

以下を出力します。

• transcript.txt
• metadata.json
• チャットで 1 行の概要：タイトル、ソース、長さ、単語数
• 作業ディレクトリのパス
• （任意）ステップ 9 — セカンドブレインへの保存を提案する

ステップ 7 — visual モードの場合：フレームを抽出し、画像分析を行う

フレーム抽出（ffmpeg）

ソースの特徴に応じた間隔：

ソースの種類	フレーム間隔
画面共有 / Loom / デモ	5 秒ごとに 1 フレーム（UI の変化が速いため）
トークヘッド / ポッドキャスト	30 秒ごとに 1 フレーム（変化が遅いため）
スライドプレゼンテーション	10 秒ごとに 1 フレーム + 検出したシーン切り替えごとにフレームを強制取得
不明な場合のデフォルト	15 秒ごとに 1 フレーム

mkdir -p "<workdir>/frames"
ffmpeg -i "<workdir>/video.mp4" -vf "fps=1/15" "<workdir>/frames/frame-%04d.png" -y

シーン切り替えの検出（特にスライド資料の場合）：

ffmpeg -i "<workdir>/video.mp4" -vf "select='gt(scene,0.3)',showinfo" -vsync vfr "<workdir>/frames/scene-%04d.png" 2> "<workdir>/scene-detection.log"

ビジョンパス

各フレームを、同じタイムスタンプ範囲のトランスクリプトチャンクとペアにします。その後、Claude のビジョンにバッチ送信して統合します。

フレームごとのバッチプロンプト（1回の呼び出しで最大約10フレーム）:

ここにタイムスタンプ T1..TN の動画からの N 個のフレームがあります。各フレームについて、画面に表示されている内容を1〜2文で説明してください。次の点にフラグを立ててください: (a) 前のフレームからの UI の変化、(b) 画面に表示されているテキスト、(c) 意思決定、アクション、または注目すべき出来事と思われる瞬間。また、この範囲で話されたトランスクリプトのテキストも記録してください。

出力を <workdir>/moments.md として保存します:

# Key moments — <title>

## 00:00:15 (frame-001.png)
**On screen**: Login form, email field focused
**Transcript**: "So you just open it up and..."
**Note**: Beginning of UI demo

## 00:00:45 (frame-002.png)
**On screen**: Dashboard with 4 cards
**Transcript**: "And here's where you see all your projects."
**Note**: Major view change — first time the dashboard appears

サマリーを生成

モーメントを特定したら、動画全体を <workdir>/summary.md に統合します:

# Summary — <title>

**Source:** <source URL / file>
**Duration:** <hh:mm:ss>
**Watched at:** <date>
**Mode:** visual

## TL;DR
<2–4 sentences>

## Key moments
- 00:00:15 — <one-line>
- 00:00:45 — <one-line>

## Action items flagged
- <item> [timestamp]

## Decisions flagged
- <decision> [timestamp] — consider routing to /decide

## Quotes worth keeping
- "..." [timestamp]

## Open questions
- <question raised but not answered>

Step 8 — multimodal モードの場合

バックエンドの選択

1. Gemini ネイティブ: $GEMINI_API_KEY が設定されている場合（長い動画ではフレームごとの処理よりはるかに安価で高速）:

   デフォルトモデル: gemini-3.5-flash（2026年5月リリース、入力 ~$1.50 / 出力 $9 あたり100万トークン、動画1秒あたり ~$0.15、コーディング／エージェント系ベンチマークで 3.1 Pro を上回り、速度は4倍）。詳細が重要なブランド監査／重要な分析では gemini-3.1-pro にオーバーライドしてください。大量の安価な処理には gemini-2.5-flash-lite を使用します。

   # Step 1: Upload video via Files API
   FILE_URI=$(curl -s -X POST "https://generativelanguage.googleapis.com/upload/v1beta/files?key=$GEMINI_API_KEY" \
     -H "X-Goog-Upload-Command: start, upload, finalize" \
     -H "Content-Type: video/mp4" \
     --data-binary "@<workdir>/video.mp4" | jq -r '.file.uri')
   
   # Wait until file is ACTIVE (Gemini processes the video first)
   while true; do
     STATE=$(curl -s "$FILE_URI?key=$GEMINI_API_KEY" | jq -r '.state')
     [ "$STATE" = "ACTIVE" ] && break
     sleep 3
   done
   
   # Step 2: Generate content with the file + multimodal-analysis prompt
   curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent?key=$GEMINI_API_KEY" \
     -H "Content-Type: application/json" \
     -d "{
       \"contents\":[{
         \"parts\":[
           {\"file_data\":{\"mime_type\":\"video/mp4\",\"file_uri\":\"$FILE_URI\"}},
           {\"text\":\"<multimodal analysis prompt — see Step 7's summary template + use-case extensions>\"}
         ]
       }]
     }"
   

   ファイルは Gemini Files API に約48時間保持されます — 同じ動画を異なるプロンプトで再クエリするのに便利です。

2. Gemini キーがない場合の高密度 Claude ビジョンフォールバック:

   • フレーム間隔: 3秒ごとに1フレーム（ビジュアルモードよりはるかに高密度）
   • マルチモーダル分析プロンプトを使って Claude のビジョン経由でバッチ処理
   • 長い動画では Gemini より遅く高コスト — 10分を超えるコンテンツで実行する前にユーザーに警告してください

マルチモーダル出力

Step 7 と同じ summary.md テンプレート + 拡張セクション:

## Multimodal observations
- **Body language / delivery**: <observations on talking-head video>
- **Pacing**: <fast/slow/uneven>
- **Visual style**: <brand audit, ad review, design observations>
- **Audio quality / atmosphere**: <music, silence, background>

追加のセクションの正確な内容はユースケース（ブランド監査、広告レビュー、トークの配信レビュー、クライアントコールの読み取り）によって異なります。ユースケースは、呼び出し時のソースとユーザーの口頭での説明から推測されます。

Step 9 — オプション: second-brain へのキャプチャ

いずれかのモードが完了したら、次を提案します:

「これを second-brain にキャプチャしますか？ call-<slug>.md（または meeting- / note- / resource-）を ${SECOND_BRAIN_VAULT:-$HOME/Documents/SecondBrain}/raw/ に、サマリー、ソース URL、トランスクリプトへのリンクとともに書き込みます。」

ソース別のタイププレフィックス:

ソース	プレフィックス
Loom / Zoom / Riverside / Otter / 通話録音	call-
会議（トランスクリプトではなく自分のメモ）	meeting-
トーク / キーノート / カンファレンス	note-
広告 / ランディングページ動画 / マーケティング参考資料 / 競合動画	resource-

ファイル本文: ソースを1行、サマリー、完全な workdir へのリンク。

Step 10 — レポート

チャット内で:

• 1行のヘッドライン: <source> · <title> · <duration> · <mode> · <word count> words
• workdir パス
• visual / multimodal の場合: 上位3つのキーモーメントの簡単なリスト
• すべてのモードの場合: トリアージ用にフラグが立てられたアクション項目／意思決定
• second-brain にキャプチャした場合: そのパスも

ソースリファレンス

ソース	ダウンロード	組み込みトランスクリプト	備考
YouTube	yt-dlp	自動字幕（--write-auto-sub）	以前の youtube-transcript スキルと同じ
Loom	yt-dlp（Loom 対応）	あり — embed メタデータまたは Loom API 経由で取得	非同期スクリーンシェアが中心 — 主要なユースケース
Vimeo	yt-dlp	場合による	マーケティング／埋め込み動画
Riverside	エクスポートからの直接 URL、またはローカルファイル	あり — Riverside が生成	ポッドキャストのエピソード
Zoom	ローカルの .mp4（ダウンロード済み録画）	場合による（Zoom の音声トランスクリプトファイル）	クライアントコール
X / IG / TikTok	メタデータは social-fetch に委ね、ファイルは yt-dlp	なし	ショートフォーム
ローカルファイル	n/a	n/a	パスをドロップ

連携先

• social-fetch — 動画処理の前に、X／IG／TikTok の URL メタデータ（エンゲージメント、投稿者、返信）を取得します
• second-brain — ソースの種類に応じて、要約を raw/call-<slug>.md、meeting-、note-、または resource- として保存します
• decide — 動画にフラグ付きの決定事項が含まれている場合は、構造化して記録するために /decide に振り分けます
• pm — 要約でフラグ付けされたアクションアイテムは、プロジェクトボードでトリアージできます
• slide-deck — トークの録画 → アウトラインの抽出 → スライドデッキのドラフト（ループ）
• jab-hook — ポッドキャスト／トーク動画から引用とクリップに適した場面を抽出し、BIP／プロモーション投稿に活用します
• skillify from-video — プロセスの録画に visual モードを使用する主なケースです。ユーザーがワークフローを実行する様子を録画（Loom／画面共有）すると、このスキルがトランスクリプトと重要な視覚的場面を抽出し、その後 skillify がワークフローを統合して SKILL.md にまとめます。「一度録画すれば、AI がスキルに変換します。」

エラー処理

失敗	対応
動画が利用不可／非公開／地域制限あり	その旨を報告して停止します
字幕がなく、Whisper がインストールされていない	ユーザーに pip install mlx-whisper（Apple Silicon）または pip install faster-whisper（それ以外）を案内します
ffmpeg が見つからない（visual／マルチモーダルの場合）	ユーザーに brew install ffmpeg を案内します
Vision パスの結果が空／不明瞭	フレーム数を減らして再試行するか、注記を付けてトランスクリプトのみの処理に切り替えます
マルチモーダルをリクエストされたが $GEMINI_API_KEY がなく、動画が30分を超える	コストを警告し、visual モードへの切り替えを提案します
yt-dlp バイナリが見つからない	brew install yt-dlp

品質に関する注意事項

• 深度を選ぶのはユーザーであり、スキルではありません。 トランスクリプト／visual／マルチモーダルは、コストとレイテンシーの異なる3つのプロファイルです。長い動画（>10 min）では、visual／マルチモーダルの処理にコストをかける前に必ず確認します。
• プラットフォームのトランスクリプトを優先し、次に Whisper を使います。 YouTube の自動字幕、Loom のトランスクリプト、Riverside の組み込みトランスクリプトがあれば、無料ですぐに利用できます。プラットフォーム提供の方法が使えない場合に限り、ローカルの Whisper に切り替えます。
• ローカルの Whisper が最速の方法です。 M シリーズ Mac の MLX はリアルタイムより速く文字起こしでき、その他の環境では faster-whisper が同等の選択肢です。クラウドの Whisper は、費用がかかり、ネットワークに依存し、一般的な動画の長さではレイテンシーも悪いため、かなり優先度の低い選択肢です。
• ソースの種類に応じてフレーム間隔を設定します。 画面共有／デモでは UI がすばやく変化するため5秒に1フレーム、トーク中心のポッドキャストでは変化がゆっくりなため30秒に1フレームが必要です。判断に迷う場合は、デフォルトの15秒を使います。間隔が適切でないと、重要な場面を見逃すか、Vision パスのコストを無駄にします。
• 720p で十分です。 文字起こしとフレーム解析のために1080p／4Kをダウンロードすると、帯域幅とストレージを無駄にします。デフォルトでは yt-dlp -f "bv*[height<=720]+ba/b[height<=720]" を使います。
• シーン変化の検出でスライドの切り替わりを捉えられます。 動画がスライドプレゼンテーションの場合は、ffmpeg -vf "select='gt(scene,0.3)'" を追加して、検出されたスライド変更ごとにフレームを取得します。時間ベースのサンプリングのみの場合より確実です。
• マルチモーダルのコスト警告は必須です。 60分の動画で Gemini のマルチモーダル処理を行うと、かなりの費用がかかります。実行前に警告し、ユーザーが判断に迷っている場合は、代替としてトランスクリプトのみの処理を提案します。
• 要約形式には振り分けのヒントが含まれます。 ## Decisions flagged と ## Action items flagged のセクションは、/decide と /pm での後続処理を示します。下流との連携のしやすさは、要約の構造によって実現されます。