| name | talk-fetch |
| description | Fetch the best subtitle track for a YouTube URL via yt-dlp. Use when the user gives a YouTube link and asks for "the captions" / "the SRT" / "subtitles" — or as the first step of the talk-distill pipeline. Probes available tracks, prefers human-authored over auto-captions and `<lang>-orig` over plain `<lang>`, downloads, converts to SRT. |
| version | 0.1.0 |
| last_reviewed | 2026-05-26T00:00:00.000Z |
Talk Fetch — Sub Skill
Single-step: turn a YouTube URL into a captions.SRT file in the target
directory. Used as the entry point of the talk-distill pipeline,
but also fine standalone when the user just wants the captions.
When to invoke
- User pastes a YouTube URL and asks for captions / subtitles / SRT.
- First step of
talk-distill when no captions.SRT exists in the
target subdir.
- User asks to "re-fetch" because the previous SRT was for the wrong
language or track.
Preflight: yt-dlp version
The yt-dlp version is the single biggest source of "it doesn't work."
YouTube tightens its captions endpoint periodically, and yt-dlp builds
older than ~6 months frequently can list captions but fail to download
them ("Did not get any data blocks").
yt-dlp --version
If the user is not Avi (different setup), suggest installing from the
GitHub releases page rather than relying on apt/brew packages, which lag.
Probe available tracks
yt-dlp --list-subs --skip-download "$URL" 2>&1 | head -80
Two sections appear in the output:
- "Available subtitles" — human-authored subs uploaded by the channel
owner or auto-generated by professional services. Prefer these.
- "Available automatic captions" — YouTube's ASR (auto-speech-
recognition) output. Use if no human subs exist.
Within auto-captions, two English variants typically show up:
en-orig (English Original) — ASR on the original audio language. Best
raw material for an English talk.en (English) — sometimes identical to en-orig, sometimes a
translated-then-back fallback. Prefer en-orig.
If multiple languages are available and the talk's audio language is
non-English, prefer <source-lang>-orig over translations.
Fetch the chosen track
mkdir -p "$SUBDIR"
yt-dlp --skip-download \
--write-auto-subs \
--sub-langs "$LANG_CODE" \
--convert-subs srt \
--output "$SUBDIR/%(title)s.%(ext)s" \
"$URL"
Flag explanations:
--write-auto-subs if pulling from "automatic captions"; use
--write-subs instead if pulling from "available subtitles" (human-
authored).--sub-langs en-orig (or whatever code chosen above).--convert-subs srt — yt-dlp's native output for YouTube is VTT;
this converts in a post-processing step.--skip-download — we only want the captions, not the video.--output "..." — yt-dlp will write <title>.<lang>.srt. Plan a
rename to captions.SRT in the next step.
Rename to the canonical filename
mv "$SUBDIR/<title>.<lang>.srt" "$SUBDIR/captions.SRT"
This matches the project convention (captions.SRT with uppercase
extension, mirroring warmed-skills).
Output
${SUBDIR}/captions.SRT — the SRT file ready for talk-transcribe.
Caveats
- Auto-captions only — for many videos, there are no human-authored
subs. The downstream
talk-transcribe skill is built around the YouTube
rolling-caption format and works on auto-captions. If you pull human-
authored subs, the dedup heuristic may unnecessarily strip duplicate
lines that were intentional (e.g. song lyric repeats). Spot-check.
- The
--output template uses the video title verbatim, which can
contain characters awkward for shells (quotes, slashes). The rename
step normalizes this.
- Description metadata can sometimes name the second speaker / Q&A
participants — worth a
yt-dlp --print description "$URL" pass if the
downstream transcribe is going to use named speakers.
Deep reference
workflow_notes.md §"Steps taken (with gotchas)"
documents what went wrong the first time this was run (the yt-dlp version
wall, the rolling-caption shape discovery, etc.).
