| name | youtube-transcribe-yt-dlp |
| description | Use when a user needs YouTube subtitles or transcript text from a URL using yt-dlp only, with no video download and no browser automation fallback. |
YouTube Transcript with yt-dlp Only
Overview
Extract subtitle tracks from YouTube and produce transcript text files with yt-dlp only.
Core principle: subtitle extraction only, never video/audio download, never browser automation.
When to Use
- User asks for YouTube transcript, captions, subtitles, or subtitle-to-text export.
- User provides one or more YouTube URLs (
youtube.com/watch, youtu.be, youtube.com/shorts).
- User wants a fast CLI workflow with
yt-dlp.
When NOT to Use
- User asks for full speech-to-text transcription from audio.
- User asks to download video or audio files.
- User requires browser automation tools.
Hard Rules
- Use
yt-dlp only.
- Always include
--skip-download.
- Never use browser automation fallback.
- Never download video/audio for transcription.
- If subtitles are unavailable, report clearly and stop.
Quick Reference
| Goal | Command |
|---|
| List available subtitle languages | yt-dlp --list-subs "<URL>" |
| Download manual + auto subs only | yt-dlp --skip-download --write-subs --write-auto-subs --sub-langs "en.*,en" --sub-format "vtt" -o "%(title).180B [%(id)s].%(ext)s" "<URL>" |
| Restrict filename characters | Add --restrict-filenames |
Workflow
digraph youtube_transcript_flow {
rankdir=TB;
"Valid YouTube URL?" [shape=diamond];
"Check yt-dlp available" [shape=box];
"List subtitle tracks" [shape=box];
"Any subtitle track available?" [shape=diamond];
"Download subs with --skip-download" [shape=box];
"Convert VTT/SRT to TXT" [shape=box];
"Report output files" [shape=box];
"Stop: explain limitation" [shape=box];
"Valid YouTube URL?" -> "Check yt-dlp available" [label="yes"];
"Valid YouTube URL?" -> "Stop: explain limitation" [label="no"];
"Check yt-dlp available" -> "List subtitle tracks";
"List subtitle tracks" -> "Any subtitle track available?";
"Any subtitle track available?" -> "Download subs with --skip-download" [label="yes"];
"Any subtitle track available?" -> "Stop: explain limitation" [label="no"];
"Download subs with --skip-download" -> "Convert VTT/SRT to TXT";
"Convert VTT/SRT to TXT" -> "Report output files";
}
- Validate YouTube URL format.
- Verify
yt-dlp is available:
yt-dlp --version
If unavailable, ask user to install yt-dlp and stop.
- Inspect subtitle availability:
yt-dlp --list-subs "<URL>"
- Download subtitle files only:
yt-dlp --skip-download --write-subs --write-auto-subs --sub-langs "en.*,en" --sub-format "vtt" -o "%(title).180B [%(id)s].%(ext)s" "<URL>"
- Convert
.vtt or .srt to plain text transcript.
Example Conversion
from pathlib import Path
import html
import re
def subtitle_to_text(path: Path) -> Path:
out = path.with_suffix(".txt")
seen = set()
lines = []
for raw in path.read_text(encoding="utf-8", errors="ignore").splitlines():
line = raw.strip()
if not line:
continue
if line == "WEBVTT" or "-->" in line or line.isdigit():
continue
line = re.sub(r"<[^>]+>", "", line)
line = html.unescape(line).strip()
if line and line not in seen:
seen.add(line)
lines.append(line)
out.write_text("\n".join(lines) + "\n", encoding="utf-8")
return out
Common Mistakes
| Mistake | Fix |
|---|
Forgetting --skip-download | Always include it in subtitle extraction commands |
| Falling back to browser automation | Do not use any browser automation path |
| Falling back to audio transcription | Do not download audio/video; report subtitle unavailability |
| Hardcoding one language only | Check --list-subs first, then choose --sub-langs |
Rationalization Table
| Excuse | Reality |
|---|
| "If yt-dlp fails, browser automation is fine" | This skill explicitly forbids browser automation |
| "I'll download audio and run Whisper" | Out of scope: subtitle extraction only |
| "No subtitles available, I should improvise" | Report limitation and stop |
| "I'll skip listing tracks and guess language" | Listing tracks prevents wrong language assumptions |
Red Flags - STOP and Correct
- Any command without
--skip-download
- Any mention of Playwright, DevTools MCP, Selenium, or browser fallback
- Any mention of Whisper or speech-to-text from downloaded audio
- Claiming transcript success without produced subtitle/text file path
