extract-youtube 1.0.1

package/src/models/transcript-list.ts

@@ -0,0 +1,252 @@
+/**
+ * @fileoverview TranscriptList model representing all available transcripts for a video
+ */
+
+import { HttpClient, TranslationLanguage, CaptionsJson } from '../types';
+import { Transcript } from './transcript';
+import { NoTranscriptFound } from '../errors';
+
+/**
+ * Represents a list of available transcripts for a video.
+ * This object is iterable and provides methods to search for specific transcripts.
+ *
+ * @example
+ * ```typescript
+ * const transcriptList = await api.list('video_id');
+ *
+ * // Iterate over all transcripts
+ * for (const transcript of transcriptList) {
+ *   console.log(transcript.language, transcript.languageCode);
+ * }
+ *
+ * // Find a specific transcript
+ * const transcript = transcriptList.findTranscript(['de', 'en']);
+ * ```
+ */
+export class TranscriptList implements Iterable<Transcript> {
+  /** The video ID this list belongs to */
+  public readonly videoId: string;
+
+  private manuallyCreatedTranscripts: Record<string, Transcript>;
+  private autoGeneratedTranscripts: Record<string, Transcript>;
+  private availableTranslationLanguages: TranslationLanguage[];
+
+  /**
+   * Creates a new TranscriptList instance.
+   * The constructor is only for internal use. Use the static buildFromCaptionsJson method instead.
+   *
+   * @param {string} videoId - The video ID
+   * @param {Record<string, Transcript>} manuallyCreatedTranscripts - Map of manually created transcripts
+   * @param {Record<string, Transcript>} autoGeneratedTranscripts - Map of auto-generated transcripts
+   * @param {TranslationLanguage[]} availableTranslationLanguages - Available translation languages
+   */
+  constructor(
+    videoId: string,
+    manuallyCreatedTranscripts: Record<string, Transcript>,
+    autoGeneratedTranscripts: Record<string, Transcript>,
+    availableTranslationLanguages: TranslationLanguage[]
+  ) {
+    this.videoId = videoId;
+    this.manuallyCreatedTranscripts = manuallyCreatedTranscripts;
+    this.autoGeneratedTranscripts = autoGeneratedTranscripts;
+    this.availableTranslationLanguages = availableTranslationLanguages;
+  }
+
+  /**
+   * Factory method to build a TranscriptList from YouTube's captions JSON data.
+   *
+   * @param {HttpClient} httpClient - HTTP client for making requests
+   * @param {string} videoId - The video ID
+   * @param {CaptionsJson} captionsJson - The JSON parsed from YouTube's response
+   * @returns {TranscriptList} The created TranscriptList
+   */
+  static buildFromCaptionsJson(
+    httpClient: HttpClient,
+    videoId: string,
+    captionsJson: CaptionsJson
+  ): TranscriptList {
+    const translationLanguages = TranscriptList.extractTranslationLanguages(captionsJson);
+    const { manualTranscripts, generatedTranscripts } = TranscriptList.categorizeTranscripts(
+      httpClient,
+      videoId,
+      captionsJson,
+      translationLanguages
+    );
+
+    return new TranscriptList(videoId, manualTranscripts, generatedTranscripts, translationLanguages);
+  }
+
+  /**
+   * Extracts translation languages from the captions JSON.
+   *
+   * @private
+   * @param {CaptionsJson} captionsJson - The captions JSON data
+   * @returns {TranslationLanguage[]} Array of translation languages
+   */
+  private static extractTranslationLanguages(captionsJson: CaptionsJson): TranslationLanguage[] {
+    return (captionsJson.translationLanguages || []).map(lang => ({
+      language: lang.languageName.runs[0].text,
+      language_code: lang.languageCode
+    }));
+  }
+
+  /**
+   * Categorizes transcripts into manually created and auto-generated.
+   *
+   * @private
+   * @param {HttpClient} httpClient - HTTP client for making requests
+   * @param {string} videoId - The video ID
+   * @param {CaptionsJson} captionsJson - The captions JSON data
+   * @param {TranslationLanguage[]} translationLanguages - Available translation languages
+   * @returns {{manualTranscripts: Record<string, Transcript>, generatedTranscripts: Record<string, Transcript>}}
+   */
+  private static categorizeTranscripts(
+    httpClient: HttpClient,
+    videoId: string,
+    captionsJson: CaptionsJson,
+    translationLanguages: TranslationLanguage[]
+  ): {
+    manualTranscripts: Record<string, Transcript>;
+    generatedTranscripts: Record<string, Transcript>;
+  } {
+    const manualTranscripts: Record<string, Transcript> = {};
+    const generatedTranscripts: Record<string, Transcript> = {};
+
+    for (const captionTrack of captionsJson.captionTracks) {
+      const isAutoGenerated = captionTrack.kind === 'asr';
+      const targetMap = isAutoGenerated ? generatedTranscripts : manualTranscripts;
+
+      // Remove format parameter from URL for better compatibility
+      const cleanedUrl = captionTrack.baseUrl.replace('&fmt=srv3', '');
+
+      const transcript = new Transcript(
+        httpClient,
+        videoId,
+        cleanedUrl,
+        captionTrack.name.runs[0].text,
+        captionTrack.languageCode,
+        isAutoGenerated,
+        captionTrack.isTranslatable ? translationLanguages : []
+      );
+
+      targetMap[captionTrack.languageCode] = transcript;
+    }
+
+    return { manualTranscripts, generatedTranscripts };
+  }
+
+  /**
+   * Makes the transcript list iterable, allowing for...of loops.
+   * Manual transcripts are yielded first, followed by auto-generated transcripts.
+   *
+   * @returns {Iterator<Transcript>} Iterator over all transcripts
+   */
+  [Symbol.iterator](): Iterator<Transcript> {
+    const manualTranscripts = Object.values(this.manuallyCreatedTranscripts);
+    const generatedTranscripts = Object.values(this.autoGeneratedTranscripts);
+    return [...manualTranscripts, ...generatedTranscripts][Symbol.iterator]();
+  }
+
+  /**
+   * Finds a transcript for given language codes. Manually created transcripts are
+   * returned first and only if none are found, auto-generated transcripts are used.
+   *
+   * @param {string[]} languageCodes - A list of language codes in descending priority
+   * @returns {Transcript} The found transcript
+   * @throws {NoTranscriptFound} If no transcript is found for any of the language codes
+   *
+   * @example
+   * ```typescript
+   * // Try German first, then English
+   * const transcript = transcriptList.findTranscript(['de', 'en']);
+   * ```
+   */
+  findTranscript(languageCodes: string[]): Transcript {
+    return this.findTranscriptInMaps(languageCodes, [
+      this.manuallyCreatedTranscripts,
+      this.autoGeneratedTranscripts
+    ]);
+  }
+
+  /**
+   * Finds an automatically generated transcript for given language codes.
+   *
+   * @param {string[]} languageCodes - A list of language codes in descending priority
+   * @returns {Transcript} The found auto-generated transcript
+   * @throws {NoTranscriptFound} If no auto-generated transcript is found
+   *
+   * @example
+   * ```typescript
+   * const transcript = transcriptList.findGeneratedTranscript(['en']);
+   * ```
+   */
+  findGeneratedTranscript(languageCodes: string[]): Transcript {
+    return this.findTranscriptInMaps(languageCodes, [this.autoGeneratedTranscripts]);
+  }
+
+  /**
+   * Finds a manually created transcript for given language codes.
+   *
+   * @param {string[]} languageCodes - A list of language codes in descending priority
+   * @returns {Transcript} The found manually created transcript
+   * @throws {NoTranscriptFound} If no manually created transcript is found
+   *
+   * @example
+   * ```typescript
+   * const transcript = transcriptList.findManuallyCreatedTranscript(['en']);
+   * ```
+   */
+  findManuallyCreatedTranscript(languageCodes: string[]): Transcript {
+    return this.findTranscriptInMaps(languageCodes, [this.manuallyCreatedTranscripts]);
+  }
+
+  /**
+   * Internal method to find a transcript by searching through provided maps.
+   *
+   * @private
+   * @param {string[]} languageCodes - Language codes to search for
+   * @param {Record<string, Transcript>[]} transcriptMaps - Maps to search through
+   * @returns {Transcript} The found transcript
+   * @throws {NoTranscriptFound} If no transcript is found
+   */
+  private findTranscriptInMaps(
+    languageCodes: string[],
+    transcriptMaps: Record<string, Transcript>[]
+  ): Transcript {
+    for (const languageCode of languageCodes) {
+      for (const transcriptMap of transcriptMaps) {
+        if (languageCode in transcriptMap) {
+          return transcriptMap[languageCode];
+        }
+      }
+    }
+
+    throw new NoTranscriptFound(this.videoId, languageCodes, this);
+  }
+
+  /**
+   * Returns a formatted string representation of all available transcripts.
+   *
+   * @returns {string} A formatted string showing all available transcripts
+   */
+  toString(): string {
+    const formatTranscriptMap = (transcripts: Record<string, Transcript>): string => {
+      const descriptions = Object.values(transcripts).map(t => ` - ${t.toString()}`);
+      return descriptions.length > 0 ? descriptions.join('\n') : 'None';
+    };
+
+    const formatTranslationLanguages = (): string => {
+      const descriptions = this.availableTranslationLanguages.map(
+        lang => ` - ${lang.language_code} ("${lang.language}")`
+      );
+      return descriptions.length > 0 ? descriptions.join('\n') : 'None';
+    };
+
+    return (
+      `For this video (${this.videoId}) transcripts are available in the following languages:\n\n` +
+      `(MANUALLY CREATED)\n${formatTranscriptMap(this.manuallyCreatedTranscripts)}\n\n` +
+      `(GENERATED)\n${formatTranscriptMap(this.autoGeneratedTranscripts)}\n\n` +
+      `(TRANSLATION LANGUAGES)\n${formatTranslationLanguages()}`
+    );
+  }
+}

package/src/models/transcript.ts

@@ -0,0 +1,187 @@
+/**
+ * @fileoverview Transcript model representing a single transcript that can be fetched or translated
+ */
+
+import { HttpClient, TranslationLanguage } from '../types';
+import { NotTranslatable, TranslationLanguageNotAvailable, PoTokenRequired } from '../errors';
+import { FetchedTranscript } from './fetched-transcript';
+import { TranscriptParser } from '../parsers/transcript-parser';
+import { handleHttpErrors } from '../utils/http-error-handler';
+
+/**
+ * Represents a transcript that can be fetched or translated.
+ * You typically obtain Transcript objects from a TranscriptList.
+ *
+ * @example
+ * ```typescript
+ * const transcriptList = await api.list('video_id');
+ * const transcript = transcriptList.findTranscript(['en']);
+ * const fetched = await transcript.fetch();
+ * ```
+ */
+export class Transcript {
+  private httpClient: HttpClient;
+
+  /** The video ID this transcript belongs to */
+  public readonly videoId: string;
+
+  private transcriptUrl: 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;
+
+  /** Available translation languages */
+  public readonly translationLanguages: TranslationLanguage[];
+
+  private translationLanguagesMap: Record<string, string>;
+
+  /**
+   * Creates a new Transcript instance.
+   * You probably don't want to initialize this directly.
+   * Usually you'll access Transcript objects using a TranscriptList.
+   *
+   * @param {HttpClient} httpClient - HTTP client for making requests
+   * @param {string} videoId - The video ID
+   * @param {string} transcriptUrl - The transcript URL
+   * @param {string} language - The language name
+   * @param {string} languageCode - The language code
+   * @param {boolean} isGenerated - Whether the transcript is auto-generated
+   * @param {TranslationLanguage[]} translationLanguages - Available translation languages
+   */
+  constructor(
+    httpClient: HttpClient,
+    videoId: string,
+    transcriptUrl: string,
+    language: string,
+    languageCode: string,
+    isGenerated: boolean,
+    translationLanguages: TranslationLanguage[]
+  ) {
+    this.httpClient = httpClient;
+    this.videoId = videoId;
+    this.transcriptUrl = transcriptUrl;
+    this.language = language;
+    this.languageCode = languageCode;
+    this.isGenerated = isGenerated;
+    this.translationLanguages = translationLanguages;
+    this.translationLanguagesMap = this.buildTranslationLanguagesMap(translationLanguages);
+  }
+
+  /**
+   * Builds a map of language codes to language names for quick lookup.
+   *
+   * @private
+   * @param {TranslationLanguage[]} languages - Array of translation languages
+   * @returns {Record<string, string>} Map of language code to language name
+   */
+  private buildTranslationLanguagesMap(languages: TranslationLanguage[]): Record<string, string> {
+    const map: Record<string, string> = {};
+    for (const lang of languages) {
+      map[lang.language_code] = lang.language;
+    }
+    return map;
+  }
+
+  /**
+   * Loads the actual transcript data from YouTube.
+   *
+   * @param {boolean} [preserveFormatting=false] - Whether to keep select HTML text formatting
+   * @returns {Promise<FetchedTranscript>} The fetched transcript with all snippets
+   * @throws {PoTokenRequired} If a PO Token is required for this video
+   * @throws {YouTubeRequestFailed} If the HTTP request fails
+   *
+   * @example
+   * ```typescript
+   * const transcript = transcriptList.findTranscript(['en']);
+   * const fetched = await transcript.fetch();
+   *
+   * // With formatting preserved
+   * const fetchedWithFormatting = await transcript.fetch(true);
+   * ```
+   */
+  async fetch(preserveFormatting: boolean = false): Promise<FetchedTranscript> {
+    if (this.transcriptUrl.includes('&exp=xpe')) {
+      throw new PoTokenRequired(this.videoId);
+    }
+
+    const response = await this.httpClient.get(this.transcriptUrl);
+    handleHttpErrors(response, this.videoId);
+
+    const xmlData = await response.text();
+    const parser = new TranscriptParser(preserveFormatting);
+    const snippets = parser.parseTranscriptXml(xmlData);
+
+    return new FetchedTranscript(
+      snippets,
+      this.videoId,
+      this.language,
+      this.languageCode,
+      this.isGenerated
+    );
+  }
+
+  /**
+   * Checks whether this transcript can be translated to other languages.
+   *
+   * @returns {boolean} True if the transcript supports translation
+   */
+  get isTranslatable(): boolean {
+    return this.translationLanguages.length > 0;
+  }
+
+  /**
+   * Creates a translated version of this transcript.
+   *
+   * @param {string} targetLanguageCode - The target language code (e.g., 'de', 'fr')
+   * @returns {Transcript} A new Transcript object for the translated transcript
+   * @throws {NotTranslatable} If the transcript cannot be translated
+   * @throws {TranslationLanguageNotAvailable} If the requested language is not available
+   *
+   * @example
+   * ```typescript
+   * const englishTranscript = transcriptList.findTranscript(['en']);
+   * if (englishTranscript.isTranslatable) {
+   *   const germanTranscript = englishTranscript.translate('de');
+   *   const fetched = await germanTranscript.fetch();
+   * }
+   * ```
+   */
+  translate(targetLanguageCode: string): Transcript {
+    if (!this.isTranslatable) {
+      throw new NotTranslatable(this.videoId);
+    }
+
+    if (!(targetLanguageCode in this.translationLanguagesMap)) {
+      throw new TranslationLanguageNotAvailable(this.videoId);
+    }
+
+    const translatedUrl = `${this.transcriptUrl}&tlang=${targetLanguageCode}`;
+    const translatedLanguage = this.translationLanguagesMap[targetLanguageCode];
+
+    return new Transcript(
+      this.httpClient,
+      this.videoId,
+      translatedUrl,
+      translatedLanguage,
+      targetLanguageCode,
+      true,
+      [] // Translated transcripts cannot be translated again
+    );
+  }
+
+  /**
+   * Returns a string representation of the transcript.
+   *
+   * @returns {string} A formatted string representation
+   */
+  toString(): string {
+    const translatableFlag = this.isTranslatable ? '[TRANSLATABLE]' : '';
+    return `${this.languageCode} ("${this.language}")${translatableFlag}`;
+  }
+}

package/src/parsers/transcript-parser.ts

@@ -0,0 +1,135 @@
+/**
+ * @fileoverview Parser for converting YouTube transcript XML data into structured snippets
+ */
+
+import { XMLParser } from 'fast-xml-parser';
+import { decode } from 'html-entities';
+import { FetchedTranscriptSnippet } from '../types';
+
+/**
+ * Parses transcript XML data from YouTube into FetchedTranscriptSnippet objects.
+ *
+ * @example
+ * ```typescript
+ * const parser = new TranscriptParser(false);
+ * const snippets = parser.parseTranscriptXml(xmlData);
+ * ```
+ */
+export class TranscriptParser {
+  /**
+   * HTML formatting tags that can be preserved in transcript text.
+   * These are common formatting tags that provide semantic meaning.
+   */
+  private static readonly FORMATTING_TAGS = [
+    'strong',  // Bold text
+    'em',      // Emphasized text
+    'b',       // Bold text (alternative)
+    'i',       // Italic text
+    'mark',    // Marked/highlighted text
+    'small',   // Small text
+    'del',     // Deleted text
+    'ins',     // Inserted text
+    'sub',     // Subscript
+    'sup'      // Superscript
+  ];
+
+  private htmlRemovalRegex: RegExp;
+
+  /**
+   * Creates a new TranscriptParser instance.
+   *
+   * @param {boolean} [preserveFormatting=false] - Whether to preserve HTML formatting tags
+   */
+  constructor(preserveFormatting: boolean = false) {
+    this.htmlRemovalRegex = this.buildHtmlRemovalRegex(preserveFormatting);
+  }
+
+  /**
+   * Builds a regex pattern for removing HTML tags based on formatting preferences.
+   *
+   * @private
+   * @param {boolean} preserveFormatting - Whether to preserve formatting tags
+   * @returns {RegExp} The HTML removal regex
+   */
+  private buildHtmlRemovalRegex(preserveFormatting: boolean): RegExp {
+    if (preserveFormatting) {
+      // Create a regex that removes all tags EXCEPT the formatting tags
+      const formattingTagsPattern = TranscriptParser.FORMATTING_TAGS.join('|');
+      const pattern = `<\\/?(?!\\/?(?:${formattingTagsPattern})\\b).*?\\b>`;
+      return new RegExp(pattern, 'gi');
+    } else {
+      // Remove all HTML tags
+      return /<[^>]*>/gi;
+    }
+  }
+
+  /**
+   * Parses raw XML transcript data into an array of transcript snippets.
+   *
+   * @param {string} xmlData - The raw XML data from YouTube's transcript API
+   * @returns {FetchedTranscriptSnippet[]} Array of parsed transcript snippets
+   *
+   * @example
+   * ```typescript
+   * const parser = new TranscriptParser();
+   * const snippets = parser.parseTranscriptXml(xmlData);
+   * for (const snippet of snippets) {
+   *   console.log(`${snippet.start}s: ${snippet.text}`);
+   * }
+   * ```
+   */
+  parseTranscriptXml(xmlData: string): FetchedTranscriptSnippet[] {
+    const parser = new XMLParser({
+      ignoreAttributes: false,
+      attributeNamePrefix: '@_'
+    });
+
+    const parsedXml = parser.parse(xmlData);
+    const textElements = parsedXml.transcript?.text || [];
+
+    // Ensure textElements is always an array (XMLParser returns single object if only one element)
+    const elementsArray = Array.isArray(textElements) ? textElements : [textElements];
+
+    return elementsArray
+      .filter(element => element['#text'])
+      .map(element => this.parseTranscriptSnippet(element));
+  }
+
+  /**
+   * Parses a single XML element into a FetchedTranscriptSnippet.
+   *
+   * @private
+   * @param {any} element - The XML element to parse
+   * @returns {FetchedTranscriptSnippet} The parsed snippet
+   */
+  private parseTranscriptSnippet(element: any): FetchedTranscriptSnippet {
+    return {
+      text: this.cleanTranscriptText(element['#text']),
+      start: this.parseFloatAttribute(element['@_start']),
+      duration: this.parseFloatAttribute(element['@_dur'])
+    };
+  }
+
+  /**
+   * Parses a string attribute as a float, defaulting to 0 if invalid.
+   *
+   * @private
+   * @param {string | undefined} value - The attribute value to parse
+   * @returns {number} The parsed float value
+   */
+  private parseFloatAttribute(value: string | undefined): number {
+    return parseFloat(value || '0');
+  }
+
+  /**
+   * Cleans transcript text by decoding HTML entities and removing HTML tags.
+   *
+   * @private
+   * @param {string} text - The raw transcript text
+   * @returns {string} The cleaned text
+   */
+  private cleanTranscriptText(text: string): string {
+    const decodedText = decode(text);
+    return decodedText.replace(this.htmlRemovalRegex, '');
+  }
+}