Ingest YouTube Transcripts into Your Vault

Ingest-youtube pulls a single YouTube video's transcript into a markdown vault as a typed, queryable memory entry, following the same normalizer pattern as ingest-slack, ingest-whatsapp, ingest-notion, ingest-linear, ingest-github, and ingest-gmail - adding YouTube means a new normalizer, not a new architecture. Given one video URL, it verifies yt-dlp is installed, lists available subtitles, and prefers manual subs over auto-generated captions (manual subs preserve creator punctuation and speaker labels; auto-gen is uppercase with no punctuation). It downloads the highest-priority subtitle as VTT with a default language preference of English then Spanish, strips VTT timing markers, merges the text into clean prose paragraphs, and deduplicates the repeated lines that auto-generated VTTs are prone to, preserving speaker labels where the source had them. It also pulls video metadata (title, channel, upload date, duration, video_id, URL) and writes everything to External Inputs/YouTube/<channel-slug>/<YYYY-MM-DD>-<video-slug>.md with YAML frontmatter carrying the video ID, URL, channel, title, dates, language, subtitle source, word count, and ingestion timestamp. The transcript is scanned for trigger keywords - decision, framework, model, principle, "the lesson is," playbook, anti-pattern, case study - and each match spawns a writing-seed stub in Meta/Captures/ so it lands in the captures aggregator. A run prints a summary of the file path, transcript word count, language, and seeds detected. Re-ingesting the same URL overwrites the same vault file, and seed-stub filenames hash the video_id so repeated runs refresh rather than duplicate.

Use it when a user pastes a YouTube URL and asks for a transcript or summary, runs /ingest-youtube <url> on one video, or asks to capture, sync, ingest, transcribe, or pull a talk, podcast, or keynote into the vault. Do not use it to download the actual video file (use yt-dlp -f best directly instead), for channel-wide ingestion or --days windows (it only ingests one video URL per run), for live streams (their transcripts are not stable), for non-YouTube sources like Vimeo, Twitch, or Twitter Spaces (they have their own connectors), or for a one-off transcript read where no vault file is wanted (run yt-dlp --write-auto-sub directly and pipe to stdout instead).

Input is a single http(s) YouTube video URL, plus optional --vault <path> (defaults to the $VAULT_ROOT env var or the current directory) and --lang <code> (defaults to en,es). Output is the markdown vault file described above, plus any writing-seed stub files for trigger-keyword matches. If yt-dlp --list-subs finds no manual or auto subtitles, the script writes a metadata-only stub vault note instead of failing silently - the --whisper flag is accepted for a future local-transcription fallback but currently reports that the fallback is not implemented; a manual workaround is to transcribe the audio with a local Whisper workflow and add the transcript before rerunning ingest.

python3 ingest.py <youtube-url> [--vault <path>] [--lang <code>]

Depends on yt-dlp (required - install via brew install yt-dlp or pip3 install --user yt-dlp) for subtitle enumeration, download, and video metadata. whisper-cpp is an optional dependency for a manual transcription fallback performed outside the script itself. The skill is bundled in adelaidasofia/ai-brain-starter, a verification harness around an AI agent built so memory compounds instead of corrupts, and belongs to that project's ingest-* family of vault connectors.

Anyone running a personal knowledge vault who wants YouTube talks, podcasts, and keynotes captured as structured, searchable notes rather than left as an unindexed link - particularly useful ahead of downstream skills like knowledge-graph extraction, voice-fingerprint training, content repurposing, or action-item extraction that need a typed transcript to work from.