extract-youtube 1.0.2 → 1.0.3

package/src/{formatters.ts → formatters/index.ts}

@@ -2,8 +2,8 @@
  * @fileoverview All formatter classes for transcript formatting
  */
 
-import type { FetchedTranscript } from './models/fetched-transcript';
-import type { FetchedTranscriptSnippet } from './types';
+import type { FetchedTranscript } from '../models/fetched-transcript';
+import type { FetchedTranscriptSnippet } from '../types';
 
 /**
  * Base abstract class for all transcript formatters.
@@ -52,6 +52,83 @@ export class TextFormatter extends Formatter {
   }
 }
 
+/**
+ * Formatter that converts transcripts to article format with character-to-timestamp mappings.
+ * Returns full text as a string along with character position to time pairings.
+ */
+export class ArticleFormatter extends Formatter {
+  formatTranscript(transcript: FetchedTranscript): string {
+    // Build full text content
+    const fullText = transcript.snippets.map(snippet => snippet.text).join(' ');
+
+    // Build timestamp mappings - track which character position corresponds to which time
+    const timestamps: Array<[number, number]> = [];
+    let charPosition = 0;
+
+    for (const snippet of transcript.snippets) {
+      // Record the character position and start time for this snippet
+      timestamps.push([charPosition, snippet.start]);
+      charPosition += snippet.text.length + 1; // +1 for the space separator
+    }
+
+    // Calculate character-per-second speeds at intervals
+    const speedsEveryCharPeriod: { [key: number]: number } = {};
+    const valueCharPeriod = 100;
+
+    for (const [char, time] of timestamps) {
+      const speed = Math.floor(char / time) - 10;
+      speedsEveryCharPeriod[Math.floor(char / valueCharPeriod)] = speed;
+    }
+
+    // Compress the speed data
+    const speeds = Object.keys(speedsEveryCharPeriod).map(
+      (timeKey) => speedsEveryCharPeriod[parseInt(timeKey)]
+    );
+
+    const compressed: number[] = [];
+    const compressedCount: number[] = [];
+    let currentNum = speeds[0];
+    let count = 1;
+
+    for (let i = 1; i < speeds.length; i++) {
+      if (speeds[i] === currentNum) {
+        count++;
+      } else {
+        compressed.push(currentNum);
+        compressedCount.push(count);
+        currentNum = speeds[i];
+        count = 1;
+      }
+    }
+    compressed.push(currentNum);
+    compressedCount.push(count);
+
+    // Convert counts to cumulative positions
+    let total = 0;
+    const cumulativeCounts = compressedCount.map((c) => {
+      total += c;
+      return total;
+    });
+
+    // Format output with speeds and timestamps
+    const speedsData = compressed.join(',') + '  ' + cumulativeCounts.join(',');
+
+    // Remove extra spaces from full text
+    const cleanedText = fullText.replace(/\s+/g, ' ');
+
+    return JSON.stringify({
+      text: cleanedText,
+      timestamps: speedsData,
+      wordCount: cleanedText.split(/\s+/).length,
+      charCount: cleanedText.length
+    }, null, 2);
+  }
+
+  formatTranscripts(transcripts: FetchedTranscript[]): string {
+    return transcripts.map(t => this.formatTranscript(t)).join('\n\n');
+  }
+}
+
 /**
  * Base class for subtitle formatters (SRT, WebVTT).
  */
@@ -132,7 +209,7 @@ export class WebVTTFormatter extends SubtitleFormatterBase {
  */
 export class UnknownFormatterType extends Error {
   constructor(formatterType: string) {
-    super(`Unknown formatter type: ${formatterType}. Available types: json, text, srt, webvtt, pretty`);
+    super(`Unknown formatter type: ${formatterType}. Available types: json, text, srt, webvtt, pretty, article`);
     this.name = 'UnknownFormatterType';
     Object.setPrototypeOf(this, UnknownFormatterType.prototype);
   }
@@ -150,6 +227,8 @@ export class FormatterLoader {
         return new JSONFormatter();
       case 'text':
         return new TextFormatter();
+      case 'article':
+        return new ArticleFormatter();
       case 'srt':
         return new SRTFormatter();
       case 'webvtt':

package/src/http/fetch-http-client.ts

@@ -1,13 +1,13 @@
 /**
- * @fileoverview HTTP client implementation using node-fetch
+ * @fileoverview HTTP client implementation using grab-url
  */
 
-import fetch, { Response, RequestInit } from 'node-fetch';
+import grab from 'grab-url';
 import { HttpsProxyAgent } from 'https-proxy-agent';
 import { HttpClient, RequestsProxyConfigDict } from '../types';
 
 /**
- * Simple HTTP client implementation using node-fetch with proxy support.
+ * Simple HTTP client implementation using grab-url with proxy support.
  * This client handles HTTP/HTTPS requests with configurable headers and proxy settings.
  *
  * @internal
@@ -52,12 +52,12 @@ export class FetchHttpClient implements HttpClient {
    */
   async get(url: string, options?: RequestInit): Promise<Response> {
     const proxyAgent = this.getProxyAgentForUrl(url);
-    return fetch(url, {
+    return grab(url, {
       ...options,
       method: 'GET',
-      headers: { ...this.requestHeaders, ...options?.headers },
+      headers: { ...this.requestHeaders, ...(options?.headers as Record<string, string>) },
       agent: proxyAgent
-    });
+    } as any);
   }
 
   /**
@@ -69,12 +69,12 @@ export class FetchHttpClient implements HttpClient {
    */
   async post(url: string, options?: RequestInit): Promise<Response> {
     const proxyAgent = this.getProxyAgentForUrl(url);
-    return fetch(url, {
+    return grab(url, {
       ...options,
       method: 'POST',
-      headers: { ...this.requestHeaders, ...options?.headers },
+      headers: { ...this.requestHeaders, ...(options?.headers as Record<string, string>) },
       agent: proxyAgent
-    });
+    } as any);
   }
 
   /**

package/src/index.ts

@@ -6,6 +6,9 @@
 // Main API
 export { YouTubeTranscriptApi } from './youtube-transcript-api';
 
+// Transcript utilities
+export { encodeTranscriptSpeeds, getTimestampAtChar, decompressTimestampsArray } from './utils/transcript-utils';
+
 // Transcript model classes
 export {
   FetchedTranscript,
@@ -30,6 +33,7 @@ export {
   JSONFormatter,
   PrettyPrintFormatter,
   TextFormatter,
+  ArticleFormatter,
   SRTFormatter,
   WebVTTFormatter,
   FormatterLoader,

package/src/parsers/transcript-parser.ts

@@ -129,6 +129,10 @@ export class TranscriptParser {
    * @returns {string} The cleaned text
    */
   private cleanTranscriptText(text: string): string {
+    // Ensure text is a string
+    if (typeof text !== 'string') {
+      text = String(text || '');
+    }
     const decodedText = decode(text);
     return decodedText.replace(this.htmlRemovalRegex, '');
   }

package/src/{proxies.ts → proxies/index.ts}

@@ -2,7 +2,7 @@
  * @fileoverview Proxy configuration classes for the YouTube Transcript API
  */
 
-import { RequestsProxyConfigDict } from './types';
+import { RequestsProxyConfigDict } from '../types';
 
 /**
  * Exception for invalid proxy configurations

package/src/{types.ts → types/index.ts}

@@ -2,8 +2,6 @@
  * @fileoverview Type definitions for the YouTube Transcript API
  */
 
-import { Response, RequestInit } from 'node-fetch';
-
 /**
  * Represents a single snippet/cue of a transcript
  */

package/src/utils/http-error-handler.ts

@@ -2,7 +2,6 @@
  * @fileoverview HTTP error handling utilities for YouTube API requests
  */
 
-import { Response } from 'node-fetch';
 import { IpBlocked, YouTubeRequestFailed } from '../errors';
 
 /**

package/src/utils/transcript-utils.ts

@@ -0,0 +1,107 @@
+import { FetchedTranscript } from '../models';
+
+/**
+ * Encodes speech speed from a fetched transcript into a compact run-length string.
+ * Optionally prepends a YouTube embed iframe with data-timestamps for player sync.
+ * @param transcript - A FetchedTranscript returned by fetchTranscript()
+ * @param addPlayer - If true, prepends an iframe embed with data-timestamps attribute
+ * @returns html content, word count, run-length encoded speed string, and raw timestamps
+ */
+export function encodeTranscriptSpeeds(
+  transcript: FetchedTranscript,
+  addPlayer = false
+): {
+  html: string;
+  word_count: number;
+  speeds: string;
+} {
+  let charCount = 0;
+  const timestamps: [number, number][] = [];
+  const textParts: string[] = [];
+
+  for (const snippet of transcript.snippets) {
+    textParts.push(snippet.text);
+    charCount += snippet.text.length;
+    if (snippet.start > 0) {
+      timestamps.push([charCount, snippet.start]);
+    }
+  }
+
+  const content = textParts.join(' ').replace(/\s+/g, ' ');
+  const word_count = content.split(/\s+/).filter(Boolean).length;
+
+  const speedValues = timestamps.map(([char, time]) => Math.floor(char / time) - 10);
+  if (speedValues.length === 0) {
+    return { html: content, word_count, speeds: '' };
+  }
+
+  const compressed: number[] = [];
+  const compressedCount: number[] = [];
+  let currentNum = speedValues[0];
+  let count = 1;
+
+  for (let i = 1; i < speedValues.length; i++) {
+    if (speedValues[i] === currentNum) {
+      count++;
+    } else {
+      compressed.push(currentNum);
+      compressedCount.push(count);
+      currentNum = speedValues[i];
+      count = 1;
+    }
+  }
+  compressed.push(currentNum);
+  compressedCount.push(count);
+
+  const speeds = compressed.map((val, i) => `${val}x${compressedCount[i]}`).join(',');
+
+  const html = addPlayer
+    ? `<iframe width="100%" height="315px" data-timestamps="${speeds}" ` +
+      `src="https://www.youtube.com/embed/${transcript.videoId}" frameborder="0" ` +
+      `allow="accelerometer; autoplay; clipboard-write; encrypted-media; ` +
+      `gyroscope; picture-in-picture" allowfullscreen></iframe>${content}`
+    : content;
+
+  return { html, word_count, speeds };
+}
+
+/**
+ * Given a character index in the joined transcript text, returns the interpolated
+ * video timestamp in seconds. Uses the nearest snippet boundaries to interpolate.
+ */
+export function getTimestampAtChar(transcript: FetchedTranscript, charIndex: number): number {
+  let charCount = 0;
+  const points: [number, number][] = [[0, 0]]; // [cumulativeChars, seconds]
+
+  for (const snippet of transcript.snippets) {
+    charCount += snippet.text.length + 1; // +1 for the join space
+    points.push([charCount, snippet.start]);
+  }
+
+  if (charIndex <= 0) return 0;
+  if (charIndex >= points[points.length - 1][0]) return points[points.length - 1][1];
+
+  for (let i = 1; i < points.length; i++) {
+    if (points[i][0] >= charIndex) {
+      const [c0, t0] = points[i - 1];
+      const [c1, t1] = points[i];
+      const ratio = (charIndex - c0) / (c1 - c0);
+      return t0 + ratio * (t1 - t0);
+    }
+  }
+
+  return points[points.length - 1][1];
+}
+
+/**
+ * Decompresses a speeds string produced by encodeTranscriptSpeeds back into a flat array.
+ * Format: "12x3,8x7,15x1" → [12,12,12, 8,8,8,8,8,8,8, 15]
+ */
+export function decompressTimestampsArray(speeds: string): number[] {
+  const decompressed: number[] = [];
+  for (const part of speeds.split(',')) {
+    const [num, count] = part.split('x');
+    decompressed.push(...Array(parseInt(count)).fill(parseInt(num)));
+  }
+  return decompressed;
+}

package/tsconfig.json

@@ -2,7 +2,7 @@
   "compilerOptions": {
     "target": "ES2020",
     "module": "commonjs",
-    "lib": ["ES2020"],
+    "lib": ["ES2020", "DOM"],
     "outDir": "./dist",
     "rootDir": "./src",
     "declaration": true,
@@ -12,9 +12,9 @@
     "esModuleInterop": true,
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
-    "moduleResolution": "node",
-    "resolveJsonModule": true
+    "resolveJsonModule": true,
+    "types": ["node"]
   },
-  "include": ["src/**/*", "__tests__"],
-  "exclude": ["node_modules", "dist", "src/**/*.test.ts", "__tests__"]
+  "include": ["src/**/*", "test"],
+  "exclude": ["node_modules", "dist", "src/**/*.test.ts", "test"]
 }

package/tsconfig.test.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "types": ["node", "jest"],
+    "noEmit": true
+  },
+  "include": ["src/**/*", "test/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/vite.config.ts

@@ -10,6 +10,8 @@ const buildCli = process.env.BUILD_CLI === 'true';
 
 export default defineConfig({
   build: {
+    // Don't empty output dir for CLI build to preserve library files
+    emptyOutDir: !buildCli,
     lib: buildCli ? {
       entry: resolve(__dirname, 'src/cli.ts'),
       name: 'ExtractYoutubeCli',
@@ -22,9 +24,12 @@ export default defineConfig({
       fileName: (format) => `index.${format === 'es' ? 'mjs' : 'cjs'}`,
     },
     rollupOptions: {
-      // Externalize dependencies to avoid bundling them
+      // Externalize dependencies to avoid bundling them.
+      // grab-url is deliberately bundled: its published CJS entry resolves
+      // its internal chunks relative to the consumer's cwd and fails to load
+      // under require(); bundling its ESM source avoids the broken entry.
       external: [
-        ...Object.keys(pkg.dependencies || {}),
+        ...Object.keys(pkg.dependencies || {}).filter((d) => d !== 'grab-url'),
         'node:http',
         'node:https',
         'node:url',
@@ -38,7 +43,7 @@ export default defineConfig({
         exports: 'named',
         // Provide global names for UMD/IIFE builds
         globals: {
-          'node-fetch': 'fetch',
+          'grab-url': 'grab',
           'fast-xml-parser': 'XMLParser',
           'html-entities': 'htmlEntities',
           'https-proxy-agent': 'HttpsProxyAgent',

package/CHANGELOG.md

@@ -1 +0,0 @@
-