YouTube Transcript

概要

YouTubeのURLを、キャプションの生のダンプではなく、洗練された読み物に変換します。まずはYouTubeのネイティブキャプションを優先し、キャプションがない場合、使用できない場合、または著しく不完全な場合にのみ音声認識（ASR）にフォールバックします。

ワークフロー

入力がYouTubeのURLであることを確認します。
メタデータを収集し、ネイティブ字幕または自動生成キャプションが利用可能かどうかを検査します。
抽出前に、期待されるトランスクリプトの言語を決定します。ユーザーが英語のトランスクリプトを要求した場合は、--language enを渡します。ユーザーがソース言語の保持を要求した場合は、既知の場合に限り音声言語のトラックを優先します。それ以外の場合は、確認されるまで言語は未解決として扱います。
キャプション抽出はASRよりも高速で低コストであるため、これを優先します。
フェッチ直後にreport.jsonを検査し、selected_languageが意図した言語と一致することを確認してから、アセンブルやレンダリングを行います。
キャプション抽出が失敗した場合、著しく不完全な場合、または利用可能なキャプショントラックが言語的に曖昧な場合にのみ、ASRにフォールバックします。
タイトル、公開日、チャンネル、URL、利用可能な場合はソースのチャプターなど、メタデータを収集します。
トランスクリプトをキャプションの断片ではなく、読みやすい段落に正規化します。
タイトル、日付、ソースメタデータ、要約、チャプターリスト、トランスクリプト本文を含むドキュメントを構築します。
最終成果物を現在のプロジェクトフォルダ内にPDFとして保存します。
プロンプトで明示的に要求された場合にのみ、中国語翻訳を追加します。

環境契約

環境が以下を提供することを期待します。

python3
YouTubeページおよび任意のトランスクリプトソースにアクセスするためのネットワークアクセス
キャプションファーストパスでのメタデータおよび字幕抽出のためのyt-dlp
フォールバック用のローカルWhisper互換ASRツールまたはホスト型転写API
scripts/内のバンドルされたスクリプト

必要な機能が不足している場合は、不足している依存関係を正確に伝え、トランスクリプトが完了したと主張する前に停止します。

ソース選択

キャプションファーストパス

ネイティブ字幕または自動生成YouTubeキャプションが存在する場合、このパスを優先します。

最初にメタデータと字幕の利用可能性を取得します。
意図した言語で最適な字幕トラックをダウンロードします。
手動キャプションと自動キャプションの両方が存在する場合は、手動キャプションを優先します。
ユーザーがターゲットトランスクリプト言語を指定した場合は、--languageで明示的に渡します。
ユーザーが言語を指定しない場合は、既知であるか、確実に推論できる場合にのみ音声言語を保持します。利用可能なキャプショントラックが複数の言語にまたがり、音声言語が不明な場合は、キャプションパスを停止し、任意に選択する代わりに曖昧として扱います。
キャプションが部分的である、同期が著しくずれている、または音声の大部分を省略している場合は、ASRに切り替えます。
キャプションフェッチ後、report.jsonを検査し、selected_languageが意図したトランスクリプト言語と一致しない場合は結果を拒否します。

環境で利用可能な場合の便利なツール：

メタデータおよび字幕抽出のためのyt-dlp
存在する場合、scripts/内の正規抽出ラッパー

ASRフォールバックパス

キャプション抽出が利用不可または十分でない場合にのみASRを使用します。

YouTubeオーディオをダウンロードまたはアクセスします。
言語が既知の場合は、ソース言語で文字起こしを実行します。
トランスクリプトでは元の言語を保持します。
デフォルトでは翻訳しません。
最終的な読みやすい記事とPDFの信頼できるソースとしてトランスクリプトを使用します。

利用可能な場合の一般的なオプション：

ローカルWhisper / faster-whisper
ホスト型転写API

障害ポリシー

以下のいずれかに該当する場合は、停止して障害を説明します。

入力が有効なYouTube URLではない
メタデータを取得できない
キャプションが利用不可であり、ASRフォールバックも利用不可である
ASRパスでオーディオのダウンロードが失敗する
信頼できる要約をサポートするにはトランスクリプトが不完全すぎる

作業は可能だが品質が限られている場合は、警告とともに続行します。

キャプションは存在するが、部分的、ノイズが多い、または同期がずれているように見える
ASRは完了したが、句読点や話者境界が弱い
チャプター境界をノイズの多いトランスクリプトテキストから推論する必要がある

以下の場合、明示的な言語で停止して再実行します。

ユーザーが英語のトランスクリプトを期待しており、report.jsonが英語以外のトラックを選択した
ユーザーがソース言語の保持を期待しているが、選択されたキャプション言語が曖昧であるか、明らかに翻訳されている

出力契約

ユーザーが特に要求しない限り、現在のプロジェクトフォルダに整形されたPDFを生成し、以下を含めます。

タイトル
公開日
チャンネルまたは出典を含むソース行
要約またはdek
上部近くのチャプターリスト
元の言語での読みやすいトランスクリプト本文
有用な場合、例えば20分ごとなどの大まかなタイムスタンプマーカーのみ

主要な成果物として、構造化されていない巨大なキャプションブロックを返さないでください。

フォーマットルール

OpenAIのHarness Engineering記事のようなロングフォーム投稿をモデルにした読みやすさを目指します。十分な余白、強力なタイトル階層、コンパクトなメタデータ、明確なセクション区切り、読みやすい段落幅。

YouTube Transcriptなどのオーバーラインまたはセクションラベルで開始します。
タイトルを最初に配置します。
1ページ目では、繰り返されるページヘッダーラベルと上部区切り線ブロックを避けます。
2ページ目以降では、上部区切り線を配置し、そのページ上部からの距離が下部区切り線のページ下部からの距離と一致するようにします。
2ページ目以降では、Sissi Skill - YouTube Transcript to PDFというページラベルをその上部区切り線のすぐ上に配置します。
公開日とソースメタデータをタイトルのすぐ下に配置します。
チャプターリストをドキュメントの上部近くに配置します。
チャプターメタデータが存在する場合は、対応する位置でトランスクリプト本文内にチャプター見出しを再挿入します。
段落は短く読みやすく保ちます。
本文段落を両端揃えにして、テキストブロックの幅が区切り線の幅と一致するようにします。
キャプションの断片を散文のような段落に結合します。
字幕のセグメンテーションによって引き起こされる重複を削除します。
編集上意味がない限り、繰り返される矢印やスタンドアロンの音楽マーカーなどの明らかなノイズを削除します。
話者名をでっち上げないでください。
高密度のタイムスタンプノイズを出力しないでください。
大まかなナビゲーション補助として、20分ごとのマーカーのみを挿入します。
動画が20分未満の場合は、マーカーを完全に省略します。
すべてのページにフッターの余白帯を確保し、灰色の水平線で本文テキストと区切ります。
本文テキストをフッターの区切り線の近くまで配置し、最終行が重なることなく、おおよそその1行上に位置するようにします。

可読性ヒューリスティック

キャプションを正規化する際：

重複する字幕ウィンドウからの正確な繰り返しを重複排除します。
時間間隔、文の終わり、段落の長さに基づいて、長いテキストを段落に分割します。
段落の長さは、字幕のストリームではなく、エッセイの散文のように感じられるものを優先します。
ソースが句読点を提供している場合は、それを保持します。
ソースの句読点が貧弱な場合は、読みやすさのために必要な最小限の句読点のみを追加します。

要約とチャプター

トランスクリプトを構築した後、以下を作成します。

動画の主な主張やポイントに焦点を当てた簡潔な要約
短い見出しを持つチャプターリスト

ソースデータにすでに信頼できるチャプターメタデータが含まれている場合は、それを再利用します。それ以外の場合は、トランスクリプト内のトピックの変化からチャプターを推論します。

例

例1：ポッドキャストトランスクリプトパッケージ

ユーザー：「このYouTubeインタビューをきれいなPDFトランスクリプトに変換してください。」
アクション：
1. メタデータとキャプションの利用可能性を取得します。
2. 利用可能な場合は手動キャプションを優先します。
3. トランスクリプトの段落を正規化します。
4. 要約とチャプターリストを生成します。
5. 現在のプロジェクトフォルダ内にPDFをレンダリングします。
結果：要約とチャプター分割を含む記事スタイルのトランスクリプトPDF。

例2：基調講演からの要約とトランスクリプト

ユーザー：「この基調講演からトランスクリプトを抽出し、各セクションを要約してください。」
アクション：
1. キャプションを抽出するか、ASRフォールバックを使用します。
2. ソースチャプターが存在する場合はそれを再利用し、そうでない場合は推論します。
3. チャプター構造に沿った簡潔な要約を構築します。
4. 最終PDFを保存し、チャットで要約を返します。
結果：生の字幕テキストではなく、使用可能な読み物。

例3：ソース言語の保持

ユーザー：「このスペイン語のYouTubeトークから読みやすいトランスクリプトを作成してください。」
アクション：
1. スペイン語のトランスクリプトを保持します。
2. 明示的に要求されない限り、翻訳しません。
3. キャプションが弱い場合は、ソース品質の問題を報告します。
結果：正直な品質メモ付きのスペイン語トランスクリプトパッケージ。

例4：明示的な翻訳リクエスト

ユーザー：「このYouTube動画からトランスクリプトPDFを作成し、中国語翻訳を追加してください。」
アクション：
1. 最初にソーストランスクリプトを抽出します。
2. 整形されたソース言語トランスクリプトを生成します。
3. 明示的に要求されたため、中国語翻訳を追加します。
結果：ソーステキストと翻訳テキストを明確に区別するトランスクリプトパッケージ。

出力場所

ユーザーが別のパスを要求しない限り、最終的なPDFを現在のプロジェクトフォルダ内に保存します。動画のタイトルからスラッグ化されたファイル名を優先します。

例：

./cult-leaders-have-terrible-pitches.pdf

ヘルパースクリプト

scripts/fetch_youtube_transcript.pyを正規の抽出エントリポイントとして使用します。これはURLの検証、メタデータのフェッチ、キャプションの選択、品質チェック、およびオプションのASRフォールバックを一元化するため、フロー内で最初のスクリプトである必要があります。キャプションが利用不可でオーディオをダウンロードできる場合は、scripts/asr_faster_whisper.pyを使用します。これはローカルのfaster-whisperモデルを使用して、フォールバックパス用のセグメントJSONを書き込みます。

scripts/assemble_transcript.pyを使用して、タイムスタンプ付きセグメントを大まかなマーカー付きの読みやすいトランスクリプト散文に変換します。チャプタータイトルをトランスクリプト本文内の正確な位置に挿入する必要がある場合は、同じスクリプトから段落メタデータJSONも書き込み、それをPDFレンダラーに渡します。信頼できるソースチャプターが存在する場合は、それらもassemble_transcript.pyに渡して、PDFレンダリング前に段落境界がチャプター境界に揃うようにします。

scripts/render_blog_pdf.pyを使用して、外部PDF依存関係なしで、メタデータ、要約、チャプター、トランスクリプトテキストから整形されたPDFに変換します。 scripts/validate_transcript_skill.pyを開発時に使用して、VTT解析、重複クリーンアップ、マーカー挿入、チャプター対応トランスクリプトメタデータ、PDFレンダリングのオフライン回帰チェックを実行します。 scripts/package_skill_release.pyを配布前に使用して、README.md、.git/、tests/、__pycache__/などのリポジトリ専用ファイルを除外したクリーンなzipをビルドします。

典型的なフロー：

python scripts/fetch_youtube_transcript.py "https://www.youtube.com/watch?v=VIDEO_ID" --output-dir ./youtube_transcript_work --language en
sed -n '1,120p' ./youtube_transcript_work/report.json
python scripts/asr_faster_whisper.py ./downloaded-audio.m4a --output ./youtube_transcript_work/segments.json --model small --device cpu --compute-type int8 --beam-size 1 --vad-filter
python scripts/assemble_transcript.py ./youtube_transcript_work/segments.json --output transcript.txt
python scripts/assemble_transcript.py ./youtube_transcript_work/segments.json --output transcript.txt --metadata-output transcript-metadata.json --chapter-breaks-json ./youtube_transcript_work/chapters.json
# 次に、./youtube_transcript_work/metadata.json から title/date/channel を読み取り、レンダラーに渡します。
python scripts/render_blog_pdf.py \
  --title "Cult Leaders Have Terrible Pitches" \
  --date "2025-09-16" \
  --channel "The Knowledge Project Podcast" \
  --summary-file summary.txt \
  --chapters-json ./youtube_transcript_work/chapters.json \
  --transcript-metadata-json transcript-metadata.json \
  --transcript transcript.txt \
  --output ./cult-leaders-have-terrible-pitches.pdf
python scripts/validate_transcript_skill.py
python scripts/package_skill_release.py

品質チェック

結果を返す前に、以下を確認します。

トランスクリプト言語がソースコンテンツと一致していること（翻訳が明示的に要求された場合を除く）
report.jsonのselected_languageが意図したトランスクリプト言語と一致していること
トランスクリプトが実質的に完全であること
チャプターリストが一貫していること
ソースチャプターが存在する場合、インラインチャプター見出しがトランスクリプトの正しい位置に現れていること
隣接するチャプタータイムスタンプが1分未満の間隔である場合、それらを単一のインラインチャプター見出しに統合すること
トランスクリプト本文内のインラインチャプター見出しからタイムスタンプを省略すること
ドキュメントにタイトル、日付、ソースメタデータが含まれていること
PDFがプロジェクトフォルダ内に正常に書き込まれたこと
本文テキストが両端揃えで、区切り線と同じ幅に揃えられていること
本文テキストがフッターの余白帯に食い込むページがないこと
最終ドキュメントが生の字幕ではなく、記事として読みやすいこと

抽出品質が低い場合は、簡単にその旨を述べ、弱点がソースキャプションによるものかASRによるものかを明らかにします。

トラブルシューティング

キャプションが見つからない

原因：動画に手動または自動生成キャプションがない。
対応：ASR依存関係が利用可能な場合のみASRを使用します。それ以外の場合は、停止して不足している機能を報告します。

キャプションが不完全に見える

原因：字幕トラックが音声部分を省略しているか、同期が著しくずれている。
対応：ASRが利用可能な場合はそれに切り替え、キャプションパスが拒否された理由を説明します。

間違った言語トラックが選択された

原因：複数の字幕トラックが存在し、自動的に間違ったものが選択された。
対応：ターゲット言語が既知の場合は、明示的な--languageを指定してfetch_youtube_transcript.pyを再実行します。音声言語が不明で利用可能なキャプショントラックが多言語の場合は、任意に選択する代わりにキャプションパスを曖昧として停止します。

ASRフォールバックが利用不可

原因：ローカルまたはホスト型の文字起こしパスが存在しない。
対応：トランスクリプトが完了したふりをする代わりに、不足している依存関係を報告します。

PDFはレンダリングされるが、フォーマットが劣化している

原因：トランスクリプトブロックが長すぎる、メタデータがない、またはチャプターの配置がノイズが多い。
対応：ファイルを返す前に、トランスクリプトの正規化、チャプター入力、レンダリング入力を再確認します。

ユーザーが要約のみを希望

原因：ユーザーが全文のトランスクリプトを必要としていない。
対応：ユーザーの要望に合わせて、要約とチャプターのアウトラインのみを提供します。完全なトランスクリプト文章は含めません。

動画が非常に長い（3時間以上）

原因：キャプションファイルが大量にあるか、ASR処理に長時間かかる。
対応：開始時間を報告し、ASRの場合は処理の進行状況を提供します。キャプションフェッチのみで進められる場合は、即座に続行します。

中国語翻訳が必要

原因：ユーザーが特に中国語翻訳を要求した。
対応：元の言語のトランスクリプトを完全な読み物として保持し、追加の翻訳セクションを追加します。翻訳が元のテキストよりも後ろに配置され、明確にラベル付けされていることを確認します。元のトランスクリプトのみを翻訳と置き換えないでください。

SissiMeow/codex-skill-YouTube-Transcript-PDF

codex-skill-YouTube-Transcript-PDF とは？

お気に入りのAIに質問する

ドキュメント