youtube-analysis

YouTube の分析

YouTube 動画から文字起こしを抽出し、主要なアイデア、議論、専門用語、要点、複数レベルの要約など、構造化された概念分析を作成します。API キーも MCP サーバーも必要ありません。

参照ファイル

ファイル	用途
scripts/fetch_transcript.py	文字起こしとメタデータの取得（CLI とインポートに対応）
scripts/analyze_video.py	オーケストレーター：取得 → 構造化 → エクスポート用ひな形の作成
scripts/utils.py	URL の解析、タイムスタンプの書式設定、文字起こしの分割
references/analysis-patterns.md	動画の種類ごとのプロンプトパターン
assets/output-template.md	最終出力用の Markdown テンプレート

ワークフロー

User provides YouTube URL
        │
        ▼
┌─────────────────────┐
│  Step 0: Deps check │
└────────┬────────────┘
         ▼
┌─────────────────────┐
│  Step 1: Parse URL  │
└────────┬────────────┘
         ▼
┌─────────────────────┐     ┌──────────────┐
│  Step 2: Transcript │────▶│  yt-dlp      │
│  (youtube-t-api)    │fail │  (fallback)  │
└────────┬────────────┘     └──────┬───────┘
         │◀───────────────-────────┘
         ▼
┌─────────────────────┐
│  Step 3: Metadata   │
│  (yt-dlp --dump-json│
└────────┬────────────┘
         ▼
┌─────────────────────┐
│  Step 4: Claude     │
│  analyzes transcript│
└────────┬────────────┘
         ▼
┌─────────────────────┐
│  Step 5: Export MD  │
└─────────────────────┘

ステップ 0：依存関係を確認する

スクリプトを実行する前に、依存関係がインストールされていることを確認します。

uv pip install youtube-transcript-api yt-dlp -q

または、uv run を使ってスクリプトを直接実行します。

uv run --with youtube-transcript-api --no-project python scripts/fetch_transcript.py "URL"

確認します。

python -c "from youtube_transcript_api import YouTubeTranscriptApi; print('OK')"
yt-dlp --version

ステップ 1：URL の解析と検証

scripts/utils.py:parse_youtube_url() を使って動画 ID を抽出します。次の形式に対応しています。

形式	例
標準の視聴 URL	youtube.com/watch?v=dQw4w9WgXcQ
短縮 URL	youtu.be/dQw4w9WgXcQ
Shorts	youtube.com/shorts/dQw4w9WgXcQ
埋め込み	youtube.com/embed/dQw4w9WgXcQ
ライブ	youtube.com/live/dQw4w9WgXcQ
パラメーター付き	youtube.com/watch?v=dQw4w9WgXcQ&t=120&list=PLxxx
ID のみ	dQw4w9WgXcQ
モバイル	m.youtube.com/watch?v=dQw4w9WgXcQ
Music	music.youtube.com/watch?v=dQw4w9WgXcQ

解析に失敗した場合は、標準形式の URL をユーザーに提示してもらいます。

ステップ 2：文字起こしの抽出

fetch_transcript.py を実行して文字起こしを取得します。

cd <skill_dir>/scripts
python fetch_transcript.py "YOUTUBE_URL" --lang en

標準出力に JSON が出力されます。このスクリプトは次の処理を行います。

1. 主な方法：youtube-transcript-api を使って字幕を直接取得します（API キー不要）。
2. フォールバック：主な方法が失敗した場合、yt-dlp --write-sub --write-auto-sub を使って字幕ファイルを抽出します。
3. 言語の処理：まず指定された言語を試し、利用可能な文字起こしにフォールバックします。

返される JSON には、タイムスタンプ付きの個別セグメントと、結合された transcript_text フィールドの両方が含まれます。

モジュールとしてインポートする場合（analyze_video.py で使用）：

from fetch_transcript import fetch_video
data = fetch_video("https://youtube.com/watch?v=VIDEO_ID", lang="en")

ステップ 3：メタデータの抽出

メタデータは、fetch_transcript.py が yt-dlp --dump-json を使って自動的に取得します。

• タイトル、チャンネル名
• 再生時間（秒）
• アップロード日（YYYY-MM-DD）
• 説明（ひな形には先頭 500 文字を記載）
• 視聴回数
• タグ

個別の手順は不要です。fetch_video() がすべてを返します。

ステップ 4：概念分析

ここであなた（Claude）が作業します。 スクリプトが生データを提供し、分析はあなたが行います。

分析の詳細度

ユーザーのリクエストまたは動画の長さに応じて選択します。

詳細度	使用する場面	記入するセクション
quick	ユーザーが手早い概要を求めている場合、または動画が 10 分未満の場合	TL;DR、主要な概念、要点
standard	ほとんどの動画でのデフォルト	テンプレートのすべてのセクション
deep	ユーザーが詳細な分析を求めている場合、または動画が 30 分を超える場合	すべてのセクションと、タイムスタンプ付きのセクションごとの分析

分析プロセス

1. JSON 出力からトランスクリプト全体を読む
2. 動画の種類を特定する（またはユーザーが提示したヒントを使う）。種類ごとのガイダンスについては、references/analysis-patterns.md を参照してください
3. 主要な概念を抽出する：主なアイデア、主張、論点を、それぞれ簡潔な説明を添えた箇条書きにします
4. 技術用語を特定する：動画で示された定義を確認します
5. 注目すべき発言を抜き出す：おおよそのタイムスタンプを添えて、重要な引用を言い換えます
6. 要点をまとめる：視聴者が検討すべき、実行可能な項目を挙げます
7. TL;DR を書く：核心となるメッセージを、1〜3 文でまとめます
8. 関連トピックを提案する：言及された概念に基づいて、視聴者が次に調べるとよい内容を提案します

詳細な分析を行う場合

utils.chunk_transcript() を使ってトランスクリプトを 5 分ごとの区間に分割し、タイムスタンプ付きで各区間を分析します。

from utils import chunk_transcript
chunks = chunk_transcript(data["transcript"], chunk_minutes=5)
for chunk in chunks:
    print(f"[{chunk['start_formatted']} - {chunk['end_formatted']}]")
    print(chunk["text"])

または、オーケストレーターを --depth deep 付きで実行します。

python analyze_video.py "YOUTUBE_URL" --depth deep

動画の種類ごとのパターン

種類	主な抽出対象	参照先
講義	主張、論点、引用、定義	references/analysis-patterns.md
チュートリアル	手順、ツール、前提条件、注意点	references/analysis-patterns.md
インタビュー	視点、意見の相違、各人の立場	references/analysis-patterns.md
ポッドキャスト	話題の流れ、意見、推奨事項	references/analysis-patterns.md
テックトーク	アーキテクチャ、トレードオフ、ベンチマーク、教訓	references/analysis-patterns.md
パネルディスカッション	合意点と意見の相違、各登壇者の見解	references/analysis-patterns.md

種類ごとの詳しい抽出ガイダンスについては、references/analysis-patterns.md をお読みください。

ステップ 5：Markdown にエクスポートする

オーケストレーターは、次のひな形を生成します。

cd <skill_dir>/scripts
python analyze_video.py "YOUTUBE_URL" --output ./analysis.md --depth standard --type auto

フラグ：

• --output PATH：書き込み先（デフォルト：./{sanitized_title}.md）
• --depth quick|standard|deep：分析の深さ
• --type auto|lecture|tutorial|interview|podcast|tech-talk|panel：動画の種類のヒント
• --lang CODE：トランスクリプトの言語（デフォルト：en）
• --json：Markdown のひな形ではなく、生の JSON を出力します

ひな形には、入力済みのメタデータと [TO BE ANALYZED] のプレースホルダーが含まれます。Claude がこれらを実際の分析結果に置き換えます。

推奨ワークフロー：fetch_transcript.py を実行して JSON を取得し、コンテキスト内で分析したうえで、assets/output-template.md を構成のガイドとして、最終的な Markdown を直接作成します。オーケストレーターは、バッチ処理を行う場合や、ユーザーがファイルへの書き込みを希望する場合に便利です。

エラー処理

エラー	終了コード	原因	解決方法
URL の解析に失敗	1	無効または未対応の URL 形式	標準的な YouTube URL をユーザーに尋ねます
トランスクリプトなし	2	動画に字幕がない（手動・自動のどちらも）	ユーザーに知らせ、別の動画を提案します
動画を利用できない	1	非公開、削除済み、または地域制限	制限についてユーザーに知らせます
年齢制限あり	1	認証が必要	ユーザーに知らせます。yt-dlp は Cookie があれば動作する可能性があります
メタデータの取得に失敗	0	yt-dlp のネットワークの問題	トランスクリプトは引き続き利用でき、メタデータには「Unknown」と表示されます
言語を利用できない	0	要求した言語を利用できない	利用可能な言語に自動的にフォールバックします
yt-dlp が未インストール	1	依存関係が不足	ステップ 0 の依存関係のインストールを実行します

制限事項

• 視覚的な分析には非対応：文字起こしのみが対象です。スライド、図、画面上のコード、デモは取得されません。関連する場合は、この点を出力に記載してください。
• 自動字幕の品質：自動生成された字幕には、特に専門用語、固有名詞、英語以外のアクセントがある場合に誤りが含まれることがあります。
• ミュージックビデオ：歌詞は字幕として利用できない場合があります。音楽のみのコンテンツでは、結果の品質が低くなります。
• ライブ配信：配信中のライブ配信では、文字起こしが不完全または利用できない場合があります。
• レート制限：YouTube へのリクエストが過剰になると、一時的にブロックされることがあります。複数の動画を処理する場合は、リクエストの間隔を空けてください。
• 対応言語：英語で最良の結果が得られます。その他の言語では、字幕の有無と品質に左右されます。
• 話者の特定：文字起こしで個々の話者が特定されることはほとんどありません。可能な場合、Claude は文脈から推測します。