Ingest YouTube Transcripts into Your Vault

This skill pulls a YouTube video transcript into a queryable markdown vault. It uses yt-dlp for subtitle discovery, cleans the VTT subtitle file into prose, adds metadata frontmatter, and creates capture-seed stubs. The resulting notes are typed-memory entries that downstream skills, such as knowledge graph extraction, voice-fingerprint training, content repurposing, and action-item extraction, can act on. It follows the same pattern as sibling ingest skills for Slack, WhatsApp, Notion, Linear, GitHub, and Gmail, so adding YouTube meant a new normalizer, not a new architecture.

How it works, step by step:

1. Parse the input as one YouTube video URL.
2. Verify yt-dlp is installed. If not, the script exits with install instructions (Homebrew, or pip with the user flag).
3. Validate the URL as a single http or https YouTube video and enumerate available subtitles.
4. Choose subtitles by priority: manual subtitles first, then auto-generated captions. Manual subtitles keep creator punctuation and speaker labels, while auto-generated ones are uppercase with no punctuation.
5. Download the best subtitle as VTT. The default language preference is English first, Spanish second.
6. Strip timing markers, merge into clean paragraphs, and deduplicate repeated lines, since auto-generated VTT files are line-doubled.
7. Pull video metadata: title, channel, upload date, duration, video ID, and URL.
8. Slugify the channel and title and write the note under an External Inputs folder for YouTube, grouped by channel and dated.
9. Scan the transcript for trigger keywords such as decision, framework, model, principle, "the lesson is", playbook, anti-pattern, and case study, and create a writing-seed stub for each match in a Meta Captures folder.
10. Print a summary with the file path, word count, language, and seeds detected.

Use it when the user pastes a YouTube URL and asks for a transcript or summary, uses the /ingest-youtube command for a single 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 video file itself (use yt-dlp directly), for channel-wide ingestion or day windows (it takes one URL per run), for live streams because their transcripts are not stable, for non-YouTube sources such as Vimeo, Twitch, or Twitter Spaces, or for one-off reads where the user does not want a vault file.

Invocation takes a URL, an optional vault path (defaulting to the VAULT_ROOT environment variable or the current directory), and an optional language code:

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

The output note has frontmatter with the type external-input, source youtube, video ID, URL, channel, title, upload date, duration in seconds, language, subtitle source (manual, auto, or whisper), word count, and ingestion timestamp. The body is the cleaned transcript as paragraph prose, with speaker turns formatted in bold when the transcript had speaker labels. Re-ingesting the same URL overwrites the same file, and seed stub filenames hash the video ID, so re-runs refresh rather than duplicate.

• yt-dlp is required. whisper-cpp is optional for a manual fallback outside the script.
• The script is bundled in the ai-brain-starter repository by adelaidasofia, under the MIT license, and belongs to the ingest family of connectors.

If no manual or auto subtitles exist, the script writes a stub note with the video metadata and source URL instead of failing silently. The whisper flag is reserved for a future fallback, and this version does no built-in transcription. For a manual fallback, download the audio, transcribe with your local Whisper workflow, add the text, and rerun. The acceptance test uses the first video ever uploaded to YouTube and expects a note with 39 words, English language, and manual subtitles.

It is for people who keep a markdown knowledge vault, such as Obsidian users, and want talks, podcasts, and keynotes captured as searchable notes with metadata and ready-made prompts for follow-up writing.