YouTube#

Captions and blocks#

Captions are the cheapest and most accurate transcript: no audio download, no speech-to-text. youtube-captions reads them keylessly through the innertube player API and the timedtext endpoint.

How a track is chosen#

With a language (--lang de, language: 'de'):

1. a creator track in that language,
2. an auto-generated (asr) track in that language, unless allowAuto is false,
3. YouTube's machine translation (tlang) of the best translatable track, unless allowTranslated is false. The transcript is marked translated: true. When the player lists translation targets, only a listed language is used, with YouTube's own code for it (pt-BR becomes pt).

Without a language: a creator track in the spoken language (an asr track's language reveals it), then any creator track (the video's default first), then the asr track.

Languages match exactly first, then by primary subtag (en matches en-GB). Tracks download as srv3, then srv1. Parsers also handle json3 and WebVTT, and the format is detected from the body, never from the request, because the endpoint does not always honour fmt. The raw track text is kept as is; cleaning and translation by an LLM are separate layers.

Player clients and fallback#

Clients are tried in order. Defaults, verified live from a GCP VM on 2026-11-14:

Checked and dropped the same day: TVHTML5_SIMPLY_EMBEDDED_PLAYER ("YouTube is no longer supported in this application or device"), WEB and MWEB ("The page needs to be reloaded", even with visitorData; they now need a PO token), ANDROID_VR and TVHTML5 (the bot check from the VM, while ANDROID and IOS passed). The recorded responses are in providers/youtube/test/fixtures/.

The next client gets a turn when the current one:

• is refused for its own reasons (LOGIN_REQUIRED without a video reason, UNPLAYABLE "page needs to be reloaded", "no longer supported"),
• gets "Sign in to confirm you're not a bot" (often specific to one client),
• returns no captions,
• fails with an HTTP error other than a block (a retired version gets HTTP 400 "Precondition check failed").

A verdict about the video itself (removed, private, members-only, upcoming) stops the search. Each client tried is recorded as an attempt (youtube/android, youtube/ios) on the player response and on the error. Player responses are cached per video for 60 seconds, so metadata and captions share one call.

Settings: YOUTUBE_CLIENTS=ios,android changes the order or drops a client. YOUTUBE_ANDROID_VERSION and YOUTUBE_IOS_VERSION raise a version without a release. Other modules (metadata, browse, comments) call innertubeRequest(endpoint, body, client, ctx) with their own client spec and share the transport below.

Errors#

What a block looks like#

YouTube flags many cloud and datacenter IPs. Two shapes were seen from a GCP VM on 2026-11-14:

• the player API answers LOGIN_REQUIRED "Sign in to confirm you're not a bot" (for some clients; vid2context moves on to the next one, and reports blocked only when every client gets it),
• timedtext answers HTTP 429 with an HTML page: "Sorry... your computer or network may be sending automated queries". On that day the player API kept answering while every caption request got this page.

Retries never help with a block and tend to extend it. So a blocked result is not retried, and it opens a circuit breaker: for YOUTUBE_BLOCK_COOLDOWN_SEC (default 600, 0 turns it off) every YouTube call in the process fails fast with the same error and hint, and an attempt with reason circuit-open. Rate limits and 5xx get exponential backoff with full jitter instead (at most 3 retries, Retry-After honoured).

Fixes for a block, best first#

1. Run vid2context on your own machine. A home connection is rarely blocked.
2. Keep the server where it is but send its YouTube traffic through your home network: see docs/guides/cloudflare-tunnel.md.
3. Route through a proxy. vid2context has no proxy code of its own: Node 24 honours HTTPS_PROXY when started with NODE_USE_ENV_PROXY=1, for example NODE_USE_ENV_PROXY=1 HTTPS_PROXY=http://host:port npx vid2context <url>.
4. Set YOUTUBE_COOKIE to the Cookie header of a signed-in youtube.com tab. With a SAPISID cookie, the matching SAPISIDHASH Authorization header is derived. Warning: the cookie ties every request to that Google account, and heavy use can get the account flagged, so use a spare account. The provider runs on Node, Workers and in the browser and never reads files, so reading a Netscape cookies file (YOUTUBE_COOKIES_FILE) into YOUTUBE_COOKIE is left to the Node surfaces (CLI, server); until they do, paste the header value itself. YouTube honours account cookies mainly for its web clients, so with the default app clients the gain is uncertain. Not verified live (no account was used).
5. Install the yt-dlp provider, which has its own client rotation and cookie support.
6. Wait. Blocks usually lift after some time without requests.

PO tokens#

When YouTube wants a proof-of-origin token for a client, caption tracks come back empty. YOUTUBE_PO_TOKEN is sent in the player request (serviceIntegrityDimensions.poToken) and on caption URLs (&pot=, with &c=<client>). YOUTUBE_VISITOR_DATA must be the visitorData the token was minted for; it goes into the client context and the x-goog-visitor-id header. Tokens are minted outside vid2context (for example with BgUtils) and expire. Neither was needed on 2026-11-14 with ANDROID or IOS. Cookie and token values are never logged.

Metadata and chapters#

youtube.getMetadata makes one player request (the same cached response the captions provider uses), one next request (the watch page's data, WEB client) and one HEAD request for the maxres thumbnail, the last two in parallel. No key. It succeeds whenever the player returns videoDetails, including age-restricted, members-only, live and upcoming videos: those states are reported in extra, and the transcript stage raises the errors. If the next request fails, the player fields are still returned and a warning is logged.

Fields and where they come from#

Not available without an extra request: the category and a separate upload date. They are only in the WEB player response's microformat, and the ANDROID and IOS player responses and next do not carry them, so they are left out rather than costing a second player call.

Chapter precedence#

The first source that yields a list wins:

1. Creator chapters parsed from the description.
2. YouTube's chapter markers in next (player bar markers, key DESCRIPTION_CHAPTERS): YouTube's own parse of the description.
3. Auto-generated chapters, shown as "key moments" (key AUTO_CHAPTERS).

Every chapter gets endSec: the next chapter's start, and the duration for the last one (no endSec for the last chapter when the duration is unknown).

Description rules#

A description yields chapters when it has a line stamped 0:00 (or 00:00, 00:00:00), at least three timestamped lines in all, and ascending times. Lines before the 0:00 line are ignored, and the list ends at the first time that does not ascend or that falls past the end of the video, so stray timestamps elsewhere do not leak in.

• Timestamps: h:mm:ss, hh:mm:ss, mm:ss, m:ss, optionally in brackets or parentheses, optionally as a range (0:00 - 0:30: Intro gives "Intro" at 0).
• The title may come before or after the timestamp, with or without a separator (-, |, :, dashes, bullets). Bullets and list numbers before a leading timestamp are dropped; a list number before a trailing-timestamp title stays, as on YouTube.
• A timestamp in the middle of a line is never a chapter ("at 3:45 he says"), nor a trailing one after words such as "at", "to", "from", "around" ("skip to 12:30").
• Titles are trimmed, inner spaces collapsed, emoji at either end and quotes that wrap the whole title removed (YouTube does the same).
• YouTube's help page asks for chapters of at least 10 seconds, but YouTube accepts shorter ones (the 5-second "Intro" of jNQXAC9IVRw), so this rule is not enforced.

Checked against 220 real videos on 2026-11-14: the parser matches YouTube's own chapter list for every description except six where the creator's list is valid but YouTube showed no description chapters (those keep the creator's chapters) and one that uses time ranges (YouTube keeps "0:30:" in the titles; this parser reads the range).

YOUTUBE_WEB_VERSION overrides the WEB client version used for next (default 2.20261112.10.00).

Comments#

Comments often hold what a video leaves out: owners' experiences, corrections from experts, and the creator's pinned clarifications. Ask for them with getVideoContext(registry, url, { comments: 50 }, ctx) (or comments: true for the default of 50). They come back in VideoContext.comments, a separate array that is never merged into the transcript. Comments are untrusted text written by the public: show them to a model as quoted material, not as instructions.

How they are fetched: keyless, through innertube next with the WEB client (no YouTube Data API key). The first call finds the comments section, then each continuation returns about 20 top-level threads. Paging stops as soon as the limit is reached, and ctx.signal is checked between pages.

Replies cost one request per thread, so they are fetched for at most 20 threads: every thread the creator replied in first, then the 5 most liked threads with replies. Within a thread a creator reply is always kept, even when the reply limit is 1; the rest are filled in YouTube's order. If a thread is marked as having a creator reply that is not on the first page of replies, up to 3 reply pages are read to find it.

Each comment maps to the core Comment type:

• id, author (the display name, usually the @handle), text (plain text; links are kept as full URLs, emoji as characters, timestamps like 6:38 as written).
• likes: YouTube shows rounded counts (1.2K), so likes above 1,000 are approximate.
• publishedAt: approximate. YouTube only says "2 years ago", so the date is computed from that text and the time of the request. Day-or-longer units give a date only (2024-11-14); months count as 30 days and years as 365.
• isCreator (the author is the video's channel) and isPinned: set only when true. The pinned comment is always first.
• replies: present only on expanded threads.

Not represented: the creator's heart on a comment (the core type has no field for it, and nothing is added to the text), whether a comment was edited, and author channel ids.

When there are no comments to give, the result is [] with an info log saying why: comments turned off (for example videos made for kids), members-only or age-restricted videos, and videos with no comments yet. A video that does not exist, was removed or is private is an error, using the same error codes as captions. Each request goes through the shared YouTube transport, so a blocked IP fails fast with the same blocked error and hint as captions.

YouTube sends comments in two shapes: the WEB client uses entity payloads (frameworkUpdates mutations keyed from a commentViewModel), and the mobile web client still uses the classic commentRenderer. Both were seen live on 2026-11-14 and both are parsed.

Playlists, channels and search#

listItems (and expandInput, the MCP tool list_items, the HTTP route GET /items) expands a playlist, a channel or a search into video refs. Each item is the same ref a single-video URL gives (youtube:<videoId>, watch URL), so cached transcripts are shared. Everything is keyless, through innertube browse, search and navigation/resolve_url with the WEB client; no YouTube Data API key is used. URL matching is synchronous and makes no request.

Input forms#

Channel nativeId is the UC... id when the URL carries it, otherwise @handle, c:name or user:name. The tab is recorded after a slash in the ref id and the URL, never in nativeId. Other channel subpages (/community, /about) match as the channel itself.

Hosts: only youtube.com, www., m., music.youtube.com, youtube-nocookie.com and youtu.be match, plus the ytsearch prefix, so these forms never shadow another provider.

Rejected with unsupported-input: mixes (list=RD..., personalized and endless), ytsearch: without a query, and a count outside 1 to 200.

A watch URL with both v= and list= stays a single video. To list the playlist, pass the /playlist?list= form.

Limits and order#

• limit stops paging as soon as it is reached; no further page is requested. Playlists and channels have no default limit, so an uncapped channel listing pages through every upload (about 100 per request).
• Search returns 20 results by default, ytsearch<N>: asks for N, and the maximum is 200. A smaller limit wins.
• ctx.signal is checked between pages.
• Pages follow continuation tokens until the list ends; a token seen twice ends the listing.

How channels are listed#

A handle, /c/ or /user/ URL is resolved to its UC... id with navigation/resolve_url, which also returns the tab's browse params. Then the upload playlists derived from the id are tried first, because one playlist request gives a stable newest-first order: UU... (all uploads) for a bare channel, UULF... (long-form videos) for /videos, UUSH... for /shorts, UULV... for /streams. If that playlist does not exist, the channel tab itself is listed. A channel without the requested tab (YouTube answers with the Home tab instead) lists nothing, with a log line.

What is skipped#

• Unavailable entries (private, deleted or otherwise unplayable videos). Playlists are requested with unavailable entries shown, so they can be counted, then skipped.
• Duplicates: a video already listed is not listed again, even across the playlists of a /playlists tab.
• Search shelves ("People also watched", shorts shelves) and ads; the search uses the type=video filter.
• On the /playlists tab, a private or deleted playlist is skipped with a warning; the rest are still listed.

Skipped counts go to one log line on stderr: youtube: skipped list entries with unavailable, duplicates and listed.

Errors#

Metadata for lists#

getMetadata on a list ref returns a VideoMetadata with chapters: [] and extra.kind set to playlist, channel or search. Playlists carry the title, description, owner channel, thumbnail and extra.itemCount (the count in the header). Channels carry the title, description, avatar, extra.handle and extra.itemCount. A search needs no request: its title is YouTube search: <query>.

YOUTUBE_WEB_VERSION (shared with comments) overrides the WEB client version if YouTube starts rejecting the pinned one.