yt-dlp
Use when downloading YouTube captions, subtitles, or transcripts via CLI. Also handles basic video download. Routes to reference docs for flags, formats, batch processing, and integration with video-pipeline and deepgram-transcription.
| Model | Source |
|---|---|
| sonnet | pack: video-pipeline |
Full Reference
yt-dlp
Section titled “yt-dlp”CLI reference for yt-dlp — YouTube subtitle/caption extraction primary, basic video download secondary. Acts as the “free captions gate” before falling back to paid Deepgram transcription.
Quick Reference
Section titled “Quick Reference”| Item | Value |
|---|---|
| Binary | yt-dlp (via brew install yt-dlp) |
| Version pinned | 2026.02.21 |
| Dependency | ffmpeg (for format conversion) |
| Primary use | --write-auto-subs --skip-download |
| Input | YouTube URL or batch file |
| Output | .srt, .vtt, or .json3 subtitle files |
Reference Index
Section titled “Reference Index”| I want to… | File |
|---|---|
| Extract captions/subtitles, list available tracks, select languages | reference/subtitles.md |
| Process multiple URLs, playlists, output templates | reference/batch.md |
| Choose between SRT/VTT/JSON3, convert formats | reference/formats.md |
| Download video files, select quality/format | reference/video-download.md |
| Connect with video-pipeline, deepgram-transcription | reference/integration.md |
Usage: Read the reference file matching your current task. Each file is self-contained with examples and gotchas.
Prerequisites — MANDATORY CHECK
Section titled “Prerequisites — MANDATORY CHECK”Before running ANY yt-dlp command, run this check and offer to install missing tools:
which yt-dlp && yt-dlp --version || echo "MISSING"which ffmpeg && ffmpeg -version 2>&1 | head -1 || echo "MISSING"If either is missing, tell the user and install for them:
| OS | Install command |
|---|---|
| macOS | brew install yt-dlp ffmpeg |
| Linux (pip) | pip install yt-dlp && sudo apt install ffmpeg |
| Linux (brew) | brew install yt-dlp ffmpeg |
Do not skip this check. Do not assume tools are installed. Offer to install, then install on approval.
Caption Gate Pattern
Section titled “Caption Gate Pattern”YT URL → yt-dlp --list-subs → captions available? YES → yt-dlp extract (free, instant) NO → deepgram-transcription (paid, slower, but works on any audio)Always check for existing captions before transcribing. Saves cost and time.
Announcement
Section titled “Announcement”┏━ 🔧 yt-dlp ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓┃ [action] for [target] ┃┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛