ingest-youtube — YouTube-to-vault コネクタ
YouTube のトランスクリプトを、クエリ可能な型付きメモリエントリとしてマークダウンボールトに取り込みます。後続のスキル(知識グラフ抽出、音声フィンガープリント学習、コンテンツ再利用、アクションアイテム抽出)がこれを利用できます。
ingest-slack、ingest-whatsapp、ingest-notion、ingest-linear、ingest-github、ingest-gmail と同じパターンです。YouTube を追加するということは、新しいノーマライザーが追加されただけで、アーキテクチャが新しくなったわけではありません。
使用するタイミング
- ユーザーが YouTube の URL を貼り付けて、トランスクリプトまたは要約を求めた場合
- ユーザーが
/ingest-youtube <url>と入力して1本の動画を指定した場合 - ユーザーがトーク、ポッドキャスト、キーノートをキャプチャ、同期、取り込み、文字起こし、またはボールトにプルするよう依頼した場合
使用してはいけないケース:
- 実際の動画ファイル自体をダウンロードする場合(
yt-dlpを直接-f bestオプションで使用) - チャンネル全体の取り込みや
--daysウィンドウでの処理(このスクリプトは一度に1つの動画 URL のみを取り込みます) - ライブストリーム(トランスクリプトが安定していません)
- YouTube 以外のソース(Vimeo、Twitch、Twitter Spaces にはそれぞれ専用のコネクタがあります)
- ボールトファイルを必要としない1回限りのトランスクリプト読み取り(
yt-dlp --write-auto-subを直接実行し、標準出力にパイプ)
動作の仕組み
- 入力を1つの YouTube 動画 URL として解析します。
yt-dlpがインストールされているか確認します。インストールされていない場合、スクリプトはインストール手順を表示して終了します:brew install yt-dlp(macOS)またはpip3 install --user yt-dlp。yt-dlp --list-subs <url>を呼び出して、利用可能な字幕を一覧表示します。- 字幕の優先順位: 手動字幕 > 自動生成キャプション。手動字幕は作成者が提供する句読点と話者ラベルを保持します。自動生成字幕は大文字で句読点がありません。
- 最も優先順位の高い字幕を、
yt-dlp --write-sub --sub-lang <lang> --skip-downloadで VTT としてダウンロードします。デフォルトの言語設定:en,es(英語優先、スペイン語が次)。 - VTT のタイミングマーカーを削除し、クリーンな散文パラグラフに結合します。重複する行を除去します(自動生成 VTT は行が2重になることがあります)。ソースに話者ラベルがあった場合は保持します。
yt-dlp --print-json --skip-downloadで動画メタデータ(タイトル、チャンネル、アップロード日、再生時間、video_id、URL)を取得します。- チャンネル名と動画タイトルをスラッグ化します。
External Inputs/YouTube/<channel-slug>/<YYYY-MM-DD>-<video-slug>.mdに書き込みます。 - トランスクリプトからトリガーキーワード(decision、framework、model、principle、"the lesson is"、playbook、anti-pattern、case study)をスキャンします。一致するものごとに、
Meta/Captures/<YYYY-MM-DD>-youtube-<channel-slug>-<video-id>.mdにライティングシードスタブを作成し、そのシードがキャプチャアグリゲーターに届くようにします。 - サマリーを表示します: ファイルパス、トランスクリプトの単語数、言語、検出されたシード。
呼び出し方法
python3 ingest.py <youtube-url> [--vault <path>] [--lang <code>]
デフォルト:
--vault:$VAULT_ROOT環境変数、またはカレントディレクトリ--lang:en,es(英語優先、スペイン語が次。一般的なバイリンガルデフォルトに適合)--whisper: 将来のフォールバックフラグとして受け入れられますが、このバージョンでは字幕がない場合にスタブを作成します
出力契約
ボールトファイル External Inputs/YouTube/<channel-slug>/<YYYY-MM-DD>-<video-slug>.md には以下のフロントマターが含まれます:
---
type: external-input
source: youtube
video_id: <11桁のID>
url: https://www.youtube.com/watch?v=<id>
channel: <チャンネル名>
channel_url: https://www.youtube.com/<ハンドル>
title: <動画タイトル>
upload_date: <YYYY-MM-DD>
duration_seconds: <整数>
language: <ISOコード>
subtitle_source: manual | auto | whisper
word_count: <整数>
ingested_at: <ISO 8601 タイムスタンプ>
---
本文は、クリーニングされたトランスクリプトが段落散文として記述されます。ソースに話者ラベルがある場合は、ターンごとに **<話者>:** <テキスト> の形式でフォーマットします。
冪等性
同じ動画 URL を再取り込みすると、同じボールトファイルが上書きされます。シードスタブのファイル名は video_id をハッシュ化するため、同じソース動画からは再実行時にも同じスタブファイル名が生成されます。再実行は更新を行い、決して重複しません。
字幕がない場合
yt-dlp --list-subs が手動または自動字幕を返さない場合、スクリプトはエラーで終了する代わりに、動画メタデータとソース URL を含むスタブボールトノートを作成します。--whisper フラグは将来のローカル文字起こしフォールバック用に予約されており、現在はフォールバックが実装されていないことを報告します。
手動でフォールバックするには、yt-dlp でオーディオをダウンロードし、ローカルの Whisper ワークフローで文字起こしを行い、取り込みを再実行する前にキャプションまたはトランスクリプトテキストを追加してください。
制限事項
- 1回の実行で1つの YouTube 動画 URL のみを取り込みます。チャンネルハンドル、プレイリスト、
--daysウィンドウは対象外です。 yt-dlpが返す字幕に依存します。字幕がない動画は、トランスクリプトではなくメタデータスタブが生成されます。- このバージョンでは動画ファイルのダウンロードや組み込みの Whisper 文字起こしは行いません。
- ネットワークの可用性、YouTube の字幕アクセス、ローカルの
yt-dlpの動作が取り込みの成否を左右します。
受け入れテスト
YouTube に最初にアップロードされた動画で実行:
python3 ingest.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --vault /tmp/test
期待される出力:
Wrote 39 words to /tmp/test/External Inputs/YouTube/jawed/2005-04-24-me-at-the-zoo.md. Language: en. Subtitle source: manual.
出力ファイルには有効なフロントマターとクリーンな散文本文が含まれています。
依存関係
yt-dlp(必須):brew install yt-dlpまたはpip3 install --user yt-dlpでインストールwhisper-cpp(このスクリプト外での手動フォールバック用。オプション)
ソース
adelaidasofia/ai-brain-starter にバンドルされています。これは AI エージェントの検証ハーネスであり、メモリが破損するのではなく蓄積されるようにします。このスキルは、ingest-* 系のボールトコネクタファミリーの一部です。