@nadimtuhin/ytranscript 1.0.2 → 1.2.0

package/dist/loaders/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/loaders/history.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AA4BjD;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA0BpF"}

package/dist/loaders/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Unified loader for various input sources
+ */
+import type { WatchHistoryMeta } from '../types';
+export { loadWatchHistory } from './history';
+export { loadWatchLater } from './watchLater';
+/**
+ * Create metadata entries from video IDs or URLs
+ */
+export declare function fromVideoIds(inputs: string[]): WatchHistoryMeta[];
+/**
+ * Merge multiple sources, deduplicating by video ID
+ * Priority: history > watch_later > manual
+ */
+export declare function mergeVideoSources(...sources: WatchHistoryMeta[][]): WatchHistoryMeta[];
+/**
+ * Load processed video IDs from an existing JSONL file
+ */
+export declare function loadProcessedIds(jsonlPath: string): Promise<Set<string>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/loaders/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/loaders/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAIjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,gBAAgB,EAAE,CAejE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,OAAO,EAAE,gBAAgB,EAAE,EAAE,GAAG,gBAAgB,EAAE,CAYtF;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CA6B9E"}

package/dist/loaders/watchLater.d.ts

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

package/dist/loaders/watchLater.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchLater.d.ts","sourceRoot":"","sources":["../../src/loaders/watchLater.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AA6DjD;;GAEG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAqBlF"}

package/dist/mcp.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * ytranscript MCP Server
+ *
+ * Exposes YouTube transcript extraction as MCP tools for AI assistants
+ */
+export {};
+//# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":";AACA;;;;GAIG"}

package/dist/mcp.js

@@ -28317,6 +28317,7 @@ class StdioServerTransport {
 }
 
 // src/lib/fetcher.ts
+import {createRequire} from "node:module";
 function extractVideoId(input) {
   if (/^[a-zA-Z0-9_-]{11}$/.test(input)) {
     return input;
@@ -28342,9 +28343,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",
@@ -28361,7 +28373,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}`);
@@ -28371,14 +28384,16 @@ async function fetchPlayerResponse(videoId, timeout) {
     clearTimeout(timeoutId);
   }
 }
-async function fetchCaptionTrack(url2, timeout) {
+async function fetchCaptionTrack(url2, timeout, proxy) {
   const controller = new AbortController;
   const timeoutId = setTimeout(() => controller.abort(), timeout);
+  const dispatcher = createProxyAgent(proxy);
   try {
     const jsonUrl = `${url2}&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}`);
@@ -28417,8 +28432,8 @@ function selectCaptionTrack(tracks, preferredLanguages, includeAutoGenerated) {
   return searchOrder[0] || null;
 }
 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");
@@ -28427,7 +28442,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");
   }
@@ -28440,6 +28455,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";
 
 // src/outputs/index.ts

package/dist/outputs/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Output writers for different formats
+ */
+import type { OutputOptions, Transcript, TranscriptResult } from '../types';
+/**
+ * Write results to JSONL format (one JSON object per line)
+ */
+export declare function writeJsonl(results: TranscriptResult[], options: OutputOptions): Promise<void>;
+/**
+ * Append a single result to JSONL file (for streaming)
+ * Uses atomic append to avoid race conditions in concurrent writes
+ */
+export declare function appendJsonl(result: TranscriptResult, path: string): Promise<void>;
+/**
+ * Write results to CSV format
+ */
+export declare function writeCsv(results: TranscriptResult[], options: OutputOptions): Promise<void>;
+/**
+ * Format transcript as SRT subtitle format
+ */
+export declare function formatSrt(transcript: Transcript): string;
+/**
+ * Format transcript as VTT subtitle format
+ */
+export declare function formatVtt(transcript: Transcript): string;
+/**
+ * Format transcript as plain text
+ */
+export declare function formatText(transcript: Transcript, includeTimestamps?: boolean): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/outputs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/outputs/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE5E;;GAEG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,gBAAgB,EAAE,EAC3B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvF;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,gBAAgB,EAAE,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CA2CjG;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,CAcxD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,CAaxD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,UAAU,EAAE,iBAAiB,UAAQ,GAAG,MAAM,CAMpF"}

package/dist/types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Core types for ytranscript
+ */
+/** Proxy configuration for HTTP requests */
+export interface ProxyConfig {
+    /** HTTP proxy URL (e.g., "http://user:pass@host:port") */
+    url: string;
+}
+/** Represents a single transcript segment with timing information */
+export interface TranscriptSegment {
+    /** The text content of this segment */
+    text: string;
+    /** Start time in seconds */
+    start: number;
+    /** Duration in seconds */
+    duration: number;
+}
+/** The complete transcript for a video */
+export interface Transcript {
+    /** Video ID */
+    videoId: string;
+    /** Full transcript text (joined segments) */
+    text: string;
+    /** Individual segments with timestamps */
+    segments: TranscriptSegment[];
+    /** Language code (e.g., 'en', 'es') */
+    language: string;
+    /** Whether this is auto-generated */
+    isAutoGenerated: boolean;
+}
+/** Metadata from Google Takeout watch history */
+export interface WatchHistoryMeta {
+    /** Video ID */
+    videoId: string;
+    /** Video title */
+    title?: string;
+    /** Full YouTube URL */
+    url?: string;
+    /** Channel info */
+    channel?: {
+        name?: string;
+        url?: string;
+    };
+    /** When the video was watched */
+    watchedAt?: string;
+    /** Source of this entry */
+    source: 'history' | 'watch_later' | 'manual';
+}
+/** Result of fetching a transcript */
+export interface TranscriptResult {
+    /** Video metadata */
+    meta: WatchHistoryMeta;
+    /** The transcript (null if failed) */
+    transcript: Transcript | null;
+    /** Error message if fetch failed */
+    error?: string;
+}
+/** Options for fetching transcripts */
+export interface FetchOptions {
+    /** Preferred language codes (in order of preference) */
+    languages?: string[];
+    /** Timeout in milliseconds */
+    timeout?: number;
+    /** Include auto-generated transcripts */
+    includeAutoGenerated?: boolean;
+    /** Proxy configuration for avoiding rate limits */
+    proxy?: ProxyConfig;
+}
+/** Options for bulk processing */
+export interface BulkOptions extends FetchOptions {
+    /** Max concurrent requests */
+    concurrency?: number;
+    /** Pause duration (ms) after N requests */
+    pauseAfter?: number;
+    /** Pause duration in ms */
+    pauseDuration?: number;
+    /** Callback for progress updates */
+    onProgress?: (completed: number, total: number, result: TranscriptResult) => void;
+    /** Set of already-processed video IDs to skip */
+    skipIds?: Set<string>;
+}
+/** Output format types */
+export type OutputFormat = 'json' | 'jsonl' | 'csv' | 'txt' | 'srt' | 'vtt';
+/** Options for output writers */
+export interface OutputOptions {
+    /** Output file path */
+    path: string;
+    /** Whether to append to existing file */
+    append?: boolean;
+    /** Include timestamps in text output */
+    includeTimestamps?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,4CAA4C;AAC5C,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,GAAG,EAAE,MAAM,CAAC;CACb;AAED,qEAAqE;AACrE,MAAM,WAAW,iBAAiB;IAChC,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,0CAA0C;AAC1C,MAAM,WAAW,UAAU;IACzB,eAAe;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,eAAe;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,kBAAkB;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uBAAuB;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mBAAmB;IACnB,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,CAAC;IACF,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2BAA2B;IAC3B,MAAM,EAAE,SAAS,GAAG,aAAa,GAAG,QAAQ,CAAC;CAC9C;AAED,sCAAsC;AACtC,MAAM,WAAW,gBAAgB;IAC/B,qBAAqB;IACrB,IAAI,EAAE,gBAAgB,CAAC;IACvB,sCAAsC;IACtC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,mDAAmD;IACnD,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,kCAAkC;AAClC,MAAM,WAAW,WAAY,SAAQ,YAAY;IAC/C,8BAA8B;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2BAA2B;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAClF,iDAAiD;IACjD,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACvB;AAED,0BAA0B;AAC1B,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAE5E,iCAAiC;AACjC,MAAM,WAAW,aAAa;IAC5B,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wCAAwC;IACxC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B"}

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@nadimtuhin/ytranscript",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "Fast YouTube transcript extraction with bulk processing, Google Takeout support, MCP server, and multiple output formats",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "@nadimtuhin/ytranscript": "dist/cli.js",
     "ytranscript": "dist/cli.js",
     "ytranscript-mcp": "dist/mcp.js"
   },
@@ -17,11 +16,10 @@
       "types": "./dist/index.d.ts"
     }
   },
-  "files": [
-    "dist"
-  ],
+  "files": ["dist"],
   "scripts": {
-    "build": "bun build ./src/index.ts --outdir ./dist --target node && bun build ./src/cli.ts --outdir ./dist --target bun && bun build ./src/mcp.ts --outdir ./dist --target node",
+    "build": "bun build ./src/index.ts --outdir ./dist --target node && bun build ./src/cli.ts --outdir ./dist --target node && bun build ./src/mcp.ts --outdir ./dist --target node && tsc --emitDeclarationOnly --declaration --outDir ./dist",
+    "build:types": "tsc --emitDeclarationOnly --declaration --outDir ./dist",
     "dev": "bun run --watch src/cli.ts",
     "dev:mcp": "bun run --watch src/mcp.ts",
     "test": "bun test",
@@ -58,9 +56,11 @@
     "commander": "^12.1.0",
     "linkedom": "^0.18.0",
     "p-limit": "^6.1.0",
+    "undici": "^7.18.2",
     "zod": "^4.3.5"
   },
   "engines": {
+    "node": ">=18.0.0",
     "bun": ">=1.0.0"
   }
 }