youtube-transcript

A Claude Code skill that pulls existing captions from a YouTube video via yt-dlp. This is the captions-API path — fast, no GPU, no audio download. For videos with no captions, or for non-YouTube media, see the companion transcribe-video skill, which runs ASR locally.

What it does

Given a YouTube URL or ID, the skill:

1. Asks yt-dlp for the video's subtitle tracks.
2. Tries manual (human-authored) captions in the requested language(s), then falls back to YouTube's auto-generated ones.
3. Writes the result as a .vtt file named <video-id>.<lang>.vtt under ./transcripts (or wherever -o points).
4. Optionally emits a deduplicated plain-text .txt alongside, useful for summarisation or quoting.

Supported inputs: https://www.youtube.com/watch?v=…, https://youtu.be/…, https://www.youtube.com/shorts/…, or a bare 11-char video ID.

Requirements

• yt-dlp on $PATH. On macOS: brew install yt-dlp. On Linux: use your package manager or pipx install yt-dlp.
• awk (POSIX). Present on every Unix.

That's it. Pure shell — no Python deps, no models to download.

Installation as a Claude Code skill

Clone into your Claude Code skills directory:

git clone https://github.com/saralilyb/youtube-transcript.git \
  ~/.claude/skills/youtube-transcript

Claude Code picks it up on next launch. Then ask Claude something like "get the transcript of this YouTube video" and paste a URL.

Standalone use (no Claude)

The script works on its own:

# Default: English captions, VTT only, into ./transcripts/
~/.claude/skills/youtube-transcript/scripts/fetch-youtube-transcript.sh \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"

# Also emit a deduplicated plain-text .txt
~/.claude/skills/youtube-transcript/scripts/fetch-youtube-transcript.sh -p \
  "https://youtu.be/jNQXAC9IVRw"

# Language priority list (try Japanese first, fall back to English)
~/.claude/skills/youtube-transcript/scripts/fetch-youtube-transcript.sh -l ja,en \
  "https://www.youtube.com/watch?v=…"

# Discover what subtitle tracks the video actually has
~/.claude/skills/youtube-transcript/scripts/fetch-youtube-transcript.sh -L \
  "https://www.youtube.com/watch?v=…"

# Custom output directory
~/.claude/skills/youtube-transcript/scripts/fetch-youtube-transcript.sh \
  -o /tmp/subs "https://www.youtube.com/watch?v=…"

The script prints VTT: <path> (and TXT: <path> with -p) on success, exits non-zero with a clear message if no matching captions exist.

Caveats

• No captions at all. Reach for transcribe-video to run ASR locally.
• Age-restricted / members-only / private videos. yt-dlp will fail without cookies. If you need them, run yt-dlp --cookies-from-browser firefox directly; cookie auth is out of scope for this skill.
• Auto-generated captions. YouTube's native format builds cues progressively — each new cue repeats the previous one plus a new word. The -p text output deduplicates exact-line repeats, but very chatty auto-subs may still show some redundancy. The full VTT is always there if you want to redo the cleanup.
• Rate limits. YouTube throttles aggressive clients. If you hit a 429, wait a few minutes or upgrade yt-dlp (brew upgrade yt-dlp) — extractor fixes ship frequently.

License

MIT