YouTube Transcript

Downloads transcripts (subtitles/captions) from YouTube videos. Works with both manually created and auto-generated transcripts. No API key or browser required — uses YouTube's InnerTube API directly and automatically falls back to

yt-dlp

Fetches video metadata and cover image on first run, caches raw data for fast re-formatting.

Script Directory

Scripts in

scripts/

{baseDir}

${BUN_X}

bun

bun

npx

npx -y bun

{baseDir}

${BUN_X}

scripts/main.ts

Usage

# Default: markdown with timestamps (English)
${BUN_X} {baseDir}/scripts/main.ts <youtube-url-or-id>

# Specify languages (priority order)
${BUN_X} {baseDir}/scripts/main.ts <url> --languages zh,en,ja

# Without timestamps
${BUN_X} {baseDir}/scripts/main.ts <url> --no-timestamps

# With chapter segmentation
${BUN_X} {baseDir}/scripts/main.ts <url> --chapters

# With speaker identification (requires AI post-processing)
${BUN_X} {baseDir}/scripts/main.ts <url> --speakers

# SRT subtitle file
${BUN_X} {baseDir}/scripts/main.ts <url> --format srt

# Translate transcript
${BUN_X} {baseDir}/scripts/main.ts <url> --translate zh-Hans

# List available transcripts
${BUN_X} {baseDir}/scripts/main.ts <url> --list

# Force re-fetch (ignore cache)
${BUN_X} {baseDir}/scripts/main.ts <url> --refresh

Options

<url-or-id>

--languages <codes>

en

--format <fmt>

text

srt

text

--translate <code>

--list

--timestamps

[HH:MM:SS → HH:MM:SS]

--no-timestamps

--chapters

--speakers

--exclude-generated

--exclude-manually-created

--refresh

-o, --output <path>

--output-dir <dir>

youtube-transcript

Optional Environment Variables

YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER

yt-dlp --cookies-from-browser

chrome

safari

firefox

chrome:Profile 1

Input Formats

Accepts any of these as video input:

• Full URL:

  https://www.youtube.com/watch?v=dQw4w9WgXcQ

• Short URL:

  https://youtu.be/dQw4w9WgXcQ

• Embed URL:

  https://www.youtube.com/embed/dQw4w9WgXcQ

• Shorts URL:

  https://www.youtube.com/shorts/dQw4w9WgXcQ

• Video ID:

  dQw4w9WgXcQ

Output Formats

text

.md

description

srt

.srt

Output Directory

youtube-transcript/
├── .index.json                          # Video ID → directory path mapping (for cache lookup)
└── {channel-slug}/{title-full-slug}/
    ├── meta.json                        # Video metadata (title, channel, description, duration, chapters, etc.)
    ├── transcript-raw.json              # Raw transcript snippets from YouTube API (cached)
    ├── transcript-sentences.json        # Sentence-segmented transcript (split by punctuation, merged across snippets)
    ├── imgs/
    │   └── cover.jpg                    # Video thumbnail
    ├── transcript.md                    # Markdown transcript (generated from sentences)
    └── transcript.srt                   # SRT subtitle (generated from raw snippets, if --format srt)

• {channel-slug}

  : Channel name in kebab-case

• {title-full-slug}

  : Full video title in kebab-case

The

--list

Caching

On first fetch, the script saves:

• meta.json

  — video metadata, chapters, cover image path, language info

• transcript-raw.json

  — raw transcript snippets from YouTube API (

  { text, start, duration }[]

  )

• transcript-sentences.json

  — sentence-segmented transcript (

  { text, start: "HH:mm:ss", end: "HH:mm:ss" }[]

  ), split by sentence-ending punctuation (

  .?!…。？！

  etc.), timestamps proportionally allocated by character length, CJK-aware text merging

• imgs/cover.jpg

  — video thumbnail

Subsequent runs for the same video use cached data (no network calls). Use

--refresh

When YouTube returns anti-bot / blocked responses on the direct InnerTube path, the script retries with alternate client identities and then falls back to

yt-dlp

yt-dlp

yt-dlp

SRT output (

--format srt

transcript-raw.json

transcript-sentences.json

Workflow

When user provides a YouTube URL and wants the transcript:

1. Run with

   --list

   first if the user hasn't specified a language, to show available options
2. Always single-quote the URL when running the script — zsh treats

   ?

   as a glob wildcard, so an unquoted YouTube URL causes "no matches found": use

   'https://www.youtube.com/watch?v=ID'

3. Default: run with

   --chapters --speakers

   for the richest output (chapters + speaker identification)
4. The script auto-saves cached data + output file and prints the file path
5. For

   --speakers

   mode: after the script saves the raw file, follow the speaker identification workflow below to post-process with speaker labels

When user only wants a cover image or metadata, running the script with any option will also cache

meta.json

imgs/cover.jpg

When re-formatting the same video (e.g., first text then SRT), the cached data is reused — no re-fetch needed.

Chapter & Speaker Workflow

Chapters (

--chapters

)

The script parses chapter timestamps from the video description (e.g.,

0:00 Introduction

.md

If no chapter timestamps exist in the description, the transcript is output as grouped paragraphs without chapter headings.

Speaker Identification (

--speakers

)

Speaker identification requires AI processing. The script outputs a raw

.md

• YAML frontmatter with video metadata (title, channel, date, cover, description, language)
• Video description (for speaker name extraction)
• Chapter list from description (if available)
• Raw transcript in SRT format (pre-computed start/end timestamps, token-efficient)

After the script saves the raw file, spawn a sub-agent (use a cheaper model like Sonnet for cost efficiency) to process speaker identification:

1. Read the saved

   .md

   file
2. Read the prompt template at

   {baseDir}/prompts/speaker-transcript.md

3. Process the raw transcript following the prompt:
   • Identify speakers using video metadata (title → guest, channel → host, description → names)
   • Detect speaker turns from conversation flow, question-answer patterns, and contextual cues
   • Segment into chapters (use description chapters if available, else create from topic shifts)
   • Format with

     **Speaker Name:**

     labels, paragraph grouping (2-4 sentences), and

     [HH:MM:SS → HH:MM:SS]

     timestamps
4. Overwrite the

   .md

   file with the processed transcript (keep the YAML frontmatter)

When

--speakers

--chapters

Error Cases

yt-dlp

YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER=safari