@nadimtuhin/ytranscript 1.0.2 → 1.2.0

package/dist/cli.js

@@ -1,5 +1,5 @@
-#!/usr/bin/env bun
-// @bun
+#!/usr/bin/env node
+import {createRequire} from "node:module";
 var __create = Object.create;
 var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
@@ -17,6 +17,7 @@ var __toESM = (mod, isNodeMode, target) => {
   return to;
 };
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // node_modules/commander/lib/error.js
 var require_error = __commonJS((exports) => {
@@ -616,11 +617,11 @@ var require_command = __commonJS((exports) => {
       return arg;
     });
   }
-  var EventEmitter = import.meta.require("events").EventEmitter;
-  var childProcess = import.meta.require("child_process");
-  var path = import.meta.require("path");
-  var fs = import.meta.require("fs");
-  var process2 = import.meta.require("process");
+  var EventEmitter = __require("node:events").EventEmitter;
+  var childProcess = __require("node:child_process");
+  var path = __require("node:path");
+  var fs = __require("node:fs");
+  var process2 = __require("node:process");
   var { Argument, humanReadableArgName } = require_argument();
   var { CommanderError } = require_error();
   var { Help } = require_help();
@@ -1844,6 +1845,9 @@ var require_commander = __commonJS((exports) => {
   exports.InvalidOptionArgumentError = InvalidArgumentError;
 });
 
+// src/cli.ts
+import {readFile as readFile2, writeFile as writeFile2} from "node:fs/promises";
+
 // node_modules/commander/esm.mjs
 var import_ = __toESM(require_commander(), 1);
 var {
@@ -1860,9 +1864,10 @@ var {
   Help
 } = import_.default;
 // package.json
-var version = "1.0.2";
+var version = "1.2.0";
 
 // src/lib/fetcher.ts
+import {createRequire as createRequire2} from "node:module";
 function extractVideoId(input) {
   if (/^[a-zA-Z0-9_-]{11}$/.test(input)) {
     return input;
@@ -1888,9 +1893,20 @@ function extractVideoId(input) {
   }
   return null;
 }
-async function fetchPlayerResponse(videoId, timeout) {
+function createProxyAgent(proxy) {
+  if (proxy) {
+    return new ProxyAgent(proxy.url);
+  }
+  const envProxy = process.env.HTTP_PROXY || process.env.http_proxy || process.env.HTTPS_PROXY || process.env.https_proxy;
+  if (envProxy) {
+    return new ProxyAgent(envProxy);
+  }
+  return;
+}
+async function fetchPlayerResponse(videoId, timeout, proxy) {
   const controller = new AbortController;
   const timeoutId = setTimeout(() => controller.abort(), timeout);
+  const dispatcher = createProxyAgent(proxy);
   try {
     const response = await fetch("https://www.youtube.com/youtubei/v1/player?prettyPrint=false", {
       method: "POST",
@@ -1907,7 +1923,8 @@ async function fetchPlayerResponse(videoId, timeout) {
         },
         videoId
       }),
-      signal: controller.signal
+      signal: controller.signal,
+      ...dispatcher && { dispatcher }
     });
     if (!response.ok) {
       throw new Error(`HTTP ${response.status}: ${response.statusText}`);
@@ -1917,14 +1934,16 @@ async function fetchPlayerResponse(videoId, timeout) {
     clearTimeout(timeoutId);
   }
 }
-async function fetchCaptionTrack(url, timeout) {
+async function fetchCaptionTrack(url, timeout, proxy) {
   const controller = new AbortController;
   const timeoutId = setTimeout(() => controller.abort(), timeout);
+  const dispatcher = createProxyAgent(proxy);
   try {
     const jsonUrl = `${url}&fmt=json3`;
     const response = await fetch(jsonUrl, {
       headers: { "User-Agent": USER_AGENT },
-      signal: controller.signal
+      signal: controller.signal,
+      ...dispatcher && { dispatcher }
     });
     if (!response.ok) {
       throw new Error(`HTTP ${response.status}`);
@@ -1962,9 +1981,14 @@ function selectCaptionTrack(tracks, preferredLanguages, includeAutoGenerated) {
   }
   return searchOrder[0] || null;
 }
+async function fetchVideoInfo(videoId, options = {}) {
+  const { timeout = 30000, proxy } = options;
+  const playerResponse = await fetchPlayerResponse(videoId, timeout, proxy);
+  return playerResponse.captions?.playerCaptionsTracklistRenderer?.captionTracks || [];
+}
 async function fetchTranscript(videoId, options = {}) {
-  const { languages = ["en"], timeout = 30000, includeAutoGenerated = true } = options;
-  const playerResponse = await fetchPlayerResponse(videoId, timeout);
+  const { languages = ["en"], timeout = 30000, includeAutoGenerated = true, proxy } = options;
+  const playerResponse = await fetchPlayerResponse(videoId, timeout, proxy);
   const captionTracks = playerResponse.captions?.playerCaptionsTracklistRenderer?.captionTracks;
   if (!captionTracks?.length) {
     throw new Error("No captions available for this video");
@@ -1973,7 +1997,7 @@ async function fetchTranscript(videoId, options = {}) {
   if (!selectedTrack) {
     throw new Error("No suitable caption track found");
   }
-  const segments = await fetchCaptionTrack(selectedTrack.baseUrl, timeout);
+  const segments = await fetchCaptionTrack(selectedTrack.baseUrl, timeout, proxy);
   if (!segments.length) {
     throw new Error("Caption track is empty");
   }
@@ -1986,6 +2010,8 @@ async function fetchTranscript(videoId, options = {}) {
     isAutoGenerated: selectedTrack.kind === "asr"
   };
 }
+var require2 = createRequire2(import.meta.url);
+var ProxyAgent = require2("undici/lib/dispatcher/proxy-agent");
 var USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
 // node_modules/yocto-queue/index.js
 class Node {
@@ -2163,6 +2189,26 @@ async function* streamVideos(videos, options = {}) {
 var DEFAULT_CONCURRENCY = 4;
 var DEFAULT_PAUSE_AFTER = 10;
 var DEFAULT_PAUSE_DURATION = 5000;
+// src/lib/fs.ts
+import {readFile, writeFile, appendFile, access, constants} from "node:fs/promises";
+async function fileExists(path) {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readTextFile(path) {
+  return readFile(path, "utf-8");
+}
+async function writeTextFile(path, content) {
+  await writeFile(path, content, "utf-8");
+}
+async function appendTextFile(path, content) {
+  await appendFile(path, content, "utf-8");
+}
+
 // src/loaders/history.ts
 function extractVideoIdFromUrl(url) {
   try {
@@ -2178,8 +2224,7 @@ function extractVideoIdFromUrl(url) {
   return null;
 }
 async function loadWatchHistory(filePath) {
-  const file = Bun.file(filePath);
-  const text = await file.text();
+  const text = await readTextFile(filePath);
   const data = JSON.parse(text);
   const results = [];
   for (const item of data) {
@@ -2243,8 +2288,7 @@ function parseCSVLine(line) {
   return result;
 }
 async function loadWatchLater(filePath) {
-  const file = Bun.file(filePath);
-  const text = await file.text();
+  const text = await readTextFile(filePath);
   const rows = parseCSV(text);
   const results = [];
   for (const row of rows) {
@@ -2290,11 +2334,11 @@ function mergeVideoSources(...sources) {
 async function loadProcessedIds(jsonlPath) {
   const ids = new Set;
   try {
-    const file = Bun.file(jsonlPath);
-    if (!await file.exists()) {
+    const exists = await fileExists(jsonlPath);
+    if (!exists) {
       return ids;
     }
-    const text = await file.text();
+    const text = await readTextFile(jsonlPath);
     const lines = text.split("\n").filter((l) => l.trim());
     for (const line of lines) {
       try {
@@ -2313,10 +2357,7 @@ async function loadProcessedIds(jsonlPath) {
 }
 // src/outputs/index.ts
 async function appendJsonl(result, path) {
-  const file = Bun.file(path);
-  const existing = await file.exists() ? await file.text() : "";
-  const newContent = `${existing + JSON.stringify(result)}\n`;
-  await Bun.write(path, newContent);
+  await appendTextFile(path, `${JSON.stringify(result)}\n`);
 }
 async function writeCsv(results, options) {
   const headers = [
@@ -2348,12 +2389,12 @@ async function writeCsv(results, options) {
     ...rows.map((row) => row.map((cell) => `"${String(cell).replace(/"/g, '""')}"`).join(","))
   ].join("\n");
   if (options.append) {
-    const file = Bun.file(options.path);
-    const existing = await file.exists() ? await file.text() : "";
-    const content = existing ? `${rows.map((row) => row.map((cell) => `"${String(cell).replace(/"/g, '""')}"`).join(",")).join("\n")}\n` : `${csvContent}\n`;
-    await Bun.write(options.path, existing + content);
+    const exists = await fileExists(options.path);
+    const rowsContent = rows.map((row) => row.map((cell) => `"${String(cell).replace(/"/g, '""')}"`).join(",")).join("\n");
+    const content = exists ? `${rowsContent}\n` : `${csvContent}\n`;
+    await appendTextFile(options.path, content);
   } else {
-    await Bun.write(options.path, `${csvContent}\n`);
+    await writeTextFile(options.path, `${csvContent}\n`);
   }
 }
 function formatSrt(transcript) {
@@ -2408,20 +2449,40 @@ function pad(num, size) {
   return String(num).padStart(size, "0");
 }
 // src/cli.ts
+function validateProxyUrl(url) {
+  try {
+    const parsed = new URL(url);
+    return ["http:", "https:", "socks4:", "socks5:"].includes(parsed.protocol);
+  } catch {
+    return false;
+  }
+}
+function parseProxy(proxyUrl) {
+  if (!proxyUrl)
+    return;
+  if (!validateProxyUrl(proxyUrl)) {
+    console.error(red(`Invalid proxy URL: ${proxyUrl}`));
+    console.error(dim("Expected format: http://[user:pass@]host:port"));
+    process.exit(1);
+  }
+  return { url: proxyUrl };
+}
 var green = (s) => `\x1B[32m${s}\x1B[0m`;
 var red = (s) => `\x1B[31m${s}\x1B[0m`;
 var yellow = (s) => `\x1B[33m${s}\x1B[0m`;
 var dim = (s) => `\x1B[2m${s}\x1B[0m`;
 program.name("ytranscript").description("Fast YouTube transcript extraction with bulk processing").version(version);
-program.command("get <video>").description("Fetch transcript for a single video (ID or URL)").option("-l, --lang <codes>", "Preferred language codes (comma-separated)", "en").option("-f, --format <format>", "Output format: text, json, srt, vtt", "text").option("-t, --timestamps", "Include timestamps in text output").option("-o, --output <file>", "Write to file instead of stdout").action(async (video, options) => {
+program.command("get <video>").description("Fetch transcript for a single video (ID or URL)").option("-l, --lang <codes>", "Preferred language codes (comma-separated)", "en").option("-f, --format <format>", "Output format: text, json, srt, vtt", "text").option("-t, --timestamps", "Include timestamps in text output").option("-o, --output <file>", "Write to file instead of stdout").option("--proxy <url>", "HTTP proxy URL (e.g., http://user:pass@host:port)").action(async (video, options) => {
   const videoId = extractVideoId(video);
   if (!videoId) {
     console.error(red(`Invalid video ID or URL: ${video}`));
     process.exit(1);
   }
+  const proxy = parseProxy(options.proxy);
   try {
     const transcript = await fetchTranscript(videoId, {
-      languages: options.lang.split(",")
+      languages: options.lang.split(","),
+      proxy
     });
     let output;
     switch (options.format) {
@@ -2438,7 +2499,7 @@ program.command("get <video>").description("Fetch transcript for a single video
         output = formatText(transcript, options.timestamps);
     }
     if (options.output) {
-      await Bun.write(options.output, output);
+      await writeFile2(options.output, output, "utf-8");
       console.log(green(`Written to ${options.output}`));
     } else {
       console.log(output);
@@ -2448,7 +2509,7 @@ program.command("get <video>").description("Fetch transcript for a single video
     process.exit(1);
   }
 });
-program.command("bulk").description("Bulk fetch transcripts from Google Takeout or video list").option("--history <file>", "Path to Google Takeout watch-history.json").option("--watch-later <file>", "Path to Google Takeout watch-later.csv").option("--videos <ids>", "Comma-separated video IDs or URLs").option("--file <file>", "File with video IDs/URLs (one per line)").option("-o, --out-jsonl <file>", "Output JSONL file", "transcripts.jsonl").option("--out-csv <file>", "Also write to CSV file").option("-c, --concurrency <n>", "Concurrent requests", "4").option("--pause-after <n>", "Pause after N requests", "10").option("--pause-ms <n>", "Pause duration in ms", "5000").option("-l, --lang <codes>", "Preferred languages (comma-separated)", "en").option("--resume", "Resume from previous run (skip already processed)").action(async (options) => {
+program.command("bulk").description("Bulk fetch transcripts from Google Takeout or video list").option("--history <file>", "Path to Google Takeout watch-history.json").option("--watch-later <file>", "Path to Google Takeout watch-later.csv").option("--videos <ids>", "Comma-separated video IDs or URLs").option("--file <file>", "File with video IDs/URLs (one per line)").option("-o, --out-jsonl <file>", "Output JSONL file", "transcripts.jsonl").option("--out-csv <file>", "Also write to CSV file").option("-c, --concurrency <n>", "Concurrent requests", "4").option("--pause-after <n>", "Pause after N requests", "10").option("--pause-ms <n>", "Pause duration in ms", "5000").option("-l, --lang <codes>", "Preferred languages (comma-separated)", "en").option("--proxy <url>", "HTTP proxy URL (e.g., http://user:pass@host:port)").option("--resume", "Resume from previous run (skip already processed)").action(async (options) => {
   const sources = [];
   if (options.history) {
     console.log(dim(`Loading watch history from ${options.history}...`));
@@ -2477,7 +2538,7 @@ program.command("bulk").description("Bulk fetch transcripts from Google Takeout
   }
   if (options.file) {
     try {
-      const content = await Bun.file(options.file).text();
+      const content = await readFile2(options.file, "utf-8");
       const ids = content.split("\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("#"));
       sources.push(fromVideoIds(ids));
       console.log(`  Added ${ids.length} videos from ${options.file}`);
@@ -2503,15 +2564,17 @@ program.command("bulk").description("Bulk fetch transcripts from Google Takeout
     console.log(green("All videos already processed!"));
     return;
   }
-  console.log(`Processing ${toProcess.length} videos...\n`);
+  console.log(`Processing ${toProcess.length} videos...\\n`);
   let successCount = 0;
   let failCount = 0;
   const csvResults = [];
+  const proxy = parseProxy(options.proxy);
   for await (const result of streamVideos(toProcess, {
     concurrency: Number.parseInt(options.concurrency, 10),
     pauseAfter: Number.parseInt(options.pauseAfter, 10),
     pauseDuration: Number.parseInt(options.pauseMs, 10),
-    languages: options.lang.split(",")
+    languages: options.lang.split(","),
+    proxy
   })) {
     const status = result.transcript ? green("OK") : red("FAIL");
     const title = result.meta.title?.slice(0, 50) || result.meta.videoId;
@@ -2533,25 +2596,15 @@ program.command("bulk").description("Bulk fetch transcripts from Google Takeout
   console.log(`\n${green("Done!")} ${successCount} succeeded, ${failCount} failed`);
   console.log(`Output: ${options.outJsonl}`);
 });
-program.command("info <video>").description("Show available transcript languages for a video").action(async (video) => {
+program.command("info <video>").description("Show available transcript languages for a video").option("--proxy <url>", "HTTP proxy URL (e.g., http://user:pass@host:port)").action(async (video, options) => {
   const videoId = extractVideoId(video);
   if (!videoId) {
     console.error(red(`Invalid video ID or URL: ${video}`));
     process.exit(1);
   }
+  const proxy = parseProxy(options.proxy);
   try {
-    const response = await fetch("https://www.youtube.com/youtubei/v1/player?prettyPrint=false", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        context: {
-          client: { clientName: "WEB", clientVersion: "2.20240101.00.00" }
-        },
-        videoId
-      })
-    });
-    const data = await response.json();
-    const tracks = data.captions?.playerCaptionsTracklistRenderer?.captionTracks || [];
+    const tracks = await fetchVideoInfo(videoId, { proxy });
     if (!tracks.length) {
       console.log(yellow("No captions available for this video"));
       return;

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * ytranscript - Fast YouTube transcript extraction
+ *
+ * @example
+ * ```typescript
+ * import { fetchTranscript, processVideos } from 'ytranscript';
+ *
+ * // Fetch a single transcript
+ * const transcript = await fetchTranscript('dQw4w9WgXcQ');
+ * console.log(transcript.text);
+ *
+ * // Bulk process from Google Takeout
+ * import { loadWatchHistory, loadWatchLater, mergeVideoSources } from 'ytranscript';
+ *
+ * const history = await loadWatchHistory('./watch-history.json');
+ * const watchLater = await loadWatchLater('./watch-later.csv');
+ * const videos = mergeVideoSources(history, watchLater);
+ *
+ * const results = await processVideos(videos, {
+ *   concurrency: 4,
+ *   onProgress: (done, total) => console.log(`${done}/${total}`)
+ * });
+ * ```
+ */
+export { fetchTranscript, extractVideoId, fetchVideoInfo } from './lib/fetcher';
+export { processVideos, streamVideos } from './lib/processor';
+export { loadWatchHistory, loadWatchLater, fromVideoIds, mergeVideoSources, loadProcessedIds, } from './loaders';
+export { writeJsonl, appendJsonl, writeCsv, formatSrt, formatVtt, formatText, } from './outputs';
+export type { ProxyConfig, Transcript, TranscriptSegment, TranscriptResult, WatchHistoryMeta, FetchOptions, BulkOptions, OutputFormat, OutputOptions, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAGhF,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAG9D,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,UAAU,EACV,WAAW,EACX,QAAQ,EACR,SAAS,EACT,SAAS,EACT,UAAU,GACX,MAAM,WAAW,CAAC;AAGnB,YAAY,EACV,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,aAAa,GACd,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -1,4 +1,5 @@
 // src/lib/fetcher.ts
+import {createRequire} from "node:module";
 function extractVideoId(input) {
   if (/^[a-zA-Z0-9_-]{11}$/.test(input)) {
     return input;
@@ -24,9 +25,20 @@ function extractVideoId(input) {
   }
   return null;
 }
-async function fetchPlayerResponse(videoId, timeout) {
+function createProxyAgent(proxy) {
+  if (proxy) {
+    return new ProxyAgent(proxy.url);
+  }
+  const envProxy = process.env.HTTP_PROXY || process.env.http_proxy || process.env.HTTPS_PROXY || process.env.https_proxy;
+  if (envProxy) {
+    return new ProxyAgent(envProxy);
+  }
+  return;
+}
+async function fetchPlayerResponse(videoId, timeout, proxy) {
   const controller = new AbortController;
   const timeoutId = setTimeout(() => controller.abort(), timeout);
+  const dispatcher = createProxyAgent(proxy);
   try {
     const response = await fetch("https://www.youtube.com/youtubei/v1/player?prettyPrint=false", {
       method: "POST",
@@ -43,7 +55,8 @@ async function fetchPlayerResponse(videoId, timeout) {
         },
         videoId
       }),
-      signal: controller.signal
+      signal: controller.signal,
+      ...dispatcher && { dispatcher }
     });
     if (!response.ok) {
       throw new Error(`HTTP ${response.status}: ${response.statusText}`);
@@ -53,14 +66,16 @@ async function fetchPlayerResponse(videoId, timeout) {
     clearTimeout(timeoutId);
   }
 }
-async function fetchCaptionTrack(url, timeout) {
+async function fetchCaptionTrack(url, timeout, proxy) {
   const controller = new AbortController;
   const timeoutId = setTimeout(() => controller.abort(), timeout);
+  const dispatcher = createProxyAgent(proxy);
   try {
     const jsonUrl = `${url}&fmt=json3`;
     const response = await fetch(jsonUrl, {
       headers: { "User-Agent": USER_AGENT },
-      signal: controller.signal
+      signal: controller.signal,
+      ...dispatcher && { dispatcher }
     });
     if (!response.ok) {
       throw new Error(`HTTP ${response.status}`);
@@ -98,9 +113,14 @@ function selectCaptionTrack(tracks, preferredLanguages, includeAutoGenerated) {
   }
   return searchOrder[0] || null;
 }
+async function fetchVideoInfo(videoId, options = {}) {
+  const { timeout = 30000, proxy } = options;
+  const playerResponse = await fetchPlayerResponse(videoId, timeout, proxy);
+  return playerResponse.captions?.playerCaptionsTracklistRenderer?.captionTracks || [];
+}
 async function fetchTranscript(videoId, options = {}) {
-  const { languages = ["en"], timeout = 30000, includeAutoGenerated = true } = options;
-  const playerResponse = await fetchPlayerResponse(videoId, timeout);
+  const { languages = ["en"], timeout = 30000, includeAutoGenerated = true, proxy } = options;
+  const playerResponse = await fetchPlayerResponse(videoId, timeout, proxy);
   const captionTracks = playerResponse.captions?.playerCaptionsTracklistRenderer?.captionTracks;
   if (!captionTracks?.length) {
     throw new Error("No captions available for this video");
@@ -109,7 +129,7 @@ async function fetchTranscript(videoId, options = {}) {
   if (!selectedTrack) {
     throw new Error("No suitable caption track found");
   }
-  const segments = await fetchCaptionTrack(selectedTrack.baseUrl, timeout);
+  const segments = await fetchCaptionTrack(selectedTrack.baseUrl, timeout, proxy);
   if (!segments.length) {
     throw new Error("Caption track is empty");
   }
@@ -122,6 +142,8 @@ async function fetchTranscript(videoId, options = {}) {
     isAutoGenerated: selectedTrack.kind === "asr"
   };
 }
+var require2 = createRequire(import.meta.url);
+var ProxyAgent = require2("undici/lib/dispatcher/proxy-agent");
 var USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
 // node_modules/yocto-queue/index.js
 class Node {
@@ -344,6 +366,26 @@ async function* streamVideos(videos, options = {}) {
 var DEFAULT_CONCURRENCY = 4;
 var DEFAULT_PAUSE_AFTER = 10;
 var DEFAULT_PAUSE_DURATION = 5000;
+// src/lib/fs.ts
+import {readFile, writeFile, appendFile, access, constants} from "node:fs/promises";
+async function fileExists(path) {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readTextFile(path) {
+  return readFile(path, "utf-8");
+}
+async function writeTextFile(path, content) {
+  await writeFile(path, content, "utf-8");
+}
+async function appendTextFile(path, content) {
+  await appendFile(path, content, "utf-8");
+}
+
 // src/loaders/history.ts
 function extractVideoIdFromUrl(url) {
   try {
@@ -359,8 +401,7 @@ function extractVideoIdFromUrl(url) {
   return null;
 }
 async function loadWatchHistory(filePath) {
-  const file = Bun.file(filePath);
-  const text = await file.text();
+  const text = await readTextFile(filePath);
   const data = JSON.parse(text);
   const results = [];
   for (const item of data) {
@@ -424,8 +465,7 @@ function parseCSVLine(line) {
   return result;
 }
 async function loadWatchLater(filePath) {
-  const file = Bun.file(filePath);
-  const text = await file.text();
+  const text = await readTextFile(filePath);
   const rows = parseCSV(text);
   const results = [];
   for (const row of rows) {
@@ -471,11 +511,11 @@ function mergeVideoSources(...sources) {
 async function loadProcessedIds(jsonlPath) {
   const ids = new Set;
   try {
-    const file = Bun.file(jsonlPath);
-    if (!await file.exists()) {
+    const exists = await fileExists(jsonlPath);
+    if (!exists) {
       return ids;
     }
-    const text = await file.text();
+    const text = await readTextFile(jsonlPath);
     const lines = text.split("\n").filter((l) => l.trim());
     for (const line of lines) {
       try {
@@ -497,16 +537,13 @@ async function writeJsonl(results, options) {
   const lines = results.map((r) => JSON.stringify(r));
   const content = `${lines.join("\n")}\n`;
   if (options.append) {
-    await Bun.write(options.path, content, { mode: "a" });
+    await appendTextFile(options.path, content);
   } else {
-    await Bun.write(options.path, content);
+    await writeTextFile(options.path, content);
   }
 }
 async function appendJsonl(result, path) {
-  const file = Bun.file(path);
-  const existing = await file.exists() ? await file.text() : "";
-  const newContent = `${existing + JSON.stringify(result)}\n`;
-  await Bun.write(path, newContent);
+  await appendTextFile(path, `${JSON.stringify(result)}\n`);
 }
 async function writeCsv(results, options) {
   const headers = [
@@ -538,12 +575,12 @@ async function writeCsv(results, options) {
     ...rows.map((row) => row.map((cell) => `"${String(cell).replace(/"/g, '""')}"`).join(","))
   ].join("\n");
   if (options.append) {
-    const file = Bun.file(options.path);
-    const existing = await file.exists() ? await file.text() : "";
-    const content = existing ? `${rows.map((row) => row.map((cell) => `"${String(cell).replace(/"/g, '""')}"`).join(",")).join("\n")}\n` : `${csvContent}\n`;
-    await Bun.write(options.path, existing + content);
+    const exists = await fileExists(options.path);
+    const rowsContent = rows.map((row) => row.map((cell) => `"${String(cell).replace(/"/g, '""')}"`).join(",")).join("\n");
+    const content = exists ? `${rowsContent}\n` : `${csvContent}\n`;
+    await appendTextFile(options.path, content);
   } else {
-    await Bun.write(options.path, `${csvContent}\n`);
+    await writeTextFile(options.path, `${csvContent}\n`);
   }
 }
 function formatSrt(transcript) {
@@ -610,6 +647,7 @@ export {
   formatVtt,
   formatText,
   formatSrt,
+  fetchVideoInfo,
   fetchTranscript,
   extractVideoId,
   appendJsonl

package/dist/lib/fetcher.d.ts

@@ -0,0 +1,26 @@
+/**
+ * YouTube transcript fetcher using YouTube's innertube API
+ * No third-party services required
+ */
+import type { FetchOptions, Transcript } from '../types';
+export interface CaptionTrack {
+    baseUrl: string;
+    languageCode: string;
+    kind?: string;
+    name?: {
+        simpleText?: string;
+    };
+}
+/**
+ * Extract video ID from various YouTube URL formats
+ */
+export declare function extractVideoId(input: string): string | null;
+/**
+ * Fetch available caption tracks for a video
+ */
+export declare function fetchVideoInfo(videoId: string, options?: FetchOptions): Promise<CaptionTrack[]>;
+/**
+ * Fetch transcript for a single video
+ */
+export declare function fetchTranscript(videoId: string, options?: FetchOptions): Promise<Transcript>;
+//# sourceMappingURL=fetcher.d.ts.map

package/dist/lib/fetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetcher.d.ts","sourceRoot":"","sources":["../../src/lib/fetcher.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAe,UAAU,EAAqB,MAAM,UAAU,CAAC;AASzF,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAChC;AAUD;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA+B3D;AAsJD;;GAEG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,YAAY,EAAE,CAAC,CAIzB;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,UAAU,CAAC,CAgCrB"}

package/dist/lib/fs.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Cross-runtime file utilities (works with Node.js and Bun)
+ */
+/**
+ * Check if a file exists
+ */
+export declare function fileExists(path: string): Promise<boolean>;
+/**
+ * Read file contents as text
+ */
+export declare function readTextFile(path: string): Promise<string>;
+/**
+ * Write content to file (overwrites existing)
+ */
+export declare function writeTextFile(path: string, content: string): Promise<void>;
+/**
+ * Append content to file
+ */
+export declare function appendTextFile(path: string, content: string): Promise<void>;
+//# sourceMappingURL=fs.d.ts.map

package/dist/lib/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/lib/fs.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;GAEG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO/D;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEhE;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhF;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEjF"}

package/dist/lib/processor.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Bulk transcript processor with concurrency control,
+ * rate limiting, and resume support
+ */
+import type { BulkOptions, TranscriptResult, WatchHistoryMeta } from '../types';
+/**
+ * Process multiple videos in bulk with concurrency control
+ */
+export declare function processVideos(videos: WatchHistoryMeta[], options?: BulkOptions): Promise<TranscriptResult[]>;
+/**
+ * Create a streaming processor that yields results as they complete
+ */
+export declare function streamVideos(videos: WatchHistoryMeta[], options?: BulkOptions): AsyncGenerator<TranscriptResult>;
+//# sourceMappingURL=processor.d.ts.map

package/dist/lib/processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processor.d.ts","sourceRoot":"","sources":["../../src/lib/processor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAOhF;;GAEG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,gBAAgB,EAAE,EAC1B,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA2D7B;AAED;;GAEG;AACH,wBAAuB,YAAY,CACjC,MAAM,EAAE,gBAAgB,EAAE,EAC1B,OAAO,GAAE,WAAgB,GACxB,cAAc,CAAC,gBAAgB,CAAC,CAwClC"}

package/dist/loaders/history.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Load YouTube watch history from Google Takeout JSON
+ */
+import type { WatchHistoryMeta } from '../types';
+/**
+ * Load watch history from Google Takeout JSON file
+ */
+export declare function loadWatchHistory(filePath: string): Promise<WatchHistoryMeta[]>;
+//# sourceMappingURL=history.d.ts.map