youtube-dlp-python

YouTube Transcript Downloader

Download transcripts from YouTube. Primary: yt-dlp subtitles (instant, free). Fallback: faster-whisper local transcription when the subtitle API is blocked or no subtitles exist.

All Python scripts live in $SKILL_DIR/scripts/.

Decision

1. Check subtitles first: yt-dlp --list-subs "URL". If any exist → Path A (yt-dlp subtitles).
2. If no subtitles exist, or Path A cannot download a usable subtitle after trying its track-selection order → Path B (Whisper fallback). Do NOT retry the same failed track; audio downloads use a different CDN and are normally unaffected.

Environment Check

# yt-dlp: try PATH, then macOS ~/.zshrc, then ~/.venv; install only if all fail.
# (macOS: VS Code's terminal may not load ~/.zshrc, so source it manually.)
source ~/.zshrc 2>/dev/null
export PATH="$HOME/.venv/bin:$PATH"
command -v yt-dlp >/dev/null || ~/.venv/bin/pip install -U "yt-dlp[default]"

# faster-whisper (installs PyAV automatically) -- only needed for Path B
~/.venv/bin/python3 -c "from faster_whisper import WhisperModel; import av" 2>/dev/null \
  || ~/.venv/bin/pip install faster-whisper

Output Location

Let the caller decide: user-specified path > AGENTS.md convention > current working directory. Do NOT hardcode a machine-specific path.

Filename is always Youtube-<Channel>-<Snake_Case_Title>.md, and the first line must be Source: [Title](URL).

Path A: yt-dlp Subtitles (Preferred)

Within Path A, select the language in this order:

1. Determine the video's source language from its title (unless the user explicitly requests a different language; for example, English/Latin → en, Simplified Chinese → zh-Hans, Traditional Chinese → zh-Hant).
2. If Available subtitles contains a manual track in that language, use it.
3. Otherwise, use the matching original-language automatic track whose exact code ends in -orig (for example, en-orig).
4. If no matching -orig track exists, use the non--orig automatic track for the video's source language (for example, en, zh-Hans, or zh-Hant).