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).

Use --write-sub for manual subtitles and --write-auto-sub for automatic captions. If a track returns 429/403, do not retry that track; continue with the next candidate in this order, then use Path B if all candidates fail.

VIDEO_URL="YOUTUBE_URL"

# 1. Check subtitles -- read full output, don't grep. Keep the two sections separate.
yt-dlp --list-subs "$VIDEO_URL"

# 2. Get title/channel and derive snake_case filename
TITLE=$(yt-dlp --get-title "$VIDEO_URL" | sed 's/[/:*?"<>|]/-/g')
CHANNEL=$(yt-dlp --print channel "$VIDEO_URL" | sed 's/^NA$//')
snake_case() { echo "$1" | sed 's/[^[:alnum:]]/_/g' | sed 's/__*/_/g' | sed 's/^_//;s/_$//'; }
CHANNEL_SNAKE=$(snake_case "$CHANNEL")
SNAKE_TITLE=$(snake_case "$TITLE")
OUTPUT_MD="Youtube-${CHANNEL_SNAKE:+$CHANNEL_SNAKE-}$SNAKE_TITLE.md"

# 3. Determine the video's source language from TITLE, then select one track in this
#    order: manual source-language subtitle, source-language automatic -orig track,
#    and finally the regular source-language automatic track.
#    Copy the exact language code from --list-subs; manual and automatic codes can
#    differ (for example, zh-Hans vs zh-Hans-zh-Hans). Run only one command below.
#    Manual subtitle:
yt-dlp --write-sub --sub-langs <manual-lang> --skip-download --output "$TITLE" "$VIDEO_URL"
#    Automatic subtitle (-orig or regular source language):
yt-dlp --write-auto-sub --sub-langs <orig-or-title-lang> --skip-download --output "$TITLE" "$VIDEO_URL"

# 4. Verify the .vtt was actually written before converting. If missing, the
#    flag/lang-code combo was wrong (see step 3) or the subtitle API is blocked.
ls "$TITLE.<lang>.vtt"

# 5. Convert VTT to timestamped transcript
echo "Source: [$TITLE]($VIDEO_URL)" > "$OUTPUT_MD"
echo >> "$OUTPUT_MD"
python3 "$SKILL_DIR/scripts/vtt_to_transcript.py" "$TITLE.<lang>.vtt" >> "$OUTPUT_MD"

Note: the bash snake_case strips non-ASCII. For CJK/non-ASCII titles, prefer Path B's naming (Python \w+ keeps Unicode), or sanitize the title in Python.

Path B: Whisper Fallback (HTTP 429/403 or No Subtitles)

python3 "$SKILL_DIR/scripts/whisper_fallback.py" "YOUTUBE_URL" [--lang zh] [--model large-v3-turbo] [--outdir .]

• --lang: source language (e.g. zh, en). Default: auto-detect from audio — do not force English; pick per video (CJK videos → zh).
• --model: large-v3-turbo (default, ~1.62GB, recommended quality/speed balance) → medium (~1.53GB) → small (~484MB, faster) → large-v3 (~3.09GB, maximum quality but slower). tiny and base are also available for low-resource use.
• The script downloads audio → transcribes on CPU → writes the .md → deletes the audio.

Optional: Fetch Comments (Read-Only)

python3 "$SKILL_DIR/scripts/fetch_comments.py" "YOUTUBE_URL" [--sort top|newest] [--max 80]

No files written. Gotchas are documented in the script's docstring.

Output Formats

• .vtt: raw subtitle file with timing markup (Path A only)
• .md: Youtube-<Channel>-<Snake_Case_Title>.md with line-level timestamps [00:01:23.456] text here (both paths)

Common Issues