ingest-youtube — YouTube-to-vault コネクタ
YouTube の文字起こしを Markdown 形式の Vault に取り込み、クエリ可能な型付きメモリエントリとして保存します。これらのエントリは、下流のスキル (知識グラフ抽出、音声フィンガープリントトレーニング、コンテンツ再利用、アクションアイテム抽出など) で利用できます。
ingest-slack、ingest-whatsapp、ingest-notion、ingest-linear、ingest-github、ingest-gmail と同じパターンです。YouTube を追加するということは、新しいノーマライザーを追加するということであり、新しいアーキテクチャを追加するわけではありません。
使用タイミング
- ユーザーが YouTube の URL を貼り付けて、文字起こしや要約を要求した場合
- ユーザーが
/ingest-youtube <url>と入力して単一の動画を取り込む場合 - ユーザーがトーク、ポッドキャスト、基調講演などを Vault にキャプチャ、同期、取り込み、文字起こし、またはプルするように要求した場合
以下の場合には使用しません:
- 実際の動画ファイルをダウンロードする場合 (直接
yt-dlpを-f bestオプションで使用してください) - チャンネル全体の取り込みや
--daysウィンドウの使用 (このスクリプトは 1 つの動画 URL を 1 度に 1 つずつ取り込みます) - ライブストリーム (文字起こしが安定していません)
- YouTube 以外のソース (Vimeo、Twitch、Twitter Spaces には独自のコネクタがあります)
- Vault ファイルを作成せずに 1 回限り文字起こしを読みたい場合 (
yt-dlp --write-auto-subを直接実行して標準出力にパイプしてください)
仕組み
- 入力を 1 つの YouTube 動画 URL として解析します。
yt-dlpがインストールされているか確認します。インストールされていない場合、スクリプトはインストール手順を表示して終了します:brew install yt-dlp(macOS) またはpip3 install --user yt-dlp。- URL が単一の http(s) YouTube 動画であることを検証し、
yt-dlp --ignore-config --list-subs -- <url>を呼び出して利用可能な字幕を列挙します。 - 字幕の優先順位: 手動字幕 > 自動生成キャプション。手動字幕は作成者が提供する句読点や話者ラベルを保持します。自動生成は大文字で句読点がありません。
yt-dlp --write-sub --sub-lang <lang> --skip-downloadを使用して、最も優先度の高い字幕を VTT としてダウンロードします。デフォルトの言語設定:en,es(英語優先、次にスペイン語)。- VTT のタイミングマーカーを削除し、クリーンな散文段落にマージします。重複行を削除します (自動生成 VTT は行が重複することがあります)。ソースに話者ラベルがある場合は保持します。
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 にある Vault ファイルには、以下のフロントマターが含まれます:
---
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 を再取り込みすると、同じ Vault ファイルが上書きされます。シードスタブのファイル名は video_id をハッシュ化するため、同じソース動画は再実行後も同じスタブファイル名を生成します。再実行はリフレッシュされ、重複は発生しません。
字幕がない場合
yt-dlp --list-subs が手動または自動の字幕を返さない場合、スクリプトはエラーで終了する代わりに、動画のメタデータとソース URL を含むスタブの Vault ノートを書き込みます。--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-* ファミリーの Vault コネクタの一部です。