Published on

How ytranscript works: reverse-engineering YouTube captions

How ytranscript works: reverse-engineering YouTube captions
Authors
On this page

In my previous post, I introduced ytranscript, a tool I built to fetch YouTube transcripts for my knowledge pipeline. This time, let's open it up and see how it actually works.

The short version: no third-party services, no API keys. Just YouTube's own internal API.

Important caveats

Before we dig in, some honest disclaimers.

This uses an undocumented API. YouTube's Innertube API is internal and can change without notice. I've seen YouTube break similar tools before by changing endpoints, requiring authentication, or adding bot detection. If ytranscript stops working, that's why.

Terms of service. Accessing undocumented APIs may violate YouTube's ToS. This tool is for personal use, research, and educational purposes. Use it responsibly.

Known limitations:

  • Age-restricted videos require authentication cookies (not supported)
  • Private/unlisted videos require authentication
  • Region-blocked content may fail based on your IP
  • Heavy usage can get your IP rate-limited (HTTP 429) or blocked
  • Auto-translation tracks are not currently supported

With that out of the way, let's look under the hood.

The Innertube API

YouTube's web player uses an internal API called Innertube to fetch video data. It's the same API that powers youtube.com. It just isn't publicly documented.

The key endpoint:

POST https://www.youtube.com/youtubei/v1/player

This returns video metadata, including the available caption tracks and their URLs.

The two-step process

Getting a transcript takes two API calls.

Step 1: get caption track URLs

curl -X POST 'https://www.youtube.com/youtubei/v1/player?prettyPrint=false' \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36' \
  -d '{
    "context": {
      "client": {
        "clientName": "WEB",
        "clientVersion": "2.20240101.00.00"
      }
    },
    "videoId": "dQw4w9WgXcQ"
  }'

The response includes a captions object:

{
  "captions": {
    "playerCaptionsTracklistRenderer": {
      "captionTracks": [
        {
          "baseUrl": "https://www.youtube.com/api/timedtext?...",
          "languageCode": "en",
          "kind": "asr",
          "name": { "simpleText": "English (auto-generated)" }
        }
      ]
    }
  }
}

The fields that matter:

  • baseUrl: the URL to fetch the actual caption content
  • languageCode: the language code (en, es, fr, etc.)
  • kind: "asr": marks auto-generated captions (manual captions don't have this field)

Step 2: fetch the caption track

Take the baseUrl from step 1 and append &fmt=json3 to get structured JSON. You need the User-Agent header here too:

curl -H 'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36' \
  "https://www.youtube.com/api/timedtext?...&fmt=json3"

Response:

{
  "events": [
    {
      "tStartMs": 0,
      "dDurationMs": 5000,
      "segs": [{ "utf8": "Hello " }, { "utf8": "world" }]
    },
    {
      "tStartMs": 5000,
      "dDurationMs": 3000,
      "segs": [{ "utf8": "Welcome to the video" }]
    }
  ]
}

Each event has:

  • tStartMs: start time in milliseconds
  • dDurationMs: duration in milliseconds
  • segs: an array of text segments (UTF-8 encoded)

One gotcha: some events don't have segs (they're timing markers or style events), so those get filtered out.

Diagram of the two-step Innertube API process querying video metadata followed by fetching timed text JSON.

The whole thing with jq

Here's a complete script that fetches a transcript, with error handling:

VIDEO_ID="dQw4w9WgXcQ"

# Get caption URL (returns empty if no captions)
CAPTION_URL=$(curl -s -X POST \
  'https://www.youtube.com/youtubei/v1/player?prettyPrint=false' \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Mozilla/5.0' \
  -d "{\"context\":{\"client\":{\"clientName\":\"WEB\",\"clientVersion\":\"2.20240101.00.00\"}},\"videoId\":\"$VIDEO_ID\"}" \
  | jq -r '.captions.playerCaptionsTracklistRenderer.captionTracks[0].baseUrl // empty')

if [ -n "$CAPTION_URL" ]; then
  curl -s -H 'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36' \
    "$CAPTION_URL&fmt=json3" \
    | jq -r '.events[] | select(.segs) | [.segs[].utf8] | join("")'
else
  echo "No captions available"
fi

Why it won't work in browsers

If you're thinking "I'll just call this from my frontend," you can't. YouTube's API doesn't send CORS headers:

Access-Control-Allow-Origin: (missing)

So the browser blocks the request before it completes.

A friendly browser window tries to hand over a request envelope, and a guard robot in a hard hat holds up a hand to stop it at the door.

Workarounds

1. Proxy through your backend

import express from 'express'
import { fetchTranscript } from '@nadimtuhin/ytranscript'

const app = express()

// Validate video ID format (11 chars, alphanumeric + dash/underscore)
const isValidVideoId = (id: string) => /^[a-zA-Z0-9_-]{11}$/.test(id)

app.get('/api/transcript/:videoId', async (req, res) => {
  const { videoId } = req.params

  if (!isValidVideoId(videoId)) {
    return res.status(400).json({ error: 'Invalid video ID' })
  }

  try {
    const transcript = await fetchTranscript(videoId)
    res.json(transcript)
  } catch (error) {
    const message = error instanceof Error ? error.message : 'Unknown error'
    // Map errors to appropriate status codes
    const status = message.includes('No captions') ? 404 : 500
    res.status(status).json({ error: message })
  }
})

app.listen(3000)

2. Serverless function. Deploy on Vercel, Netlify, or AWS Lambda.

3. Browser extension. Content scripts can make same-origin requests when injected into youtube.com.

4. Just use the CLI. For automation, keep it server-side:

ytranscript get VIDEO_ID --format json

The actual return type

The real fetchTranscript function returns a Transcript object:

interface Transcript {
  videoId: string
  text: string // Full transcript as single string
  segments: Array<{
    // Individual caption segments
    text: string
    start: number // Seconds (converted from milliseconds)
    duration: number // Seconds
  }>
  language: string // e.g., "en"
  isAutoGenerated: boolean
}

The full implementation in fetcher.ts adds language selection, timeout handling, and output formatting.

How it picks a language

ytranscript chooses a caption track like this:

  1. Check each preferred language in order
  2. For each language, prefer manual captions over auto-generated ones
  3. If nothing matches, fall back to the first available track
// Prefer Spanish, fall back to English
fetchTranscript('VIDEO_ID', { languages: ['es', 'en'] })

Language codes use prefix matching via startsWith(), so en matches en, en-US, en-GB, and so on.

Flowchart of ytranscript language selection prioritizing manual captions and falling back to auto-generated or default tracks.

Rate limiting

YouTube will rate-limit aggressive requests. ytranscript has built-in throttling for bulk operations:

ytranscript bulk \
  --file videos.txt \
  --concurrency 4 \
  --pause-after 10 \
  --pause-ms 5000

This fetches 4 videos in parallel and pauses for 5 seconds after every 10 requests.

If you get HTTP 429 errors, back off hard: wait 30-60 seconds, then use exponential backoff. Keep hammering and your IP can get blocked for hours or days.

Lessons from building it

A few quirks I ran into along the way:

  1. User-Agent is required. YouTube rejects requests without a browser-like User-Agent.
  2. Client version matters (for now). The version string doesn't need to be current, but YouTube could start enforcing it.
  3. JSON3 format. The fmt=json3 parameter returns structured JSON. Without it, you get XML.
  4. It will break eventually. This is an undocumented API. When YouTube changes it, the library needs updating.

Sometimes the best API is the one that was never meant to be public. Just don't be surprised when it disappears.