@thenavidm/youtube-mcp-cli 2.0.0

package/dist/youtube/api.js

@@ -0,0 +1,176 @@
+/**
+ * YouTube Data + Analytics API client.
+ *
+ * Two credential paths, and which one you have decides which tools work:
+ *
+ *   API key:  anyone's public data. Search, channels, public video stats.
+ *               No consent screen, no user. Cheapest to set up.
+ *   OAuth:    your own channels. Uploads, playlists, comments as the owner,
+ *               and Analytics, which has no API-key path at all.
+ *
+ * Multi-account is the default rather than a feature. A creator with several
+ * channels has to be able to say which one an action runs against, so every
+ * account-scoped tool takes `account` and the server refuses to guess when
+ * more than one is connected.
+ */
+const DATA_BASE = "https://www.googleapis.com/youtube/v3";
+const ANALYTICS_BASE = "https://youtubeanalytics.googleapis.com/v2";
+const TOKEN_URL = "https://oauth2.googleapis.com/token";
+export class YouTubeApiError extends Error {
+    status;
+    reason;
+    constructor(message, status, reason) {
+        super(message);
+        this.status = status;
+        this.reason = reason;
+        this.name = "YouTubeApiError";
+    }
+    /** The shape the CLI prints on stderr, so a script parses one thing. */
+    toJSON() {
+        return { error: this.message, status: this.status, ...(this.reason ? { reason: this.reason } : {}) };
+    }
+}
+/**
+ * Turn Google's error envelope into something a person can act on.
+ *
+ * The raw messages are unhelpfully generic: "The request cannot be completed
+ * because you have exceeded your quota" does not tell you that quota resets at
+ * midnight Pacific, and `quotaExceeded` vs `rateLimitExceeded` need different
+ * responses from the caller.
+ */
+function explain(status, reason, message) {
+    switch (reason) {
+        case "quotaExceeded":
+            return "Daily API quota is used up. It resets at midnight Pacific. Raise it in the Cloud console under IAM & Admin > Quotas, or wait.";
+        case "rateLimitExceeded":
+            return "Too many requests too quickly. Slow down and retry.";
+        case "forbidden":
+        case "insufficientPermissions":
+            return `Your token lacks the scope for this call. Reconnect the account and approve every permission. (${message})`;
+        case "authError":
+        case "unauthorized":
+            return "The access token is invalid or expired. Reconnect the account.";
+        case "videoNotFound":
+        case "channelNotFound":
+        case "playlistNotFound":
+            return `Not found. Check the id. (${message})`;
+        default:
+            return status === 403
+                ? `${message}. Usually a missing scope or a disabled API in the Cloud project.`
+                : message;
+    }
+}
+export class YouTubeClient {
+    creds;
+    /** Refreshed tokens live here for the process lifetime, keyed by account id. */
+    tokenCache = new Map();
+    constructor(creds) {
+        this.creds = creds;
+    }
+    /** An access token for the account, refreshing when it is within a minute of expiry. */
+    async accessToken(account) {
+        const cached = this.tokenCache.get(account.id);
+        if (cached && cached.expiresAt > Date.now() + 60_000)
+            return cached.token;
+        if (!account.refreshToken) {
+            if (!account.accessToken) {
+                throw new YouTubeApiError(`Account "${account.name}" has no credentials. Reconnect it.`, 401, "authError");
+            }
+            return account.accessToken;
+        }
+        const res = await fetch(TOKEN_URL, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                grant_type: "refresh_token",
+                refresh_token: account.refreshToken,
+                client_id: account.clientId,
+                client_secret: account.clientSecret,
+            }).toString(),
+        });
+        const body = (await res.json());
+        if (!res.ok || !body.access_token) {
+            // `unauthorized_client` here nearly always means the refresh token was
+            // issued by a different OAuth client than the one configured now, not
+            // that the user revoked access. Say so, because the two look identical
+            // from the outside and lead to opposite fixes.
+            const hint = body.error === "unauthorized_client"
+                ? " This usually means the token was issued by a different OAuth client than the one configured. Check YOUTUBE_CLIENT_ID matches the client that authorized this channel, or reconnect."
+                : "";
+            throw new YouTubeApiError(`Could not refresh "${account.name}": ${body.error ?? res.status}${body.error_description ? ` (${body.error_description})` : ""}.${hint}`, 401, "authError");
+        }
+        this.tokenCache.set(account.id, {
+            token: body.access_token,
+            expiresAt: Date.now() + (body.expires_in ?? 3600) * 1000,
+        });
+        return body.access_token;
+    }
+    async request(base, path, params, init = {}) {
+        const url = new URL(`${base}${path}`);
+        for (const [k, v] of Object.entries(params)) {
+            if (v === undefined || v === null || v === "")
+                continue;
+            url.searchParams.set(k, String(v));
+        }
+        const headers = {};
+        const account = this.creds.account;
+        if (account) {
+            headers.Authorization = `Bearer ${await this.accessToken(account)}`;
+        }
+        else if (init.requireAuth) {
+            // A plain Error, not a 401: nothing was rejected, nothing was set up. The
+            // CLI maps "no ... is configured" to exit 10, which is what a script needs
+            // to tell "run login first" apart from "your token expired".
+            throw new Error("No account is configured for this action. Run `youtube-cli login` once per channel, or set YOUTUBE_ACCOUNTS.");
+        }
+        else if (this.creds.apiKey) {
+            url.searchParams.set("key", this.creds.apiKey);
+        }
+        else {
+            throw new Error("No API key is configured. Run `youtube-cli login --api-key KEY` or set YOUTUBE_API_KEY for public data, or `youtube-cli login` for your own channels.");
+        }
+        if (init.body !== undefined)
+            headers["Content-Type"] = "application/json";
+        const res = await fetch(url, {
+            method: init.method ?? "GET",
+            headers,
+            body: init.body === undefined ? undefined : JSON.stringify(init.body),
+        });
+        const text = await res.text();
+        const data = text ? JSON.parse(text) : {};
+        if (!res.ok) {
+            const err = data.error;
+            const reason = err?.errors?.[0]?.reason;
+            throw new YouTubeApiError(explain(res.status, reason, err?.message ?? text), res.status, reason);
+        }
+        return data;
+    }
+    get(path, params = {}, requireAuth = false) {
+        return this.request(DATA_BASE, path, params, { requireAuth });
+    }
+    post(path, params, body) {
+        return this.request(DATA_BASE, path, params, { method: "POST", body, requireAuth: true });
+    }
+    put(path, params, body) {
+        return this.request(DATA_BASE, path, params, { method: "PUT", body, requireAuth: true });
+    }
+    delete(path, params) {
+        return this.request(DATA_BASE, path, params, { method: "DELETE", requireAuth: true });
+    }
+    analytics(params) {
+        return this.request(ANALYTICS_BASE, "/reports", params, { requireAuth: true });
+    }
+}
+/** ISO 8601 durations (`PT4M13S`) are unreadable in output. Seconds are not. */
+export function durationToSeconds(iso) {
+    if (!iso)
+        return null;
+    const m = /^P(?:(\d+)D)?T?(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?$/.exec(iso);
+    if (!m)
+        return null;
+    return (Number(m[1] ?? 0) * 86400 +
+        Number(m[2] ?? 0) * 3600 +
+        Number(m[3] ?? 0) * 60 +
+        Number(m[4] ?? 0));
+}
+//# sourceMappingURL=api.js.map

package/dist/youtube/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/youtube/api.ts"],"names":[],"mappings":"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"}

package/dist/youtube/transcripts.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Transcripts.
+ *
+ * These need no API key, no OAuth, and no quota. YouTube serves caption tracks
+ * to the watch page itself, and that is what we read. It is the only part of
+ * this server that works the moment it is installed.
+ *
+ * The trade is that it is not a supported API. YouTube changes the watch page
+ * shape occasionally and this has to follow. Everything here is written to fail
+ * as "no transcript" rather than to throw, because a missing transcript is a
+ * normal outcome: plenty of videos genuinely have no captions.
+ *
+ * Do not confuse this with the Captions API (`captions.download`), which the
+ * account tools use. That one needs OAuth AND channel ownership, so it can only
+ * ever read your own videos. This reads anyone's.
+ */
+export type TranscriptSegment = {
+    /** Seconds from the start of the video. */
+    start: number;
+    /** Segment duration in seconds. */
+    duration: number;
+    text: string;
+};
+export type TranscriptTrack = {
+    languageCode: string;
+    languageName: string;
+    /** True when YouTube generated these captions rather than a human writing them. */
+    autoGenerated: boolean;
+    url: string;
+};
+export declare class TranscriptError extends Error {
+    readonly code: "no_video" | "no_captions" | "language_missing" | "blocked" | "network";
+    constructor(message: string, code: "no_video" | "no_captions" | "language_missing" | "blocked" | "network");
+}
+/**
+ * Accepts anything a user is likely to paste: a bare id, a watch URL, a
+ * youtu.be link, a Shorts URL, an embed, or a live URL.
+ */
+export declare function parseVideoId(input: string): string | null;
+/** Every caption track YouTube will serve for this video. */
+export declare function listTracks(videoId: string, timeoutMs?: number): Promise<TranscriptTrack[]>;
+export type FetchTranscriptOptions = {
+    language?: string;
+    timeoutMs?: number;
+};
+export type Transcript = {
+    videoId: string;
+    language: string;
+    autoGenerated: boolean;
+    segments: TranscriptSegment[];
+};
+/** Fetch one video's transcript. Throws TranscriptError with a `code` you can branch on. */
+export declare function fetchTranscript(videoIdOrUrl: string, opts?: FetchTranscriptOptions): Promise<Transcript>;
+/** `1h02m03s` style stamps read better than raw seconds in a transcript dump. */
+export declare function formatTimestamp(seconds: number): string;
+/** Collapse segments into readable prose. Auto-captions arrive as ~2 second fragments. */
+export declare function toPlainText(segments: TranscriptSegment[]): string;
+/** Timestamped lines, grouped so the output is scannable rather than one line per fragment. */
+export declare function toTimestampedText(segments: TranscriptSegment[], groupSeconds?: number): string;
+/** Find a phrase in a transcript and return the timestamps where it occurs. */
+export declare function searchSegments(segments: TranscriptSegment[], query: string, contextSegments?: number): {
+    timestamp: string;
+    start: number;
+    text: string;
+}[];

package/dist/youtube/transcripts.js

@@ -0,0 +1,321 @@
+/**
+ * Transcripts.
+ *
+ * These need no API key, no OAuth, and no quota. YouTube serves caption tracks
+ * to the watch page itself, and that is what we read. It is the only part of
+ * this server that works the moment it is installed.
+ *
+ * The trade is that it is not a supported API. YouTube changes the watch page
+ * shape occasionally and this has to follow. Everything here is written to fail
+ * as "no transcript" rather than to throw, because a missing transcript is a
+ * normal outcome: plenty of videos genuinely have no captions.
+ *
+ * Do not confuse this with the Captions API (`captions.download`), which the
+ * account tools use. That one needs OAuth AND channel ownership, so it can only
+ * ever read your own videos. This reads anyone's.
+ */
+import { fetchCaptions, YtDlpMissingError } from "./ytdlp.js";
+const WATCH_URL = "https://www.youtube.com/watch";
+// Without a browser-ish UA, YouTube serves a consent interstitial with no
+// player response in it, and every video looks like it has no captions.
+const HEADERS = {
+    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+    "Accept-Language": "en-US,en;q=0.9",
+};
+export class TranscriptError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "TranscriptError";
+    }
+}
+/**
+ * Accepts anything a user is likely to paste: a bare id, a watch URL, a
+ * youtu.be link, a Shorts URL, an embed, or a live URL.
+ */
+export function parseVideoId(input) {
+    const raw = (input || "").trim();
+    if (!raw)
+        return null;
+    // A bare id. YouTube ids are 11 chars of [A-Za-z0-9_-].
+    if (/^[\w-]{11}$/.test(raw))
+        return raw;
+    let url;
+    try {
+        url = new URL(raw.startsWith("http") ? raw : `https://${raw}`);
+    }
+    catch {
+        return null;
+    }
+    if (url.hostname.endsWith("youtu.be")) {
+        const id = url.pathname.slice(1).split("/")[0];
+        return id && /^[\w-]{11}$/.test(id) ? id : null;
+    }
+    const v = url.searchParams.get("v");
+    if (v && /^[\w-]{11}$/.test(v))
+        return v;
+    const m = url.pathname.match(/\/(shorts|embed|live|v)\/([\w-]{11})/);
+    return m?.[2] ?? null;
+}
+/** Decode the XML entities YouTube puts in caption text, including the double-escaped ones. */
+function decodeEntities(text) {
+    return text
+        .replace(/&#(\d+);/g, (_, code) => String.fromCharCode(Number(code)))
+        .replace(/&#(\d+);/g, (_, code) => String.fromCharCode(Number(code)))
+        .replace(/"/g, '"')
+        .replace(/"/g, '"')
+        .replace(/'/g, "'")
+        .replace(/'/g, "'")
+        .replace(/&amp;lt;/g, "<")
+        .replace(/&lt;/g, "<")
+        .replace(/&amp;gt;/g, ">")
+        .replace(/&gt;/g, ">")
+        .replace(/&amp;nbsp;/g, " ")
+        .replace(/&nbsp;/g, " ")
+        .replace(/&amp;/g, "&")
+        .trim();
+}
+async function fetchText(url, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, { headers: HEADERS, signal: controller.signal });
+        if (res.status === 429) {
+            throw new TranscriptError("YouTube is rate limiting transcript requests from this IP. Wait a few minutes, or set YOUTUBE_TRANSCRIPT_PROXY.", "blocked");
+        }
+        if (!res.ok) {
+            throw new TranscriptError(`YouTube returned ${res.status} for ${url}`, "network");
+        }
+        return await res.text();
+    }
+    catch (err) {
+        if (err instanceof TranscriptError)
+            throw err;
+        if (err instanceof Error && err.name === "AbortError") {
+            throw new TranscriptError(`Timed out after ${timeoutMs}ms fetching the transcript.`, "network");
+        }
+        throw new TranscriptError(err instanceof Error ? err.message : String(err), "network");
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Pull the caption track list out of the watch page.
+ *
+ * The player response is embedded in the HTML as a JSON blob. We locate it by
+ * its key and balance braces rather than regex the whole object, because the
+ * blob contains nested braces inside strings and a greedy regex reliably
+ * grabs either too little or the rest of the document.
+ */
+function extractPlayerResponse(html) {
+    const key = "ytInitialPlayerResponse";
+    const at = html.indexOf(key);
+    if (at === -1)
+        return null;
+    const braceStart = html.indexOf("{", at);
+    if (braceStart === -1)
+        return null;
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = braceStart; i < html.length; i++) {
+        const ch = html[i];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (ch === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (ch === '"') {
+            inString = !inString;
+            continue;
+        }
+        if (inString)
+            continue;
+        if (ch === "{")
+            depth++;
+        else if (ch === "}") {
+            depth--;
+            if (depth === 0) {
+                try {
+                    return JSON.parse(html.slice(braceStart, i + 1));
+                }
+                catch {
+                    return null;
+                }
+            }
+        }
+    }
+    return null;
+}
+/** Every caption track YouTube will serve for this video. */
+export async function listTracks(videoId, timeoutMs = 15000) {
+    const html = await fetchText(`${WATCH_URL}?v=${videoId}&hl=en`, timeoutMs);
+    const player = extractPlayerResponse(html);
+    if (!player) {
+        throw new TranscriptError("Could not read the video page. The video may be private, deleted, or age-restricted.", "no_video");
+    }
+    const status = player.playabilityStatus?.status;
+    if (status && status !== "OK") {
+        throw new TranscriptError(`YouTube will not play this video (${status}). Private, deleted, or region-locked videos have no readable transcript.`, "no_video");
+    }
+    const captions = player.captions;
+    const tracks = captions?.playerCaptionsTracklistRenderer?.captionTracks ?? [];
+    return tracks
+        .map((t) => ({
+        languageCode: String(t.languageCode ?? ""),
+        languageName: String(t.name?.simpleText ??
+            t.name?.runs?.[0]?.text ??
+            t.languageCode ??
+            ""),
+        // `asr` = automatic speech recognition, i.e. YouTube's own auto-captions.
+        autoGenerated: String(t.kind ?? "") === "asr",
+        url: String(t.baseUrl ?? ""),
+    }))
+        .filter((t) => t.url);
+}
+/**
+ * Pick a track for the requested language.
+ *
+ * Preference order, and the reason for it: an exact match first; then the same
+ * language ignoring region, so `en` finds `en-GB`; then a human-written track
+ * in any language, which beats auto-captions on accuracy; then whatever exists.
+ */
+function pickTrack(tracks, language) {
+    if (tracks.length === 0)
+        return null;
+    if (!language) {
+        return tracks.find((t) => !t.autoGenerated) ?? tracks[0] ?? null;
+    }
+    const want = language.toLowerCase();
+    return (tracks.find((t) => t.languageCode.toLowerCase() === want) ??
+        tracks.find((t) => t.languageCode.toLowerCase().split("-")[0] === want.split("-")[0]) ??
+        null);
+}
+function parseTimedText(xml) {
+    const out = [];
+    const re = /<text([^>]*)>([\s\S]*?)<\/text>/g;
+    let m;
+    while ((m = re.exec(xml)) !== null) {
+        const attrs = m[1] ?? "";
+        const body = m[2] ?? "";
+        const start = Number(/\bstart="([\d.]+)"/.exec(attrs)?.[1] ?? 0);
+        const duration = Number(/\bdur="([\d.]+)"/.exec(attrs)?.[1] ?? 0);
+        const text = decodeEntities(body.replace(/<[^>]+>/g, ""));
+        if (text)
+            out.push({ start, duration, text });
+    }
+    return out;
+}
+/** Fetch one video's transcript. Throws TranscriptError with a `code` you can branch on. */
+export async function fetchTranscript(videoIdOrUrl, opts = {}) {
+    const videoId = parseVideoId(videoIdOrUrl);
+    if (!videoId) {
+        throw new TranscriptError(`Could not read a video id out of "${videoIdOrUrl}". Pass a video id or a YouTube URL.`, "no_video");
+    }
+    const timeoutMs = opts.timeoutMs ?? 15000;
+    const tracks = await listTracks(videoId, timeoutMs);
+    if (tracks.length === 0) {
+        throw new TranscriptError("This video has no captions at all, so there is no transcript to read.", "no_captions");
+    }
+    const track = pickTrack(tracks, opts.language);
+    if (!track) {
+        const available = tracks.map((t) => t.languageCode).join(", ");
+        throw new TranscriptError(`No "${opts.language}" captions on this video. Available: ${available}.`, "language_missing");
+    }
+    // The track list above is real, but YouTube answers the track URL itself with
+    // an empty body unless the request carries a proof-of-origin token. yt-dlp
+    // mints one, so the body comes from there while the list comes from the page.
+    let segments;
+    let language = track.languageCode;
+    let autoGenerated = track.autoGenerated;
+    try {
+        const viaYtDlp = await fetchCaptions(videoId, track.languageCode, Math.max(timeoutMs, 90000));
+        segments = viaYtDlp.segments;
+        language = viaYtDlp.language;
+        autoGenerated = viaYtDlp.autoGenerated;
+    }
+    catch (err) {
+        if (err instanceof YtDlpMissingError) {
+            throw new TranscriptError(err.message, "blocked");
+        }
+        // Direct read as a last resort. It returns nothing today, but costs one
+        // request and starts working again the moment YouTube relaxes this.
+        const xml = await fetchText(track.url, timeoutMs);
+        segments = parseTimedText(xml);
+        if (segments.length === 0) {
+            throw new TranscriptError(err instanceof Error ? err.message : "Could not download the caption track.", "blocked");
+        }
+    }
+    if (segments.length === 0) {
+        throw new TranscriptError("The caption track was empty.", "no_captions");
+    }
+    return { videoId, language, autoGenerated, segments };
+}
+/** `1h02m03s` style stamps read better than raw seconds in a transcript dump. */
+export function formatTimestamp(seconds) {
+    const total = Math.floor(seconds);
+    const h = Math.floor(total / 3600);
+    const m = Math.floor((total % 3600) / 60);
+    const s = total % 60;
+    const pad = (n) => String(n).padStart(2, "0");
+    return h > 0 ? `${h}:${pad(m)}:${pad(s)}` : `${m}:${pad(s)}`;
+}
+/** Collapse segments into readable prose. Auto-captions arrive as ~2 second fragments. */
+export function toPlainText(segments) {
+    return segments
+        .map((s) => s.text)
+        .join(" ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/** Timestamped lines, grouped so the output is scannable rather than one line per fragment. */
+export function toTimestampedText(segments, groupSeconds = 30) {
+    const lines = [];
+    let bucketStart = null;
+    let buffer = [];
+    const flush = () => {
+        if (bucketStart !== null && buffer.length) {
+            lines.push(`[${formatTimestamp(bucketStart)}] ${buffer.join(" ").replace(/\s+/g, " ").trim()}`);
+        }
+        buffer = [];
+    };
+    for (const seg of segments) {
+        if (bucketStart === null)
+            bucketStart = seg.start;
+        if (seg.start - bucketStart >= groupSeconds) {
+            flush();
+            bucketStart = seg.start;
+        }
+        buffer.push(seg.text);
+    }
+    flush();
+    return lines.join("\n");
+}
+/** Find a phrase in a transcript and return the timestamps where it occurs. */
+export function searchSegments(segments, query, contextSegments = 1) {
+    const needle = query.toLowerCase().trim();
+    if (!needle)
+        return [];
+    const hits = [];
+    for (let i = 0; i < segments.length; i++) {
+        const seg = segments[i];
+        if (!seg || !seg.text.toLowerCase().includes(needle))
+            continue;
+        const from = Math.max(0, i - contextSegments);
+        const to = Math.min(segments.length, i + contextSegments + 1);
+        const text = segments
+            .slice(from, to)
+            .map((s) => s.text)
+            .join(" ")
+            .replace(/\s+/g, " ")
+            .trim();
+        hits.push({ timestamp: formatTimestamp(seg.start), start: seg.start, text });
+    }
+    return hits;
+}
+//# sourceMappingURL=transcripts.js.map

package/dist/youtube/transcripts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcripts.js","sourceRoot":"","sources":["../../src/youtube/transcripts.ts"],"names":[],"mappings":"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"}

package/dist/youtube/ytdlp.d.ts

@@ -0,0 +1,35 @@
+/**
+ * yt-dlp transport for caption tracks.
+ *
+ * As of 2026 YouTube answers a bare `timedtext` URL with 200 and an empty body
+ * unless the request carries a proof-of-origin token tied to a real player
+ * session. Scraping the watch page still lists which tracks exist, but it can
+ * no longer read their contents, so the track list and the track body now come
+ * from different places.
+ *
+ * yt-dlp already solves the hard half and is maintained against YouTube's
+ * changes far faster than this repo could be, so we shell out to it rather than
+ * reimplement token minting. It is an optional dependency: without it you can
+ * still list languages, and every other tool in this server is unaffected.
+ */
+import type { TranscriptSegment } from "./transcripts.js";
+export declare class YtDlpMissingError extends Error {
+    constructor();
+}
+/** True when yt-dlp can actually be launched. Used by `doctor` and by tool errors. */
+export declare function isAvailable(): Promise<boolean>;
+export type YtDlpTranscript = {
+    segments: TranscriptSegment[];
+    /** The language actually written out, which may be a regional variant of what was asked for. */
+    language: string;
+    autoGenerated: boolean;
+};
+/**
+ * Download one caption track.
+ *
+ * `--sub-langs` accepts a glob, so `en.*` picks up `en`, `en-GB` and the
+ * auto-generated `en-orig` in one pass. We take whichever file lands and report
+ * the language from its name rather than assuming we got the exact code asked
+ * for.
+ */
+export declare function fetchCaptions(videoId: string, language?: string, timeoutMs?: number): Promise<YtDlpTranscript>;