YouTube Transcript Extractor

Give it a YouTube link → get the full spoken text back. Handles any length and any URL form (watch?v=, youtu.be/, /shorts/, /live/, or a bare 11-char id). The worker is yt_transcript.py in this skill directory; the steps below drive it.

Prerequisites

• Tools/CLIs: Python 3.x; yt-dlp + youtube-transcript-api (layers 1–2); faster-whisper
  • ffmpeg on PATH (layer 3, ASR fallback only — not needed when captions exist)
• Files: yt_transcript.py (ships in this skill directory)
• Services/network: reachable youtube.com, ideally from a non-cloud/residential IP — YouTube blocks known cloud-provider IPs for caption endpoints (see Gotchas)
• User inputs & decisions: the YouTube URL; optional --out path, --meta, --lang, --force-asr/--asr-model — collect these up front
• Declared fallback: the 3-layer chain — youtube-transcript-api → yt-dlp subtitles → yt-dlp audio + faster-whisper ASR — legal, no mid-run user input needed

STEP 0: Preflight

python -c "import yt_dlp, youtube_transcript_api" 2>&1   # layers 1-2, required
python -c "import faster_whisper" 2>&1                    # layer 3, optional
ffmpeg -version >/dev/null 2>&1 && echo ffmpeg-ok || echo ffmpeg-missing   # layer 3, optional

Collect the URL and output preferences (STEP 1 below) while the user is present. If BOTH yt_dlp and youtube_transcript_api are missing, report that in one line and HARD-STOP (pip install yt-dlp youtube-transcript-api) — no layer could run. If only faster_whisper/ ffmpeg are missing, warn once and continue — the ASR layer degrades gracefully rather than blocking layers 1–2.

STEP 1: Resolve the link and pick the output

Take the YouTube URL (or id) from the user. Decide where the text should go:

• to the chat → run plain (stdout),
• to a file → pass --out <file>. Save transcripts with a .md extension (Markdown — reads cleanly in editors and previews, and is the project default). If the user asks for "filename = video name", first read the title (--meta --json), strip Windows-illegal characters <>:"/\|?*, and append .md.
• Save transcript files OUTSIDE the project's git tree (e.g. a sibling transcripts/ folder) so deliverables don't pollute the repo.

STEP 2: Run the extractor

# clean text to stdout
python .claude/skills/youtube-transcript/yt_transcript.py "<URL>"

# save to a file (use a .md extension), include title/channel/duration
python .claude/skills/youtube-transcript/yt_transcript.py "<URL>" --meta --out transcript.md

# machine-readable: transcript + which method won + per-layer attempts
python .claude/skills/youtube-transcript/yt_transcript.py "<URL>" --json

Flags: --lang en (preferred caption language) · --out FILE · --json · --meta · --force-asr (skip captions, transcribe audio directly) · --asr-model tiny|base|small|medium|large-v3.

STEP 3: Read the result and let the fallback chain work

Prefer --json when scripting: parse transcript and report the method used. The tool tries three layers automatically, first that yields text wins:

1. youtube-transcript-api — fast, clean text; manual or auto captions. Primary.
2. yt-dlp subtitles — downloads the VTT track and de-duplicates it; succeeds on some tracks where layer 1 hits YouTube's PoToken block, with no extra services.
3. yt-dlp audio + faster-whisper (ASR) — only when a video has no captions at all. Downloads audio, runs local speech-to-text. This is the "do whatever it takes" layer that off-the-shelf YouTube-transcript MCP servers do not have.

If transcript is null, read attempts to see why each layer failed (e.g. blocked, no subs, ASR package missing).

STEP 4: Save and report

Write the file if requested (STEP 1 path), then report: the method that won, word/char count, and the saved path. If you produced a deliverable file for the user, surface it.

Setup (one-time)

pip install yt-dlp youtube-transcript-api   # layers 1 & 2
pip install faster-whisper                  # layer 3 (ASR); needs ffmpeg on PATH

Verified with: yt-dlp 2026.6.9, youtube-transcript-api 1.2.4, faster-whisper 1.2.1, ffmpeg 8.1, Python 3.13. Output is forced to UTF-8 so non-English transcripts are not corrupted on Windows (cp1252).

Verified test results

All three layers exercised independently and end-to-end.

Gotchas & limits

• Run from a residential / non-cloud IP. YouTube blocks known cloud-provider IPs (AWS/GCP/Azure) for the caption endpoints; a cloud host needs a residential proxy or the yt-dlp PoToken plugin.
• PoToken edge case. Some caption tracks return an empty body to layer 1 (youtube-transcript-api issue #592, no upstream fix). Layer 2 covers many of these; for the rest, install the bgutil PoToken plugin.
• ASR cost is time, not money. Fully local + free. A 2-hour video on CPU with base is slow — use tiny/base for speed, small+ for accuracy. ASR is imperfect (tiny rendered "trunks" as "prompts"); prefer captions when they exist.
• No hard volume cap, but YouTube temporarily rate-limits heavy bulk scraping from one IP — space requests out for hundreds of videos.

Why this over an off-the-shelf MCP

Surveyed servers (kimtaeyoon83, anaisbetts/mcp-youtube, jkawamoto, sinco-lab) are all caption-only — they error on videos with no captions. This skill's layer-3 ASR fallback is what makes "get the transcript of any video" actually hold.