baoyu-youtube-transcript

## baoyu-youtube-transcript スキルの概要

### baoyu-youtube-transcript が得意なこと
baoyu-youtube-transcript は、画面上の字幕を見るだけでなく、あとで再利用しやすいテキストファイルとして YouTube の文字起こしを取得したい人向けのスキルです。YouTube の URL または動画 ID から transcript、subtitle、cover image を取得でき、言語選択や翻訳にも対応しています。さらに、一度キャッシュしたデータを再取得せずに markdown や SRT へ再整形できます。実運用で特に強いのは信頼性で、まず YouTube の InnerTube API を使い、直接取得がブロックされた場合は `yt-dlp` にフォールバックします。

### どんなユーザーに向いているか、実際の用途は何か
このスキルは、リサーチャー、ノート作成者、アーカイブ担当、コンテンツ再利用担当、そして動画を markdown・字幕・transcript 資産へ変換する Format Conversion を行うエージェントに向いています。実際に片づけたい仕事はたいてい、「この動画から必要な言語の transcript を取り出し、必要ならタイムスタンプやチャプターも残し、あとで使い回せるファイル構成で保存すること」です。

### インストール前に見ておきたい主な違い
汎用的な「この YouTube 動画を要約して」というプロンプトと比べると、baoyu-youtube-transcript はファイルとして出力でき、キャッシュが効き、言語を意識したトラック選択ができ、抽出手順もより決定的です。さらに、このリポジトリには `prompts/speaker-transcript.md` という話者処理用のプロンプトも含まれており、最終的に欲しいものが生の字幕行ではなく、編集しやすい transcript である場合に効いてきます。

## baoyu-youtube-transcript スキルの使い方

### インストール時の前提と実行環境の要件
baoyu-youtube-transcript をインストールして使うには、`bun` または `npx` が必要です。スクリプトは `skills/baoyu-youtube-transcript/scripts/` にあり、`SKILL.md` では実行ランタイムとしてまず `bun`、次に `npx -y bun` を使う前提が明示されています。導入前に評価したいなら、まず次のファイルから読むのがおすすめです。
- `SKILL.md`
- `scripts/main.ts`
- `scripts/youtube.ts`
- `prompts/speaker-transcript.md`
- `scripts/main.test.ts`

この順で追うと、リポジトリ全体を漫然と眺めるよりも、実際の CLI の挙動、フォールバックの作り、後処理の流れをずっと早く把握できます。

### baoyu-youtube-transcript の実際の使い方
通常の baoyu-youtube-transcript の使い方では、メインスクリプトに YouTube の URL か 11 文字の動画 ID を渡して実行します。スクリプトでできることは次のとおりです。
- transcript track を取得する
- `json3` など、より扱いやすい字幕形式を優先する
- 手動字幕と自動生成字幕を選び分ける
- 利用可能なら翻訳を使う
- markdown または SRT で出力する
- metadata と transcript payload を出力ディレクトリ配下にキャッシュする

ここで重要なのは、長いプロンプトを書くことではなく、何をどう抽出したいかを明確にすることです。良い依頼には次の情報が入っています。
- 動画 URL または ID
- 希望言語の優先順
- 自動生成字幕を許容するかどうか
- 欲しい出力形式: markdown または SRT
- タイムスタンプ、チャプター、話者情報が必要かどうか

より実用的な依頼例は次のようになります。  
「この YouTube URL に baoyu-youtube-transcript を使い、`en` を優先、次に `zh-Hans`、自動生成字幕は許可、タイムスタンプ付きの markdown で出力し、再利用しやすい output directory 配下に保存してください。」

### baoyu-youtube-transcript で推測を減らすプロンプト設計とワークフロー
AI エージェント経由で baoyu-youtube-transcript を呼び出すなら、曖昧な依頼をそのまま渡すのではなく、実行可能な指示に分解するのが有効です。たとえば次の流れです。

1. 抽出: 「この video ID の transcript を `en` で取得し、なければ別トラックから翻訳された `en` を使う」
2. 整形: 「レビューしやすいようタイムスタンプ付き markdown で返す」
3. 仕上げ: 「その後、`prompts/speaker-transcript.md` を使って、生の transcript を翻訳せずにチャプター付き・話者ラベル付き transcript に変換する」

この 2 段階の流れが重要なのは、話者ラベル付けが生字幕のダウンロードとは別の処理だからです。プロンプトファイルでも、逐語的な忠実性と話者名の一貫性が重視されており、インタビュー、ポッドキャスト、講義 transcript の整形に向いています。

### 出力構成、キャッシュ、実運用でのコツ
baoyu-youtube-transcript スキルは metadata と transcript のキャッシュを保存するため、同じ素材を繰り返し整形するときに高速です。同じ動画から、生の出力と整えた出力の両方を作りたい場面で特に便利です。実務上のコツは次のとおりです。
- 同じ動画を何度も扱うなら、安定した `outputDir` を使う
- 話者の整形をかける前に、生の transcript 出力を残しておく
- 時間精度が重要なら SRT、読みやすさを優先するなら markdown を使う
- チャプター抽出が重要なら、動画説明欄にタイムスタンプ付きチャプターがあるか確認する。スクリプトは説明文と動画長からチャプターを解析するためです

## baoyu-youtube-transcript スキル FAQ

### baoyu-youtube-transcript は普通のプロンプトより優れている？
はい。ベストエフォートの推論ではなく、再現可能な抽出が必要なときには優位です。通常のプロンプトでは、subtitle track の安定したダウンロード、利用可能言語の確認、生データのキャッシュ、`yt-dlp` へのフォールバックといった処理を信頼して任せることはできません。baoyu-youtube-transcript は、単なる要約ではなく、取得と変換そのものが目的のタスクで強みを発揮します。

### どんな場合はこのスキルに向かない？
アクセス可能な transcript track が存在せず、音声だけから完全な speech-to-text を期待している場合には不向きです。このリポジトリは YouTube 上の transcript / subtitle を取得する設計であり、単独の ASR パイプラインではありません。また、保存可能なファイルは不要で、とにかく手早く人間向けの要約だけ欲しい場合にはオーバースペックです。

### baoyu-youtube-transcript は初心者でも使いやすい？
難易度は中程度です。クリック操作中心ではなくスクリプト実行型なので、`bun`、`npx`、パス、出力フォルダに最低限なじみがあると使いやすくなります。ただし良い点として、このリポジトリは実装を追いやすく、`scripts/main.test.ts` を見れば選択ロジックが分かり、`SKILL.md` を見れば安全に始めるためのコマンドパターンを確認できます。

## baoyu-youtube-transcript スキルを改善するには

### baoyu-youtube-transcript の出力品質を上げる入力の書き方
baoyu-youtube-transcript の結果を最も手早く改善する方法は、どの transcript を選びたいかを明示することです。言語の優先順位、手動字幕を優先するかどうか、自動生成字幕を許容するかどうかまで指定してください。ここを省くと、使えなくはないが品質の低いトラックや、意図しない翻訳版が選ばれることがあります。

### よくある失敗パターンを早めに潰す
典型的な問題は、無効な動画 ID、直接取得のブロック、対象言語字幕の欠落、そして「字幕を翻訳したい」のか「transcript を要約したい」のかが混同されることです。抽出に失敗したら、`scripts/youtube.ts` の挙動を概念的に確認してください。このスキルにはすでにフォールバック経路があるので、次にやるべきことはたいてい、プロンプト全体を書き直すことではなく、言語条件を変えるか、自動生成字幕を許可することです。

### 最初の transcript の後に反復する
Format Conversion 用の baoyu-youtube-transcript では、一発で終わらせるより、反復前提のワークフローが合っています。
1. 生の transcript を取得する
2. 言語と欠落の有無を確認する
3. 必要なら別フォーマットで再実行する
4. 話者・チャプターの後処理をかける

最初の markdown が少し荒く見えても、そこでこのスキルを見切らないでください。まずはキャッシュされた生ファイルを残し、そのうえで整形をやり直すか、`prompts/speaker-transcript.md` を適用して最終文書を整えるのが得策です。単発のダウンロードスクリプトよりこのスキルの価値が出るのは、まさにこの段階です。