baoyu-youtube-transcript

YouTube の文字起こし

YouTube 動画の文字起こし（字幕・キャプション）をダウンロードします。手動で作成された文字起こしと自動生成された文字起こしの両方に対応しています。API キーやブラウザーは不要です。YouTube の InnerTube API を直接使用し、YouTube が直接 API へのアクセスをブロックした場合は自動的に yt-dlp にフォールバックします。

初回実行時に動画のメタデータとカバー画像を取得し、形式をすばやく変換できるように生データをキャッシュします。

スクリプトディレクトリ

スクリプトは scripts/ サブディレクトリにあります。{baseDir} は、この SKILL.md のディレクトリパスです。${BUN_X} のランタイムを解決します。bun がインストールされている場合は bun、npx が利用可能な場合は npx -y bun を使用します。それ以外の場合は bun のインストールを案内します。{baseDir} と ${BUN_X} を実際の値に置き換えてください。

スクリプト	目的
scripts/main.ts	文字起こしダウンロード用 CLI

使用方法

# Default: markdown with timestamps (English)
${BUN_X} {baseDir}/scripts/main.ts <youtube-url-or-id>

# Specify languages (priority order)
${BUN_X} {baseDir}/scripts/main.ts <url> --languages zh,en,ja

# Without timestamps
${BUN_X} {baseDir}/scripts/main.ts <url> --no-timestamps

# With chapter segmentation
${BUN_X} {baseDir}/scripts/main.ts <url> --chapters

# With speaker identification (requires AI post-processing)
${BUN_X} {baseDir}/scripts/main.ts <url> --speakers

# SRT subtitle file
${BUN_X} {baseDir}/scripts/main.ts <url> --format srt

# Translate transcript
${BUN_X} {baseDir}/scripts/main.ts <url> --translate zh-Hans

# List available transcripts
${BUN_X} {baseDir}/scripts/main.ts <url> --list

# Force re-fetch (ignore cache)
${BUN_X} {baseDir}/scripts/main.ts <url> --refresh

オプション

オプション	説明	デフォルト
<url-or-id>	YouTube の URL または動画 ID（複数指定可）	必須
--languages <codes>	優先順位順に指定する、カンマ区切りの言語コード	en
--format <fmt>	出力形式：text、srt	text
--translate <code>	指定した言語コードに翻訳
--list	取得する代わりに、利用可能な文字起こしを一覧表示
--timestamps	段落ごとに [HH:MM:SS → HH:MM:SS] のタイムスタンプを含める	on
--no-timestamps	タイムスタンプを無効にする
--chapters	動画の説明から章を分割
--speakers	話者識別用のメタデータを含む生の文字起こし
--exclude-generated	自動生成された文字起こしを除外
--exclude-manually-created	手動で作成された文字起こしを除外
--refresh	キャッシュデータを無視して強制的に再取得
-o, --output <path>	指定したファイルパスに保存	自動生成
--output-dir <dir>	出力先のベースディレクトリ	youtube-transcript

任意の環境変数

変数	説明
YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER	フォールバック時に yt-dlp --cookies-from-browser に渡されます。例：chrome、safari、firefox、chrome:Profile 1

入力形式

動画入力として、以下のいずれかを指定できます。

• 完全な URL：https://www.youtube.com/watch?v=dQw4w9WgXcQ
• 短縮 URL：https://youtu.be/dQw4w9WgXcQ
• 埋め込み URL：https://www.youtube.com/embed/dQw4w9WgXcQ
• ショート動画の URL：https://www.youtube.com/shorts/dQw4w9WgXcQ
• 動画 ID：dQw4w9WgXcQ

出力形式

形式	拡張子	説明
text	.md	フロントマター（description を含む）、タイトル見出し、概要、および任意の目次／カバー画像／タイムスタンプ／章／話者を含む Markdown
srt	.srt	動画プレーヤー向けの SubRip 字幕形式

出力ディレクトリ

youtube-transcript/
├── .index.json                          # Video ID → directory path mapping (for cache lookup)
└── {channel-slug}/{title-full-slug}/
    ├── meta.json                        # Video metadata (title, channel, description, duration, chapters, etc.)
    ├── transcript-raw.json              # Raw transcript snippets from YouTube API (cached)
    ├── transcript-sentences.json        # Sentence-segmented transcript (split by punctuation, merged across snippets)
    ├── imgs/
    │   └── cover.jpg                    # Video thumbnail
    ├── transcript.md                    # Markdown transcript (generated from sentences)
    └── transcript.srt                   # SRT subtitle (generated from raw snippets, if --format srt)

• {channel-slug}：チャンネル名をケバブケースにしたもの
• {title-full-slug}：動画タイトル全体をケバブケースにしたもの

--list モードでは標準出力にのみ出力されます（ファイルは保存されません）。

キャッシュ

初回の取得時に、スクリプトは次のファイルを保存します。

• meta.json — 動画のメタデータ、チャプター、カバー画像のパス、言語情報
• transcript-raw.json — YouTube API から取得した文字起こしの生の断片（{ text, start, duration }[]）
• transcript-sentences.json — 文ごとに分割した文字起こし（{ text, start: "HH:mm:ss", end: "HH:mm:ss" }[]）。文末の句読点（.?!…。？！ など）で分割し、文字数に応じてタイムスタンプを比例配分し、CJK 文字を考慮してテキストを結合します
• imgs/cover.jpg — 動画のサムネイル

同じ動画で次回以降に実行すると、キャッシュデータが使用されます（ネットワークへのアクセスはありません）。再取得を強制するには --refresh を使用します。別の言語が指定された場合、キャッシュは自動的に更新されます。

YouTube から直接 InnerTube 経由で取得する際にボット対策またはブロックされた応答が返された場合、スクリプトは別のクライアント ID で再試行し、その後、利用可能であれば yt-dlp にフォールバックします。フォールバックが必要なのに yt-dlp を利用できない場合は、インストールの判断をユーザーに委ねず、エージェントが yt-dlp を利用可能にする方法を判断して処理を続けてください。

SRT 出力（--format srt）は transcript-raw.json から生成されます。テキスト／Markdown 出力では、自然な文の区切りに transcript-sentences.json を使用します。

ワークフロー

ユーザーが YouTube の URL を指定して文字起こしを希望した場合：

1. ユーザーが言語を指定していない場合は、最初に --list を実行して、利用可能な選択肢を表示します
2. スクリプトの実行時は、URL を必ずシングルクォートで囲みます — zsh では ? がグロブのワイルドカードとして扱われるため、YouTube の URL を引用符で囲まないと「no matches found」が発生します。'https://www.youtube.com/watch?v=ID' のように指定してください
3. デフォルトでは、最も充実した出力（チャプター＋話者の識別）を得るため、--chapters --speakers を付けて実行します
4. スクリプトはキャッシュデータと出力ファイルを自動で保存し、ファイルパスを表示します
5. --speakers モードの場合：スクリプトが生データのファイルを保存した後、以下の話者識別ワークフローに従って、話者ラベルを付ける後処理を行います

ユーザーがカバー画像またはメタデータのみを希望する場合は、どのオプションを付けてスクリプトを実行しても、meta.json と imgs/cover.jpg がキャッシュされます。

同じ動画の形式を変換する場合（例：最初にテキスト形式、次に SRT 形式）、キャッシュデータが再利用されるため、再取得は不要です。

チャプターと話者のワークフロー

チャプター（--chapters）

スクリプトは動画の説明からチャプターのタイムスタンプ（例：0:00 Introduction）を解析し、チャプターの境界で文字起こしを分割して、読みやすい段落にまとめ、目次付きの .md として保存します。追加の処理は不要です。

説明にチャプターのタイムスタンプがない場合、文字起こしはチャプター見出しなしで、まとめた段落として出力されます。

話者の識別（--speakers）

話者の識別には AI による処理が必要です。スクリプトは、次の内容を含む生の .md ファイルを出力します。

• 動画のメタデータを含む YAML フロントマター（タイトル、チャンネル、日付、カバー画像、説明、言語）
• 話者名の抽出に使用する動画の説明
• 説明にチャプターがある場合は、その一覧
• SRT 形式の文字起こしデータ（開始／終了タイムスタンプは事前に計算済みで、トークン効率に優れています）

スクリプトが生データのファイルを保存した後、サブエージェントを起動して話者を識別します（コスト効率を高めるため、Sonnet のような低コストのモデルを使用します）。

1. 保存された .md ファイルを読み込みます
2. {baseDir}/prompts/speaker-transcript.md にあるプロンプトテンプレートを読み込みます
3. プロンプトに従って、生の文字起こしを処理します。
   • 動画のメタデータを使って話者を識別します（タイトル → ゲスト、チャンネル → ホスト、説明 → 氏名）
   • 会話の流れ、質問と回答のパターン、文脈上の手がかりから話者の交代を検出します
   • チャプターに分割します（説明にチャプターがあればそれを使用し、なければ話題の変化から作成します）
   • **Speaker Name:** ラベル、段落のまとめ（2～4 文）、[HH:MM:SS → HH:MM:SS] タイムスタンプを使って書式を整えます
4. YAML フロントマターを維持したまま、処理済みの文字起こしで .md ファイルを上書きします

--speakers を使用すると、--chapters も暗黙的に有効になります。処理後の出力には、常にチャプター分割が含まれます。

エラーケース

エラー	意味
文字起こしが無効	動画に字幕がありません
文字起こしが見つからない	リクエストされた言語は利用できません
動画を利用できない	動画が削除されている、非公開になっている、または地域制限されています
IP がブロックされている	リクエストが多すぎます。しばらくしてから再試行してください
年齢制限	年齢確認のため、動画へのログインが必要です
ボットが検出された	スクリプトは別のクライアントを試した後、yt-dlp を使用して再試行します。フォールバック用ツールが不足している場合は、エージェントが自分で解決してください。それでも失敗する場合は、YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER=safari（または使用しているブラウザー）を試してください