--- name: youtube-transcripts description: > Download transcripts (auto-captions) for videos from a YouTube channel within a date range, as timestamped markdown linked back to the source video. Use when the user wants to grab transcripts/subtitles/captions from a channel, e.g. "download transcripts for all AI Daily Brief videos from July 2026", "get the captions from this channel for last month", "pull transcripts between two dates". Requires yt-dlp and ffmpeg installed. --- # YouTube Channel Transcripts Downloads English auto-caption transcripts for a channel's videos in a given date range and leaves one markdown file per video, with frontmatter linking it back to the source video. Lines are timestamped by default; `--no-timestamps` drops the times and leaves the prose. ## Requirements `yt-dlp` and `ffmpeg` must be on PATH. ```bash yt-dlp --version && ffmpeg -version | head -1 ``` If missing on macOS: `brew install yt-dlp ffmpeg`. ## Parameters - **channel_url** (required) — channel URL, e.g. `https://www.youtube.com/@AIDailyBrief/videos`. The `/videos` suffix is added automatically if absent. - **start** — inclusive start date, `YYYYMMDD`. Defaults to 7 days ago. - **end** — inclusive end date, `YYYYMMDD`. Defaults to today. - **max** (optional) — cap on number of transcripts. - **--no-timestamps** (optional flag, goes first) — omit the `[HH:MM:SS]` prefixes. Still markdown, still with the same frontmatter; only the per-line times go away. - **--chunk N** (optional flag, goes first) — group the text into ~N-second paragraphs instead of one line per caption line. `--chunk 30` reads well as prose; the default is better for grepping and citing exact moments. Combines with `--no-timestamps` for plain paragraphs. Timestamps are the default — don't pass a flag for them. Output is always `.md`, and the intermediate `.srt` is never left behind. Ask the user for the channel URL if it isn't given. **If the request has no date range, ask for one before running.** An active channel can have thousands of videos, and a request that doesn't mention dates is far more likely to be an oversight than a request for the entire back catalog. Offer the last 7 days as the default and let the user widen it. Only skip the question when the user has already stated a range, said something like "everything" or "all of it", or already declined to narrow it. Convert natural-language ranges yourself ("July 2026" → `20260701` `20260731`, "last month", "since May"). Look up today's date rather than assuming it. The script applies the same 7-day default on its own if dates are omitted, so a forgotten range can't turn into a full-catalog download — but ask first rather than relying on that. ## Usage ```bash scripts/fetch_transcripts.sh [--no-timestamps] [--chunk N] [start_YYYYMMDD] [end_YYYYMMDD] [max] ``` Omitting the dates fetches the last 7 days and says so. Example — all July 2026 videos from AI Daily Brief, as timestamped markdown: ```bash scripts/fetch_transcripts.sh "https://www.youtube.com/@AIDailyBrief/videos" 20260701 20260731 ``` Example — at most 5 transcripts: ```bash scripts/fetch_transcripts.sh "https://www.youtube.com/@AIDailyBrief/videos" 20260701 20260731 5 ``` Example — timestamps grouped into 30-second paragraphs: ```bash scripts/fetch_transcripts.sh --chunk 30 "https://www.youtube.com/@AIDailyBrief/videos" 20260701 20260731 ``` Example — prose without timestamps: ```bash scripts/fetch_transcripts.sh --no-timestamps "https://www.youtube.com/@AIDailyBrief/videos" 20260701 20260731 ``` Output lands in the current directory as `YYYYMMDD - Title [VIDEOID].md`. The video ID is kept in the filename so a transcript can always be traced back to its source, and every file carries it in YAML frontmatter regardless of mode: ```markdown --- title: Is Kimi K3 Really Fable Class date: 20260721 video_id: lmQqiWQF_8I url: https://www.youtube.com/watch?v=lmQqiWQF_8I --- # Is Kimi K3 Really Fable Class Link to any moment: `https://www.youtube.com/watch?v=lmQqiWQF_8I&t=s` [00:00:00] Today on the AI Daily Brief, did we [00:00:02] actually just get a fable level open ``` With `--chunk 30`, one paragraph per 30 seconds instead of one line per caption line. With `--no-timestamps`, the same file minus the `[HH:MM:SS]` prefixes and the deep-link hint — the frontmatter is unchanged. To deep-link a quote, convert its `[HH:MM:SS]` to seconds and append `&t=s` to the `url` from the frontmatter — no lookup or web search needed. ## How it works - Channels list newest-first, so the script uses `--break-match-filters` on the start date to stop walking the catalog once it passes below the range — it does not scan all videos. - `--sub-langs en` (not `en.*`) avoids downloading both `en` and `en-orig`, which are duplicates on most channels. - `--sub-format ttml` is what keeps the output clean. YouTube serves auto-captions in several formats; the default `vtt`/`srt` ones are a rolling two-line window where each cue repeats the previous line above the new one (interleaved with 10 ms "hold" cues), so every phrase lands in the file about twice. `ttml` has one entry per phrase with no repetition, and `--convert-subs srt` turns it into a plain SRT. Requesting the right format beats deduplicating afterward — a transcript is allowed to contain genuinely repeated lines. - The ttml → srt conversion wraps each line in `` styling tags; both output paths strip them. - `scripts/srt_to_md.awk` does the `.md` formatting: it drops index and timestamp lines and re-tags each caption line with its start time as `[HH:MM:SS]`. ## Notes - `yt-dlp` exits non-zero when `--break-match-filters` or `--max-downloads` trips; the script treats those as normal completion. - If a video has no English auto-captions it's silently skipped. - The script takes a snapshot of the directory before fetching, and only files that appear afterward are converted or cleaned up. Anything already present is counted, reported, and left untouched, whatever it's named — so running twice in the same directory can't mangle or delete the first run's output. - This skill is YouTube-only by design. `--sub-format ttml` relies on YouTube offering that format, which it does for every video and language; other sites may not, in which case the fetch would find no matching subtitle format.