extract-youtube 1.0.1

package/src/fetchers/youtube-data-extractor.ts

@@ -0,0 +1,151 @@
+/**
+ * @fileoverview Utilities for extracting data from YouTube HTML and InnerTube API responses
+ */
+
+import {
+  InnerTubeData,
+  CaptionsJson,
+  PlayabilityStatus,
+  PlayabilityFailedReason
+} from '../types';
+import {
+  IpBlocked,
+  YouTubeDataUnparsable,
+  TranscriptsDisabled,
+  RequestBlocked,
+  AgeRestricted,
+  VideoUnavailable,
+  InvalidVideoId,
+  VideoUnplayable
+} from '../errors';
+
+/**
+ * Extracts the InnerTube API key from YouTube's HTML page.
+ *
+ * @param {string} htmlContent - The HTML content from YouTube's watch page
+ * @param {string} videoId - The video ID being processed
+ * @returns {string} The extracted API key
+ * @throws {IpBlocked} If the page contains a reCAPTCHA (IP is blocked)
+ * @throws {YouTubeDataUnparsable} If the API key cannot be found
+ *
+ * @example
+ * ```typescript
+ * const html = await fetchVideoHtml(videoId);
+ * const apiKey = extractInnertubeApiKey(html, videoId);
+ * ```
+ */
+export function extractInnertubeApiKey(htmlContent: string, videoId: string): string {
+  const apiKeyPattern = /"INNERTUBE_API_KEY":\s*"([a-zA-Z0-9_-]+)"/;
+  const match = htmlContent.match(apiKeyPattern);
+
+  if (match && match.length === 2) {
+    return match[1];
+  }
+
+  // Check if IP is blocked (reCAPTCHA present)
+  if (htmlContent.includes('class="g-recaptcha"')) {
+    throw new IpBlocked(videoId);
+  }
+
+  throw new YouTubeDataUnparsable(videoId);
+}
+
+/**
+ * Extracts captions JSON from YouTube's InnerTube API response.
+ *
+ * @param {InnerTubeData} innertubeData - The InnerTube API response data
+ * @param {string} videoId - The video ID being processed
+ * @returns {CaptionsJson} The extracted captions data
+ * @throws {TranscriptsDisabled} If captions are disabled for the video
+ *
+ * @example
+ * ```typescript
+ * const innertubeData = await fetchInnertubeData(videoId, apiKey);
+ * const captionsJson = extractCaptionsJson(innertubeData, videoId);
+ * ```
+ */
+export function extractCaptionsJson(innertubeData: InnerTubeData, videoId: string): CaptionsJson {
+  validatePlayabilityStatus(innertubeData.playabilityStatus, videoId);
+
+  const captionsJson = innertubeData.captions?.playerCaptionsTracklistRenderer;
+
+  if (!captionsJson || !captionsJson.captionTracks) {
+    throw new TranscriptsDisabled(videoId);
+  }
+
+  return captionsJson;
+}
+
+/**
+ * Validates the playability status of a video and throws appropriate errors.
+ *
+ * @param {any} playabilityStatusData - The playability status data from InnerTube
+ * @param {string} videoId - The video ID being validated
+ * @throws {RequestBlocked} If YouTube detected a bot
+ * @throws {AgeRestricted} If the video is age-restricted
+ * @throws {VideoUnavailable} If the video is unavailable
+ * @throws {InvalidVideoId} If the video ID is invalid (URL was provided instead)
+ * @throws {VideoUnplayable} If the video is unplayable for any other reason
+ *
+ * @example
+ * ```typescript
+ * validatePlayabilityStatus(innertubeData.playabilityStatus, videoId);
+ * ```
+ */
+export function validatePlayabilityStatus(playabilityStatusData: any, videoId: string): void {
+  if (!playabilityStatusData) {
+    return;
+  }
+
+  const playabilityStatus = playabilityStatusData.status;
+
+  // If status is OK, video is playable
+  if (playabilityStatus === PlayabilityStatus.OK || !playabilityStatus) {
+    return;
+  }
+
+  const reason = playabilityStatusData.reason;
+
+  // Handle LOGIN_REQUIRED status
+  if (playabilityStatus === PlayabilityStatus.LOGIN_REQUIRED) {
+    if (reason === PlayabilityFailedReason.BOT_DETECTED) {
+      throw new RequestBlocked(videoId);
+    }
+    if (reason === PlayabilityFailedReason.AGE_RESTRICTED) {
+      throw new AgeRestricted(videoId);
+    }
+  }
+
+  // Handle ERROR status
+  if (playabilityStatus === PlayabilityStatus.ERROR && reason === PlayabilityFailedReason.VIDEO_UNAVAILABLE) {
+    // Check if user provided a URL instead of video ID
+    if (videoId.startsWith('http://') || videoId.startsWith('https://')) {
+      throw new InvalidVideoId(videoId);
+    }
+    throw new VideoUnavailable(videoId);
+  }
+
+  // Extract additional sub-reasons if available
+  const subReasons = extractPlayabilitySubreasons(playabilityStatusData);
+
+  throw new VideoUnplayable(videoId, reason, subReasons);
+}
+
+/**
+ * Extracts sub-reasons from the playability status error screen.
+ *
+ * @private
+ * @param {any} playabilityStatusData - The playability status data
+ * @returns {string[]} Array of sub-reason messages
+ */
+function extractPlayabilitySubreasons(playabilityStatusData: any): string[] {
+  const runs = playabilityStatusData.errorScreen?.playerErrorMessageRenderer?.subreason?.runs;
+
+  if (!runs || !Array.isArray(runs)) {
+    return [];
+  }
+
+  return runs
+    .map((run: any) => run.text || '')
+    .filter((text: string) => text.length > 0);
+}

package/src/formatters.ts

@@ -0,0 +1,163 @@
+/**
+ * @fileoverview All formatter classes for transcript formatting
+ */
+
+import type { FetchedTranscript } from './models/fetched-transcript';
+import type { FetchedTranscriptSnippet } from './types';
+
+/**
+ * Base abstract class for all transcript formatters.
+ */
+export abstract class Formatter {
+  abstract formatTranscript(transcript: FetchedTranscript, options?: any): string;
+  abstract formatTranscripts(transcripts: FetchedTranscript[], options?: any): string;
+}
+
+/**
+ * Formatter that converts transcripts to pretty-printed JSON format.
+ */
+export class PrettyPrintFormatter extends Formatter {
+  formatTranscript(transcript: FetchedTranscript): string {
+    return JSON.stringify(transcript.toRawData(), null, 2);
+  }
+
+  formatTranscripts(transcripts: FetchedTranscript[]): string {
+    return JSON.stringify(transcripts.map(t => t.toRawData()), null, 2);
+  }
+}
+
+/**
+ * Formatter that converts transcripts to JSON format.
+ */
+export class JSONFormatter extends Formatter {
+  formatTranscript(transcript: FetchedTranscript, options?: { indent?: number }): string {
+    return JSON.stringify(transcript.toRawData(), null, options?.indent);
+  }
+
+  formatTranscripts(transcripts: FetchedTranscript[], options?: { indent?: number }): string {
+    return JSON.stringify(transcripts.map(t => t.toRawData()), null, options?.indent);
+  }
+}
+
+/**
+ * Formatter that converts transcripts to plain text format with no timestamps.
+ */
+export class TextFormatter extends Formatter {
+  formatTranscript(transcript: FetchedTranscript): string {
+    return transcript.snippets.map(snippet => snippet.text).join('\n');
+  }
+
+  formatTranscripts(transcripts: FetchedTranscript[]): string {
+    return transcripts.map(t => this.formatTranscript(t)).join('\n\n\n');
+  }
+}
+
+/**
+ * Base class for subtitle formatters (SRT, WebVTT).
+ */
+abstract class SubtitleFormatterBase extends TextFormatter {
+  protected abstract formatTimestamp(h: number, m: number, s: number, ms: number): string;
+  protected abstract formatTranscriptHeader(lines: string[]): string;
+  protected abstract formatSubtitleEntry(index: number, timeRange: string, snippet: FetchedTranscriptSnippet): string;
+
+  protected secondsToTimestamp(timeInSeconds: number): string {
+    const hours = Math.floor(timeInSeconds / 3600);
+    const remainder = timeInSeconds % 3600;
+    const minutes = Math.floor(remainder / 60);
+    const seconds = Math.floor(remainder % 60);
+    const milliseconds = Math.round((timeInSeconds - Math.floor(timeInSeconds)) * 1000);
+
+    return this.formatTimestamp(hours, minutes, seconds, milliseconds);
+  }
+
+  formatTranscript(transcript: FetchedTranscript): string {
+    const formattedLines: string[] = [];
+
+    for (let i = 0; i < transcript.snippets.length; i++) {
+      const snippet = transcript.snippets[i];
+      const snippetEndTime = snippet.start + snippet.duration;
+
+      const actualEndTime =
+        i < transcript.snippets.length - 1 && transcript.snippets[i + 1].start < snippetEndTime
+          ? transcript.snippets[i + 1].start
+          : snippetEndTime;
+
+      const timeRangeText = `${this.secondsToTimestamp(snippet.start)} --> ${this.secondsToTimestamp(actualEndTime)}`;
+
+      formattedLines.push(this.formatSubtitleEntry(i, timeRangeText, snippet));
+    }
+
+    return this.formatTranscriptHeader(formattedLines);
+  }
+}
+
+/**
+ * Formatter that converts transcripts to SRT (SubRip) format.
+ */
+export class SRTFormatter extends SubtitleFormatterBase {
+  protected formatTimestamp(h: number, m: number, s: number, ms: number): string {
+    const pad = (n: number, w: number) => n.toString().padStart(w, '0');
+    return `${pad(h, 2)}:${pad(m, 2)}:${pad(s, 2)},${pad(ms, 3)}`;
+  }
+
+  protected formatTranscriptHeader(lines: string[]): string {
+    return lines.join('\n\n') + '\n';
+  }
+
+  protected formatSubtitleEntry(index: number, timeRange: string, snippet: FetchedTranscriptSnippet): string {
+    return `${index + 1}\n${timeRange}\n${snippet.text}`;
+  }
+}
+
+/**
+ * Formatter that converts transcripts to WebVTT format.
+ */
+export class WebVTTFormatter extends SubtitleFormatterBase {
+  protected formatTimestamp(h: number, m: number, s: number, ms: number): string {
+    const pad = (n: number, w: number) => n.toString().padStart(w, '0');
+    return `${pad(h, 2)}:${pad(m, 2)}:${pad(s, 2)}.${pad(ms, 3)}`;
+  }
+
+  protected formatTranscriptHeader(lines: string[]): string {
+    return 'WEBVTT\n\n' + lines.join('\n\n') + '\n';
+  }
+
+  protected formatSubtitleEntry(index: number, timeRange: string, snippet: FetchedTranscriptSnippet): string {
+    return `${timeRange}\n${snippet.text}`;
+  }
+}
+
+/**
+ * Raised when an unknown formatter type is requested.
+ */
+export class UnknownFormatterType extends Error {
+  constructor(formatterType: string) {
+    super(`Unknown formatter type: ${formatterType}. Available types: json, text, srt, webvtt, pretty`);
+    this.name = 'UnknownFormatterType';
+    Object.setPrototypeOf(this, UnknownFormatterType.prototype);
+  }
+}
+
+/**
+ * Utility class for loading formatters by type string.
+ */
+export class FormatterLoader {
+  load(formatterType?: string): Formatter {
+    const type = formatterType?.toLowerCase() || 'pretty';
+
+    switch (type) {
+      case 'json':
+        return new JSONFormatter();
+      case 'text':
+        return new TextFormatter();
+      case 'srt':
+        return new SRTFormatter();
+      case 'webvtt':
+        return new WebVTTFormatter();
+      case 'pretty':
+        return new PrettyPrintFormatter();
+      default:
+        throw new UnknownFormatterType(type);
+    }
+  }
+}

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

@@ -0,0 +1,102 @@
+/**
+ * @fileoverview HTTP client implementation using node-fetch
+ */
+
+import fetch, { Response, RequestInit } from 'node-fetch';
+import { HttpsProxyAgent } from 'https-proxy-agent';
+import { HttpClient, RequestsProxyConfigDict } from '../types';
+
+/**
+ * Simple HTTP client implementation using node-fetch with proxy support.
+ * This client handles HTTP/HTTPS requests with configurable headers and proxy settings.
+ *
+ * @internal
+ */
+export class FetchHttpClient implements HttpClient {
+  private requestHeaders: Record<string, string> = {};
+  private proxyConfiguration: Partial<RequestsProxyConfigDict> = {};
+
+  /**
+   * Creates a new FetchHttpClient instance.
+   * Sets default Accept-Language header to English.
+   */
+  constructor() {
+    this.requestHeaders['Accept-Language'] = 'en-US';
+  }
+
+  /**
+   * Sets a custom header for all requests.
+   *
+   * @param {string} headerName - The header name
+   * @param {string} headerValue - The header value
+   */
+  setHeader(headerName: string, headerValue: string): void {
+    this.requestHeaders[headerName] = headerValue;
+  }
+
+  /**
+   * Configures proxy settings for all requests.
+   *
+   * @param {RequestsProxyConfigDict} proxies - Proxy configuration dictionary
+   */
+  setProxies(proxies: RequestsProxyConfigDict): void {
+    this.proxyConfiguration = proxies;
+  }
+
+  /**
+   * Performs an HTTP GET request.
+   *
+   * @param {string} url - The URL to request
+   * @param {RequestInit} [options] - Additional request options
+   * @returns {Promise<Response>} The HTTP response
+   */
+  async get(url: string, options?: RequestInit): Promise<Response> {
+    const proxyAgent = this.getProxyAgentForUrl(url);
+    return fetch(url, {
+      ...options,
+      method: 'GET',
+      headers: { ...this.requestHeaders, ...options?.headers },
+      agent: proxyAgent
+    });
+  }
+
+  /**
+   * Performs an HTTP POST request.
+   *
+   * @param {string} url - The URL to request
+   * @param {RequestInit} [options] - Additional request options
+   * @returns {Promise<Response>} The HTTP response
+   */
+  async post(url: string, options?: RequestInit): Promise<Response> {
+    const proxyAgent = this.getProxyAgentForUrl(url);
+    return fetch(url, {
+      ...options,
+      method: 'POST',
+      headers: { ...this.requestHeaders, ...options?.headers },
+      agent: proxyAgent
+    });
+  }
+
+  /**
+   * Gets the appropriate proxy agent for a given URL.
+   *
+   * @private
+   * @param {string} url - The URL being requested
+   * @returns {any} The proxy agent or undefined if no proxy is configured
+   */
+  private getProxyAgentForUrl(url: string): any {
+    if (Object.keys(this.proxyConfiguration).length === 0) {
+      return undefined;
+    }
+
+    const proxyUrl = url.startsWith('https://')
+      ? this.proxyConfiguration.https
+      : this.proxyConfiguration.http;
+
+    if (!proxyUrl) {
+      return undefined;
+    }
+
+    return new HttpsProxyAgent(proxyUrl);
+  }
+}

package/src/index.ts

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview YouTube Transcript API - A Node.js/TypeScript API to retrieve YouTube video transcripts/subtitles
+ * @module youtube-transcript-api
+ */
+
+// Main API
+export { YouTubeTranscriptApi } from './youtube-transcript-api';
+
+// Transcript model classes
+export {
+  FetchedTranscript,
+  Transcript,
+  TranscriptList
+} from './models';
+
+// Fetcher classes
+export { TranscriptListFetcher } from './fetchers/transcript-list-fetcher';
+
+// Proxy configurations
+export {
+  ProxyConfig,
+  GenericProxyConfig,
+  WebshareProxyConfig,
+  InvalidProxyConfig
+} from './proxies';
+
+// Formatters
+export {
+  Formatter,
+  JSONFormatter,
+  PrettyPrintFormatter,
+  TextFormatter,
+  SRTFormatter,
+  WebVTTFormatter,
+  FormatterLoader,
+  UnknownFormatterType
+} from './formatters';
+
+// Error classes
+export {
+  YouTubeTranscriptApiException,
+  CookieError,
+  CookiePathInvalid,
+  CookieInvalid,
+  CouldNotRetrieveTranscript,
+  YouTubeDataUnparsable,
+  YouTubeRequestFailed,
+  VideoUnplayable,
+  VideoUnavailable,
+  InvalidVideoId,
+  RequestBlocked,
+  IpBlocked,
+  TranscriptsDisabled,
+  AgeRestricted,
+  NotTranslatable,
+  TranslationLanguageNotAvailable,
+  FailedToCreateConsentCookie,
+  NoTranscriptFound,
+  PoTokenRequired
+} from './errors';
+
+// Type definitions (enums only - interfaces are type-only and exported via .d.ts)
+export {
+  PlayabilityStatus,
+  PlayabilityFailedReason
+} from './types';
+
+// Re-export types for TypeScript consumers (these are type-only exports)
+export type {
+  FetchedTranscriptSnippet,
+  TranslationLanguage,
+  RequestsProxyConfigDict,
+  CaptionTrack,
+  CaptionsJson,
+  InnerTubeData,
+  HttpClient
+} from './types';

package/src/models/fetched-transcript.ts

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview FetchedTranscript model representing a complete transcript with all snippets
+ */
+
+import { FetchedTranscriptSnippet } from '../types';
+
+/**
+ * Represents a fetched transcript with all its snippets and metadata.
+ * This class is iterable, allowing you to iterate over transcript snippets.
+ *
+ * @example
+ * ```typescript
+ * const transcript = await api.fetch('video_id');
+ * for (const snippet of transcript) {
+ *   console.log(snippet.text);
+ * }
+ * ```
+ */
+export class FetchedTranscript implements Iterable<FetchedTranscriptSnippet> {
+  /** Array of transcript snippets */
+  public readonly snippets: FetchedTranscriptSnippet[];
+
+  /** The video ID this transcript belongs to */
+  public readonly videoId: string;
+
+  /** The language name (e.g., "English") */
+  public readonly language: string;
+
+  /** The language code (e.g., "en") */
+  public readonly languageCode: string;
+
+  /** Whether this transcript was automatically generated */
+  public readonly isGenerated: boolean;
+
+  /**
+   * Creates a new FetchedTranscript instance.
+   *
+   * @param {FetchedTranscriptSnippet[]} snippets - Array of transcript snippets
+   * @param {string} videoId - The video ID
+   * @param {string} language - The language name
+   * @param {string} languageCode - The language code
+   * @param {boolean} isGenerated - Whether the transcript is auto-generated
+   */
+  constructor(
+    snippets: FetchedTranscriptSnippet[],
+    videoId: string,
+    language: string,
+    languageCode: string,
+    isGenerated: boolean
+  ) {
+    this.snippets = snippets;
+    this.videoId = videoId;
+    this.language = language;
+    this.languageCode = languageCode;
+    this.isGenerated = isGenerated;
+  }
+
+  /**
+   * Makes the transcript iterable, allowing for...of loops.
+   *
+   * @returns {Iterator<FetchedTranscriptSnippet>} Iterator over the snippets
+   */
+  [Symbol.iterator](): Iterator<FetchedTranscriptSnippet> {
+    return this.snippets[Symbol.iterator]();
+  }
+
+  /**
+   * Gets a snippet by index.
+   *
+   * @param {number} index - The index of the snippet
+   * @returns {FetchedTranscriptSnippet} The snippet at the given index
+   */
+  getSnippetAtIndex(index: number): FetchedTranscriptSnippet {
+    return this.snippets[index];
+  }
+
+  /**
+   * Alias for getSnippetAtIndex() for backward compatibility.
+   *
+   * @deprecated Use getSnippetAtIndex() instead
+   * @param {number} index - The index of the snippet
+   * @returns {FetchedTranscriptSnippet} The snippet at the given index
+   */
+  get(index: number): FetchedTranscriptSnippet {
+    return this.getSnippetAtIndex(index);
+  }
+
+  /**
+   * Gets the total number of snippets in the transcript.
+   *
+   * @returns {number} The number of snippets
+   */
+  get length(): number {
+    return this.snippets.length;
+  }
+
+  /**
+   * Converts the transcript to raw data format (array of objects).
+   * This is useful for serialization or when you need plain data objects.
+   *
+   * @returns {Array<{text: string, start: number, duration: number}>} Raw transcript data
+   */
+  toRawData(): Array<{ text: string; start: number; duration: number }> {
+    return this.snippets.map(snippet => ({
+      text: snippet.text,
+      start: snippet.start,
+      duration: snippet.duration
+    }));
+  }
+}

package/src/models/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Central export point for all model classes
+ */
+
+export { FetchedTranscript } from './fetched-transcript';
+export { Transcript } from './transcript';
+export { TranscriptList } from './transcript-list';