youtube-transcript-nodejs 0.1.0

package/dist/cjs/http/httpClient.js

@@ -0,0 +1,228 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClient = void 0;
+const constants_js_1 = require("../config/constants.js");
+const index_js_1 = require("../errors/index.js");
+const proxyUrl_js_1 = require("../util/proxyUrl.js");
+/**
+ * Thin HTTP client wrapper around global fetch.
+ *
+ * - Injects default User-Agent, Accept-Language, cookie headers
+ * - Honors a CookieJar (mutates it from `Set-Cookie` responses)
+ * - Supports proxy URLs via dynamic undici import (only loaded when needed)
+ * - Retries on 429
+ *
+ * Designed to be small and easily mockable for tests.
+ */
+class HttpClient {
+    userAgent;
+    acceptLanguage;
+    defaultTimeoutMs;
+    cookies;
+    defaultHeaders;
+    proxyUrl;
+    fetchImpl;
+    retriesOn429;
+    proxyDispatcher;
+    constructor(config = {}) {
+        this.userAgent = config.userAgent ?? constants_js_1.DEFAULT_USER_AGENT;
+        this.acceptLanguage = config.acceptLanguage ?? constants_js_1.DEFAULT_ACCEPT_LANGUAGE;
+        this.defaultTimeoutMs = config.timeoutMs ?? constants_js_1.DEFAULT_REQUEST_TIMEOUT_MS;
+        this.cookies = config.cookies;
+        this.defaultHeaders = { ...config.defaultHeaders };
+        this.proxyUrl = config.proxyUrl;
+        this.fetchImpl = config.fetchImpl ?? globalThis.fetch.bind(globalThis);
+        this.retriesOn429 = config.retriesOn429 ?? 3;
+        if (!this.fetchImpl) {
+            throw new Error('No fetch implementation available; pass fetchImpl or run on Node 18+');
+        }
+    }
+    /**
+     * Build full headers for a request, merging defaults + per-request + cookies.
+     */
+    buildHeaders(url, perRequest) {
+        const headers = new Headers();
+        headers.set('User-Agent', this.userAgent);
+        headers.set('Accept-Language', this.acceptLanguage);
+        for (const [k, v] of Object.entries(this.defaultHeaders)) {
+            headers.set(k, v);
+        }
+        if (perRequest) {
+            for (const [k, v] of Object.entries(perRequest)) {
+                headers.set(k, v);
+            }
+        }
+        if (this.cookies) {
+            const cookieHeader = this.cookies.headerForUrl(url);
+            if (cookieHeader)
+                headers.set('Cookie', cookieHeader);
+        }
+        return headers;
+    }
+    /**
+     * GET request.
+     */
+    async get(url, opts = {}) {
+        return this.request(url, { ...opts, method: 'GET' });
+    }
+    /**
+     * POST request with a JSON body.
+     */
+    async postJson(url, body, opts = {}) {
+        const headers = { ...(opts.headers ?? {}), 'Content-Type': 'application/json' };
+        return this.request(url, {
+            ...opts,
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+        });
+    }
+    /**
+     * Perform an HTTP request with retries on 429.
+     */
+    async request(url, opts = {}) {
+        const method = opts.method ?? 'GET';
+        const timeoutMs = opts.timeoutMs ?? this.defaultTimeoutMs;
+        const headers = this.buildHeaders(url, opts.headers);
+        const dispatcher = await this.maybeProxyDispatcher();
+        let lastErr;
+        const attempts = Math.max(1, this.retriesOn429);
+        for (let attempt = 1; attempt <= attempts; attempt++) {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+            const onUserAbort = () => controller.abort();
+            opts.signal?.addEventListener('abort', onUserAbort, { once: true });
+            try {
+                const fetchOpts = {
+                    method,
+                    headers,
+                    signal: controller.signal,
+                };
+                if (opts.body !== undefined)
+                    fetchOpts.body = opts.body;
+                if (dispatcher)
+                    fetchOpts.dispatcher = dispatcher;
+                const rawResponse = await this.fetchImpl(url, fetchOpts);
+                const response = await this.normalizeResponse(rawResponse);
+                // Capture Set-Cookie headers
+                if (this.cookies) {
+                    const setCookies = this.extractSetCookies(rawResponse);
+                    for (const sc of setCookies) {
+                        this.cookies.ingestSetCookie(sc, url);
+                    }
+                }
+                if (response.status === 429 && attempt < attempts) {
+                    // Exponential backoff
+                    await new Promise((r) => setTimeout(r, 200 * 2 ** (attempt - 1)));
+                    continue;
+                }
+                return response;
+            }
+            catch (err) {
+                lastErr = err;
+                if (attempt >= attempts) {
+                    if (err instanceof Error && err.name === 'AbortError') {
+                        throw new index_js_1.YouTubeRequestFailed(url, 0, 'Request aborted (timeout)', url);
+                    }
+                    throw err;
+                }
+                await new Promise((r) => setTimeout(r, 200 * 2 ** (attempt - 1)));
+            }
+            finally {
+                clearTimeout(timeoutId);
+                opts.signal?.removeEventListener('abort', onUserAbort);
+            }
+        }
+        throw lastErr;
+    }
+    /**
+     * Wrap a raw `Response` so that `.json()` returns `unknown` and re-throwing
+     * makes the type usable in tests.
+     */
+    async normalizeResponse(raw) {
+        return {
+            status: raw.status,
+            statusText: raw.statusText,
+            ok: raw.ok,
+            text: () => raw.text(),
+            json: async () => {
+                try {
+                    return await raw.json();
+                }
+                catch (err) {
+                    throw new Error(`Failed to parse JSON response: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            },
+        };
+    }
+    extractSetCookies(raw) {
+        // Response.headers.getSetCookie is Node 18.14+ / 19.7+
+        const fn = raw.headers.getSetCookie;
+        if (typeof fn === 'function') {
+            try {
+                return fn.call(raw.headers);
+            }
+            catch {
+                // ignore
+            }
+        }
+        const single = raw.headers.get('set-cookie');
+        return single ? [single] : [];
+    }
+    /**
+     * Lazily load undici and create a ProxyAgent when a proxy URL is configured.
+     * Returns `undefined` if no proxy is set.
+     */
+    async maybeProxyDispatcher() {
+        if (!this.proxyUrl)
+            return undefined;
+        if (this.proxyDispatcher)
+            return this.proxyDispatcher;
+        const parsed = (0, proxyUrl_js_1.parseProxyUrl)(this.proxyUrl);
+        if (!parsed) {
+            throw new Error(`Invalid proxy URL: ${this.proxyUrl}`);
+        }
+        // Dynamic import so `undici` stays optional.
+        const undici = (await Promise.resolve().then(() => __importStar(require('undici'))));
+        const agentUrl = this.proxyUrl.startsWith('http')
+            ? this.proxyUrl
+            : `${parsed.protocol}://${parsed.host}${parsed.port ? `:${parsed.port}` : ''}`;
+        this.proxyDispatcher = new undici.ProxyAgent(agentUrl);
+        return this.proxyDispatcher;
+    }
+}
+exports.HttpClient = HttpClient;
+//# sourceMappingURL=httpClient.js.map

package/dist/cjs/http/httpClient.js.map

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

package/dist/cjs/index.js

@@ -0,0 +1,50 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTokenFresh = exports.BaseScriptCache = exports.AutoPoTokenProvider = exports.HttpPoTokenProvider = exports.NoopPoTokenProvider = exports.toPrettyTime = exports.toVttTime = exports.toSrtTime = exports.computeEnd = exports.PrettyPrintFormatter = exports.JSONFormatter = exports.TextFormatter = exports.WebVTTFormatter = exports.SRTFormatter = exports.TranscriptList = exports.Transcript = exports.FetchedTranscriptSnippet = exports.FetchedTranscript = exports.YouTubeTranscriptApi = void 0;
+/**
+ * youtube-transcript-nodejs — public API entry point.
+ */
+var YouTubeTranscriptApi_js_1 = require("./api/YouTubeTranscriptApi.js");
+Object.defineProperty(exports, "YouTubeTranscriptApi", { enumerable: true, get: function () { return YouTubeTranscriptApi_js_1.YouTubeTranscriptApi; } });
+var FetchedTranscript_js_1 = require("./models/FetchedTranscript.js");
+Object.defineProperty(exports, "FetchedTranscript", { enumerable: true, get: function () { return FetchedTranscript_js_1.FetchedTranscript; } });
+var FetchedTranscriptSnippet_js_1 = require("./models/FetchedTranscriptSnippet.js");
+Object.defineProperty(exports, "FetchedTranscriptSnippet", { enumerable: true, get: function () { return FetchedTranscriptSnippet_js_1.FetchedTranscriptSnippet; } });
+var Transcript_js_1 = require("./models/Transcript.js");
+Object.defineProperty(exports, "Transcript", { enumerable: true, get: function () { return Transcript_js_1.Transcript; } });
+var TranscriptList_js_1 = require("./models/TranscriptList.js");
+Object.defineProperty(exports, "TranscriptList", { enumerable: true, get: function () { return TranscriptList_js_1.TranscriptList; } });
+// Re-export error classes for `instanceof` checks in user code.
+__exportStar(require("./errors/index.js"), exports);
+// Re-export formatters so users can compose their own.
+var index_js_1 = require("./formatters/index.js");
+Object.defineProperty(exports, "SRTFormatter", { enumerable: true, get: function () { return index_js_1.SRTFormatter; } });
+Object.defineProperty(exports, "WebVTTFormatter", { enumerable: true, get: function () { return index_js_1.WebVTTFormatter; } });
+Object.defineProperty(exports, "TextFormatter", { enumerable: true, get: function () { return index_js_1.TextFormatter; } });
+Object.defineProperty(exports, "JSONFormatter", { enumerable: true, get: function () { return index_js_1.JSONFormatter; } });
+Object.defineProperty(exports, "PrettyPrintFormatter", { enumerable: true, get: function () { return index_js_1.PrettyPrintFormatter; } });
+Object.defineProperty(exports, "computeEnd", { enumerable: true, get: function () { return index_js_1.computeEnd; } });
+Object.defineProperty(exports, "toSrtTime", { enumerable: true, get: function () { return index_js_1.toSrtTime; } });
+Object.defineProperty(exports, "toVttTime", { enumerable: true, get: function () { return index_js_1.toVttTime; } });
+Object.defineProperty(exports, "toPrettyTime", { enumerable: true, get: function () { return index_js_1.toPrettyTime; } });
+var index_js_2 = require("./potoken/index.js");
+Object.defineProperty(exports, "NoopPoTokenProvider", { enumerable: true, get: function () { return index_js_2.NoopPoTokenProvider; } });
+Object.defineProperty(exports, "HttpPoTokenProvider", { enumerable: true, get: function () { return index_js_2.HttpPoTokenProvider; } });
+Object.defineProperty(exports, "AutoPoTokenProvider", { enumerable: true, get: function () { return index_js_2.AutoPoTokenProvider; } });
+Object.defineProperty(exports, "BaseScriptCache", { enumerable: true, get: function () { return index_js_2.BaseScriptCache; } });
+Object.defineProperty(exports, "isTokenFresh", { enumerable: true, get: function () { return index_js_2.isTokenFresh; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA;;GAEG;AACH,yEAAqE;AAA5D,+HAAA,oBAAoB,OAAA;AAG7B,sEAAkE;AAAzD,yHAAA,iBAAiB,OAAA;AAC1B,oFAAgF;AAAvE,uIAAA,wBAAwB,OAAA;AACjC,wDAAoD;AAA3C,2GAAA,UAAU,OAAA;AACnB,gEAA4D;AAAnD,mHAAA,cAAc,OAAA;AAMvB,gEAAgE;AAChE,oDAAkC;AAElC,uDAAuD;AACvD,kDAU+B;AAT7B,wGAAA,YAAY,OAAA;AACZ,2GAAA,eAAe,OAAA;AACf,yGAAA,aAAa,OAAA;AACb,yGAAA,aAAa,OAAA;AACb,gHAAA,oBAAoB,OAAA;AACpB,sGAAA,UAAU,OAAA;AACV,qGAAA,SAAS,OAAA;AACT,qGAAA,SAAS,OAAA;AACT,wGAAA,YAAY,OAAA;AAMd,+CAM4B;AAL1B,+GAAA,mBAAmB,OAAA;AACnB,+GAAA,mBAAmB,OAAA;AACnB,+GAAA,mBAAmB,OAAA;AACnB,2GAAA,eAAe,OAAA;AACf,wGAAA,YAAY,OAAA"}

package/dist/cjs/models/FetchedTranscript.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FetchedTranscript = void 0;
+const index_js_1 = require("../formatters/index.js");
+const FetchedTranscriptSnippet_js_1 = require("./FetchedTranscriptSnippet.js");
+/**
+ * Concrete transcript with all its cues loaded.
+ *
+ * Iterable and indexable. Provides formatting helpers that delegate
+ * to the formatter classes in `../formatters`.
+ */
+class FetchedTranscript {
+    snippets;
+    videoId;
+    language;
+    languageCode;
+    isGenerated;
+    translationLanguages;
+    constructor(snippets, meta) {
+        this.snippets = Object.freeze(snippets.map((s) => new FetchedTranscriptSnippet_js_1.FetchedTranscriptSnippet(s.text, s.start, s.duration)));
+        this.videoId = meta.videoId;
+        this.language = meta.languageName;
+        this.languageCode = meta.languageCode;
+        this.isGenerated = meta.isGenerated;
+        this.translationLanguages = meta.translationLanguages;
+    }
+    [Symbol.iterator]() {
+        return this.snippets[Symbol.iterator]();
+    }
+    get length() {
+        return this.snippets.length;
+    }
+    /** Format using an arbitrary formatter. */
+    format(formatter) {
+        const out = formatter.render(this.snippets);
+        return { content: out.content, extension: out.extension, mimeType: out.mimeType };
+    }
+    /** Raw array form (matches Python `to_raw_data()`). */
+    toRaw() {
+        return this.format(new index_js_1.JSONFormatter());
+    }
+    /** Plain text — one snippet per line. */
+    toText() {
+        return this.format(new index_js_1.TextFormatter());
+    }
+    /** SRT subtitle format. */
+    toSRT() {
+        return this.format(new index_js_1.SRTFormatter());
+    }
+    /** WebVTT subtitle format. */
+    toVTT() {
+        return this.format(new index_js_1.WebVTTFormatter());
+    }
+    /** Pretty-print human-readable. */
+    toPretty() {
+        return this.format(new index_js_1.PrettyPrintFormatter());
+    }
+    /** Serialize the entire transcript as a plain object. */
+    toJSON() {
+        return this.format(new index_js_1.JSONFormatter());
+    }
+    forEach(fn) {
+        this.snippets.forEach((s, i) => fn(s, i));
+    }
+    map(fn) {
+        return this.snippets.map(fn);
+    }
+    filter(fn) {
+        return this.snippets.filter(fn);
+    }
+    find(fn) {
+        return this.snippets.find(fn);
+    }
+    /** Pick a subset of snippets by 1-based line range (inclusive). */
+    slice(start, end) {
+        return this.snippets.slice(start, end);
+    }
+}
+exports.FetchedTranscript = FetchedTranscript;
+//# sourceMappingURL=FetchedTranscript.js.map

package/dist/cjs/models/FetchedTranscript.js.map

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

package/dist/cjs/models/FetchedTranscriptSnippet.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FetchedTranscriptSnippet = void 0;
+/**
+ * One snippet in a fetched transcript.
+ */
+class FetchedTranscriptSnippet {
+    text;
+    start;
+    duration;
+    constructor(text, start, duration) {
+        this.text = text;
+        this.start = start;
+        this.duration = duration;
+    }
+    /**
+     * End timestamp = start + duration (or earlier if the next snippet starts first).
+     * Lazily computed and cached.
+     */
+    endFor(_index, nextStart) {
+        const end = this.start + this.duration;
+        if (nextStart !== undefined && nextStart < end) {
+            return nextStart;
+        }
+        return end;
+    }
+}
+exports.FetchedTranscriptSnippet = FetchedTranscriptSnippet;
+//# sourceMappingURL=FetchedTranscriptSnippet.js.map

package/dist/cjs/models/FetchedTranscriptSnippet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FetchedTranscriptSnippet.js","sourceRoot":"","sources":["../../../src/models/FetchedTranscriptSnippet.ts"],"names":[],"mappings":";;;AAAA;;GAEG;AACH,MAAa,wBAAwB;IAC1B,IAAI,CAAS;IACb,KAAK,CAAS;IACd,QAAQ,CAAS;IAE1B,YAAY,IAAY,EAAE,KAAa,EAAE,QAAgB;QACvD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,MAAc,EAAE,SAA6B;QAClD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC;QACvC,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,GAAG,GAAG,EAAE,CAAC;YAC/C,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;CACF;AAtBD,4DAsBC"}

package/dist/cjs/models/FormattedTranscript.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=FormattedTranscript.js.map

package/dist/cjs/models/FormattedTranscript.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FormattedTranscript.js","sourceRoot":"","sources":["../../../src/models/FormattedTranscript.ts"],"names":[],"mappings":""}

package/dist/cjs/models/Transcript.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Transcript = void 0;
+const index_js_1 = require("../errors/index.js");
+const xmlTranscriptParser_js_1 = require("../parsers/xmlTranscriptParser.js");
+const FetchedTranscript_js_1 = require("./FetchedTranscript.js");
+/**
+ * A handle to a single caption track.
+ *
+ * Created via `TranscriptList.findTranscript` (or `.findGeneratedTranscript`,
+ * `.findManuallyCreatedTranscript`). To obtain the actual cues, call
+ * `.fetch()` or chain `.translate(targetLang).fetch()`.
+ */
+class Transcript {
+    videoId;
+    languageName;
+    languageCode;
+    isGenerated;
+    translationLanguages;
+    _baseUrl;
+    _httpClient;
+    _translationLanguageCodes;
+    constructor(httpClient, videoId, baseUrl, languageName, languageCode, isGenerated, translationLanguages) {
+        this._httpClient = httpClient;
+        this.videoId = videoId;
+        this._baseUrl = baseUrl;
+        this.languageName = languageName;
+        this.languageCode = languageCode;
+        this.isGenerated = isGenerated;
+        this.translationLanguages = translationLanguages;
+        this._translationLanguageCodes = new Set(translationLanguages.map((l) => l.languageCode));
+    }
+    get isTranslatable() {
+        return this.translationLanguages.length > 0;
+    }
+    /**
+     * Fetch this transcript's cues.
+     */
+    async fetch(preserveFormatting = false) {
+        const xml = await this._httpClient.fetchTranscriptXml(this._baseUrl, this.videoId);
+        const cues = (0, xmlTranscriptParser_js_1.parseTranscriptXml)(xml, { preserveFormatting });
+        return new FetchedTranscript_js_1.FetchedTranscript(cues.map((c) => ({ text: c.text, start: c.start, duration: c.duration })), this.toMetadata());
+    }
+    /**
+     * Translate this transcript to `targetLang`.
+     *
+     * Returns a new (un-fetched) Transcript whose `.fetch()` returns the
+     * translated cues. The translated track is not itself translatable.
+     */
+    translate(targetLang) {
+        if (!this.isTranslatable) {
+            throw new index_js_1.NotTranslatable(this.videoId);
+        }
+        if (!this._translationLanguageCodes.has(targetLang)) {
+            throw new index_js_1.TranslationLanguageNotAvailable(this.videoId, targetLang, [
+                ...this._translationLanguageCodes,
+            ]);
+        }
+        const newUrl = this._httpClient.buildTranslateUrl(this._baseUrl, targetLang);
+        const name = this.translationLanguages.find((l) => l.languageCode === targetLang);
+        return new Transcript(this._httpClient, this.videoId, newUrl, name?.languageName ?? targetLang, targetLang, true, []);
+    }
+    toMetadata() {
+        return {
+            videoId: this.videoId,
+            languageName: this.languageName,
+            languageCode: this.languageCode,
+            isGenerated: this.isGenerated,
+            isTranslatable: this.isTranslatable,
+            translationLanguages: this.translationLanguages,
+        };
+    }
+}
+exports.Transcript = Transcript;
+//# sourceMappingURL=Transcript.js.map

package/dist/cjs/models/Transcript.js.map

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

package/dist/cjs/models/TranscriptList.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TranscriptList = void 0;
+exports.buildTranscriptList = buildTranscriptList;
+const index_js_1 = require("../errors/index.js");
+const Transcript_js_1 = require("./Transcript.js");
+/**
+ * Collection of all available transcript tracks for a video.
+ *
+ * Created via `YouTubeTranscriptApi.list(videoId)`. Use the `find*` helpers
+ * to pick a track, then call `.fetch()` on the result.
+ */
+class TranscriptList {
+    videoId;
+    manuallyCreatedTranscripts;
+    generatedTranscripts;
+    translationLanguages;
+    constructor(videoId, manuallyCreatedTranscripts, generatedTranscripts, translationLanguages) {
+        this.videoId = videoId;
+        this.manuallyCreatedTranscripts = manuallyCreatedTranscripts;
+        this.generatedTranscripts = generatedTranscripts;
+        this.translationLanguages = translationLanguages;
+    }
+    /**
+     * Find a transcript matching one of the given language codes.
+     * Manual tracks are preferred over generated ones.
+     */
+    findTranscript(languageCodes) {
+        return this.findInOrder(languageCodes, [this.manuallyCreatedTranscripts, this.generatedTranscripts]);
+    }
+    /**
+     * Find only an ASR-generated transcript.
+     */
+    findGeneratedTranscript(languageCodes) {
+        return this.findInOrder(languageCodes, [this.generatedTranscripts]);
+    }
+    /**
+     * Find only a manually uploaded transcript.
+     */
+    findManuallyCreatedTranscript(languageCodes) {
+        return this.findInOrder(languageCodes, [this.manuallyCreatedTranscripts]);
+    }
+    findInOrder(codes, pools) {
+        for (const code of codes) {
+            for (const pool of pools) {
+                const found = pool.find((t) => t.languageCode === code);
+                if (found)
+                    return found;
+            }
+        }
+        throw new index_js_1.NoTranscriptFound({
+            videoId: this.videoId,
+            requestedLanguageCodes: codes,
+            transcriptData: this,
+        });
+    }
+    /**
+     * Iterate over all transcripts (manual first, then generated).
+     */
+    *[Symbol.iterator]() {
+        yield* this.manuallyCreatedTranscripts;
+        yield* this.generatedTranscripts;
+    }
+}
+exports.TranscriptList = TranscriptList;
+/**
+ * Factory helper to build a TranscriptList from raw caption data.
+ *
+ * `httpClient` is propagated to each Transcript so they can fetch their
+ * own cues lazily.
+ */
+function buildTranscriptList(httpClient, videoId, captionTracks, translationLanguages) {
+    const manual = [];
+    const generated = [];
+    for (const track of captionTracks) {
+        const t = new Transcript_js_1.Transcript(httpClient, videoId, track.baseUrl, track.name, track.languageCode, track.kind === 'asr', track.isTranslatable ? translationLanguages : []);
+        if (track.kind === 'asr')
+            generated.push(t);
+        else
+            manual.push(t);
+    }
+    return new TranscriptList(videoId, manual, generated, translationLanguages);
+}
+//# sourceMappingURL=TranscriptList.js.map

package/dist/cjs/models/TranscriptList.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TranscriptList.js","sourceRoot":"","sources":["../../../src/models/TranscriptList.ts"],"names":[],"mappings":";;;AAmFA,kDA4BC;AA/GD,iDAAuD;AAEvD,mDAA6C;AAG7C;;;;;GAKG;AACH,MAAa,cAAc;IAChB,OAAO,CAAS;IAChB,0BAA0B,CAAwB;IAClD,oBAAoB,CAAwB;IAC5C,oBAAoB,CAAiC;IAE9D,YACE,OAAe,EACf,0BAAiD,EACjD,oBAA2C,EAC3C,oBAAoD;QAEpD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,0BAA0B,GAAG,0BAA0B,CAAC;QAC7D,IAAI,CAAC,oBAAoB,GAAG,oBAAoB,CAAC;QACjD,IAAI,CAAC,oBAAoB,GAAG,oBAAoB,CAAC;IACnD,CAAC;IAED;;;OAGG;IACH,cAAc,CAAC,aAAgC;QAC7C,OAAO,IAAI,CAAC,WAAW,CAAC,aAAa,EAAE,CAAC,IAAI,CAAC,0BAA0B,EAAE,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC;IACvG,CAAC;IAED;;OAEG;IACH,uBAAuB,CAAC,aAAgC;QACtD,OAAO,IAAI,CAAC,WAAW,CAAC,aAAa,EAAE,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC;IACtE,CAAC;IAED;;OAEG;IACH,6BAA6B,CAAC,aAAgC;QAC5D,OAAO,IAAI,CAAC,WAAW,CAAC,aAAa,EAAE,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC,CAAC;IAC5E,CAAC;IAEO,WAAW,CACjB,KAAwB,EACxB,KAAyC;QAEzC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,IAAI,CAAC,CAAC;gBACxD,IAAI,KAAK;oBAAE,OAAO,KAAK,CAAC;YAC1B,CAAC;QACH,CAAC;QACD,MAAM,IAAI,4BAAiB,CAAC;YAC1B,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,sBAAsB,EAAE,KAAK;YAC7B,cAAc,EAAE,IAAI;SACrB,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC;QAChB,KAAK,CAAC,CAAC,IAAI,CAAC,0BAA0B,CAAC;QACvC,KAAK,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC;IACnC,CAAC;CACF;AAhED,wCAgEC;AAED;;;;;GAKG;AACH,SAAgB,mBAAmB,CACjC,UAA2B,EAC3B,OAAe,EACf,aAME,EACF,oBAAoD;IAEpD,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,MAAM,SAAS,GAAiB,EAAE,CAAC;IACnC,KAAK,MAAM,KAAK,IAAI,aAAa,EAAE,CAAC;QAClC,MAAM,CAAC,GAAG,IAAI,0BAAU,CACtB,UAAU,EACV,OAAO,EACP,KAAK,CAAC,OAAO,EACb,KAAK,CAAC,IAAI,EACV,KAAK,CAAC,YAAY,EAClB,KAAK,CAAC,IAAI,KAAK,KAAK,EACpB,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,CACjD,CAAC;QACF,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK;YAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;;YACvC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,IAAI,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,oBAAoB,CAAC,CAAC;AAC9E,CAAC"}

package/dist/cjs/models/TranscriptMetadata.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=TranscriptMetadata.js.map

package/dist/cjs/models/TranscriptMetadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TranscriptMetadata.js","sourceRoot":"","sources":["../../../src/models/TranscriptMetadata.ts"],"names":[],"mappings":""}

package/dist/cjs/models/TranslationLanguage.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=TranslationLanguage.js.map

package/dist/cjs/models/TranslationLanguage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TranslationLanguage.js","sourceRoot":"","sources":["../../../src/models/TranslationLanguage.ts"],"names":[],"mappings":""}

package/dist/cjs/models/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTranscriptList = exports.TranscriptList = exports.Transcript = exports.FetchedTranscript = exports.FetchedTranscriptSnippet = void 0;
+var FetchedTranscriptSnippet_js_1 = require("./FetchedTranscriptSnippet.js");
+Object.defineProperty(exports, "FetchedTranscriptSnippet", { enumerable: true, get: function () { return FetchedTranscriptSnippet_js_1.FetchedTranscriptSnippet; } });
+var FetchedTranscript_js_1 = require("./FetchedTranscript.js");
+Object.defineProperty(exports, "FetchedTranscript", { enumerable: true, get: function () { return FetchedTranscript_js_1.FetchedTranscript; } });
+var Transcript_js_1 = require("./Transcript.js");
+Object.defineProperty(exports, "Transcript", { enumerable: true, get: function () { return Transcript_js_1.Transcript; } });
+var TranscriptList_js_1 = require("./TranscriptList.js");
+Object.defineProperty(exports, "TranscriptList", { enumerable: true, get: function () { return TranscriptList_js_1.TranscriptList; } });
+Object.defineProperty(exports, "buildTranscriptList", { enumerable: true, get: function () { return TranscriptList_js_1.buildTranscriptList; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/models/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/models/index.ts"],"names":[],"mappings":";;;AAAA,6EAAyE;AAAhE,uIAAA,wBAAwB,OAAA;AACjC,+DAA2D;AAAlD,yHAAA,iBAAiB,OAAA;AAC1B,iDAA6C;AAApC,2GAAA,UAAU,OAAA;AACnB,yDAA0E;AAAjE,mHAAA,cAAc,OAAA;AAAE,wHAAA,mBAAmB,OAAA"}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}