youtube-transcript-plus 1.2.0 → 2.0.0

package/README.md

@@ -6,6 +6,10 @@ A Node.js library to fetch transcripts from YouTube videos. This package uses Yo
 
 **Note:** This project was originally forked from [https://github.com/Kakulukian/youtube-transcript](https://github.com/Kakulukian/youtube-transcript).
 
+## Requirements
+
+- Node.js >= 20.0.0 (Node 20.x reaches EOL in September 2026)
+
 ## Installation
 
 ```bash
@@ -167,6 +171,90 @@ fetchTranscript('videoId_or_URL', {
   .catch(console.error);
 ```
 
+### List Available Languages
+
+Discover what caption languages are available for a video without downloading transcript data.
+
+```javascript
+import { listLanguages } from 'youtube-transcript-plus';
+
+const languages = await listLanguages('videoId_or_URL');
+// [
+//   { languageCode: 'en', languageName: 'English', isAutoGenerated: false },
+//   { languageCode: 'es', languageName: 'Spanish', isAutoGenerated: true },
+// ]
+```
+
+### Transcript Format Output
+
+Convert transcript segments to common subtitle formats or plain text.
+
+```javascript
+import { fetchTranscript, toSRT, toVTT, toPlainText } from 'youtube-transcript-plus';
+
+const transcript = await fetchTranscript('videoId_or_URL');
+
+// SubRip format (.srt)
+const srt = toSRT(transcript);
+
+// WebVTT format (.vtt)
+const vtt = toVTT(transcript);
+
+// Plain text (one line per segment)
+const text = toPlainText(transcript);
+
+// Plain text with custom separator
+const paragraph = toPlainText(transcript, ' ');
+```
+
+### Video Details
+
+Opt in to receive video metadata alongside the transcript. This uses data already present in the API response, so it adds zero additional HTTP requests.
+
+```javascript
+import { fetchTranscript } from 'youtube-transcript-plus';
+
+const result = await fetchTranscript('videoId_or_URL', {
+  videoDetails: true,
+});
+
+console.log(result.videoDetails.title);
+console.log(result.videoDetails.author);
+console.log(result.videoDetails.lengthSeconds);
+console.log(result.videoDetails.viewCount);
+console.log(result.segments); // TranscriptSegment[]
+```
+
+### Retry with Exponential Backoff
+
+Automatically retry on transient failures (429 rate-limit and 5xx server errors) with exponential backoff.
+
+```javascript
+fetchTranscript('videoId_or_URL', {
+  retries: 3, // Retry up to 3 times
+  retryDelay: 1000, // Start with 1 second delay (doubles each retry)
+})
+  .then(console.log)
+  .catch(console.error);
+```
+
+### AbortController Support
+
+Cancel in-flight requests using an `AbortSignal`.
+
+```javascript
+const controller = new AbortController();
+
+// Cancel the request after 5 seconds
+setTimeout(() => controller.abort(), 5000);
+
+fetchTranscript('videoId_or_URL', {
+  signal: controller.signal,
+})
+  .then(console.log)
+  .catch(console.error);
+```
+
 ### Error Handling
 
 The library throws specific errors for different failure scenarios. Each error includes a `videoId` property for programmatic handling.
@@ -177,6 +265,7 @@ import {
   YoutubeTranscriptDisabledError,
   YoutubeTranscriptNotAvailableError,
   YoutubeTranscriptNotAvailableLanguageError,
+  YoutubeTranscriptInvalidLangError,
 } from 'youtube-transcript-plus';
 
 fetchTranscript('videoId_or_URL')
@@ -190,6 +279,8 @@ fetchTranscript('videoId_or_URL')
       console.error('No transcript available:', error.videoId);
     } else if (error instanceof YoutubeTranscriptNotAvailableLanguageError) {
       console.error('Language not available:', error.lang, error.availableLangs);
+    } else if (error instanceof YoutubeTranscriptInvalidLangError) {
+      console.error('Invalid language code:', error.lang);
     } else {
       console.error('An unexpected error occurred:', error.message);
     }
@@ -206,6 +297,11 @@ The repository includes several example files in the `example/` directory to dem
 4. **`language-usage.js`**: Shows how to fetch a transcript in a specific language (e.g., French).
 5. **`proxy-usage.js`**: Demonstrates how to use a proxy server to fetch transcripts, which can be useful for bypassing rate limits or accessing restricted content.
 6. **`custom-fetch-usage.js`**: Shows how to use all three custom fetch functions (`videoFetch`, `playerFetch`, `transcriptFetch`) with logging and custom headers.
+7. **`list-languages-usage.js`**: Shows how to discover available caption languages for a video.
+8. **`format-output-usage.js`**: Demonstrates converting transcripts to SRT, VTT, and plain text formats.
+9. **`video-details-usage.js`**: Shows how to fetch video metadata alongside the transcript.
+10. **`retry-usage.js`**: Demonstrates retry with exponential backoff for transient failures.
+11. **`abort-usage.js`**: Shows how to cancel requests using an AbortController with a timeout.
 
 These examples can be found in the `example/` directory of the repository.
 
@@ -214,10 +310,21 @@ These examples can be found in the `example/` directory of the repository.
 All types are exported for TypeScript consumers:
 
 ```typescript
-import type { TranscriptConfig, TranscriptResponse, FetchParams, CacheStrategy } from 'youtube-transcript-plus';
+import type {
+  TranscriptConfig,
+  TranscriptSegment,
+  TranscriptResult,
+  VideoDetails,
+  Thumbnail,
+  CaptionTrackInfo,
+  FetchParams,
+  CacheStrategy,
+} from 'youtube-transcript-plus';
 ```
 
-### API
+> **Note:** `TranscriptResponse` is still available as a deprecated alias for `TranscriptSegment`.
+
+## API
 
 ### `fetchTranscript(videoId: string, config?: TranscriptConfig)`
 
@@ -225,21 +332,55 @@ Fetches the transcript for a YouTube video.
 
 - **`videoId`**: The YouTube video ID or URL.
 - **`config`**: Optional configuration object with the following properties:
-  - **`lang`**: Language code (e.g., `'en'`, `'fr'`) for the transcript.
+  - **`lang`**: BCP 47 language code (e.g., `'en'`, `'fr'`, `'pt-BR'`) for the transcript.
   - **`userAgent`**: Custom User-Agent string.
-  - **`cache`**: Custom caching strategy.
+  - **`cache`**: Custom caching strategy implementing `CacheStrategy`.
   - **`cacheTTL`**: Time-to-live for cache entries in milliseconds.
   - **`disableHttps`**: Set to `true` to use HTTP instead of HTTPS for YouTube requests.
   - **`videoFetch`**: Custom fetch function for the video page request (GET).
   - **`playerFetch`**: Custom fetch function for the YouTube Innertube API request (POST).
   - **`transcriptFetch`**: Custom fetch function for the transcript data request (GET).
+  - **`retries`**: Maximum number of retry attempts for transient failures (429, 5xx). Defaults to `0`.
+  - **`retryDelay`**: Base delay in milliseconds for exponential backoff. Defaults to `1000`.
+  - **`signal`**: `AbortSignal` to cancel in-flight requests.
+  - **`videoDetails`**: When `true`, returns a `TranscriptResult` with video metadata instead of a plain array.
 
-Returns a `Promise<TranscriptResponse[]>` where each item in the array represents a transcript segment with the following properties:
+Returns a `Promise<TranscriptSegment[]>` where each item represents a transcript segment:
 
-- **`text`**: The text of the transcript segment.
+- **`text`**: The text content of the segment.
 - **`duration`**: The duration of the segment in seconds.
 - **`offset`**: The start time of the segment in seconds.
-- **`lang`**: The language of the transcript.
+- **`lang`**: The language code of the transcript.
+
+When `videoDetails: true` is set, returns a `Promise<TranscriptResult>`:
+
+- **`videoDetails`**: A `VideoDetails` object with `title`, `author`, `channelId`, `lengthSeconds`, `viewCount`, `description`, `keywords`, `thumbnails`, and `isLiveContent`.
+- **`segments`**: An array of `TranscriptSegment` objects.
+
+### `listLanguages(videoId: string, config?: TranscriptConfig)`
+
+Lists available caption languages for a video without downloading transcript data.
+
+- **`videoId`**: The YouTube video ID or URL.
+- **`config`**: Optional configuration (same options as `fetchTranscript`, except `videoDetails`).
+
+Returns a `Promise<CaptionTrackInfo[]>`:
+
+- **`languageCode`**: BCP 47 language code (e.g., `'en'`, `'fr'`).
+- **`languageName`**: Human-readable language name (e.g., `'English'`).
+- **`isAutoGenerated`**: Whether the captions are auto-generated by YouTube.
+
+### `toSRT(segments: TranscriptSegment[])`
+
+Converts transcript segments to SubRip (SRT) format with sequence numbers and `HH:MM:SS,mmm` timestamps.
+
+### `toVTT(segments: TranscriptSegment[])`
+
+Converts transcript segments to WebVTT format with `WEBVTT` header and `HH:MM:SS.mmm` timestamps.
+
+### `toPlainText(segments: TranscriptSegment[], separator?: string)`
+
+Converts transcript segments to plain text, joined by the given separator (defaults to `'\n'`).
 
 ## Errors
 
@@ -251,6 +392,11 @@ The library throws the following errors:
 - **`YoutubeTranscriptNotAvailableLanguageError`**: The transcript is not available in the specified language. Properties: `videoId`, `lang`, `availableLangs`.
 - **`YoutubeTranscriptTooManyRequestError`**: YouTube is rate-limiting requests from your IP.
 - **`YoutubeTranscriptInvalidVideoIdError`**: The provided video ID or URL is invalid.
+- **`YoutubeTranscriptInvalidLangError`**: The provided language code is not a valid BCP 47 code. Properties: `lang`.
+
+## Feature Requests
+
+Have a feature idea? [Open an issue](https://github.com/ericmmartin/youtube-transcript-plus/issues/new) and let us know!
 
 ## License
 

package/dist/cache/fs-cache.d.ts

@@ -1,8 +1,26 @@
 import { CacheStrategy } from '../types';
+/**
+ * File-system-based cache implementation.
+ *
+ * Each entry is stored as a JSON file in the specified directory.
+ * Expired entries are automatically deleted when accessed.
+ *
+ * @example
+ * ```typescript
+ * import { fetchTranscript, FsCache } from 'youtube-transcript-plus';
+ * const transcript = await fetchTranscript('dQw4w9WgXcQ', {
+ *   cache: new FsCache('./my-cache-dir', 86400000), // 1 day TTL
+ * });
+ * ```
+ */
 export declare class FsCache implements CacheStrategy {
     private cacheDir;
     private defaultTTL;
     private ready;
+    /**
+     * @param cacheDir - Directory to store cache files. Created automatically if it doesn't exist.
+     * @param defaultTTL - Default time-to-live in milliseconds. Defaults to 1 hour.
+     */
     constructor(cacheDir?: string, defaultTTL?: number);
     get(key: string): Promise<string | null>;
     set(key: string, value: string, ttl?: number): Promise<void>;

package/dist/cache/in-memory-cache.d.ts

@@ -1,7 +1,21 @@
 import { CacheStrategy } from '../types';
+/**
+ * In-memory cache implementation using a `Map`.
+ *
+ * Entries are automatically cleaned up when accessed after expiration.
+ *
+ * @example
+ * ```typescript
+ * import { fetchTranscript, InMemoryCache } from 'youtube-transcript-plus';
+ * const transcript = await fetchTranscript('dQw4w9WgXcQ', {
+ *   cache: new InMemoryCache(1800000), // 30 minutes TTL
+ * });
+ * ```
+ */
 export declare class InMemoryCache implements CacheStrategy {
     private cache;
     private defaultTTL;
+    /** @param defaultTTL - Default time-to-live in milliseconds. Defaults to 1 hour. */
     constructor(defaultTTL?: number);
     get(key: string): Promise<string | null>;
     set(key: string, value: string, ttl?: number): Promise<void>;

package/dist/errors.d.ts

@@ -1,24 +1,38 @@
+/** Thrown when YouTube is rate-limiting requests from your IP address. */
 export declare class YoutubeTranscriptTooManyRequestError extends Error {
     constructor();
 }
+/** Thrown when the requested video is unavailable or has been removed. */
 export declare class YoutubeTranscriptVideoUnavailableError extends Error {
     readonly videoId: string;
     constructor(videoId: string);
 }
+/** Thrown when transcripts are disabled for the video by its owner. */
 export declare class YoutubeTranscriptDisabledError extends Error {
     readonly videoId: string;
     constructor(videoId: string);
 }
+/** Thrown when no transcripts are available for the video. */
 export declare class YoutubeTranscriptNotAvailableError extends Error {
     readonly videoId: string;
     constructor(videoId: string);
 }
+/** Thrown when the transcript is not available in the requested language. */
 export declare class YoutubeTranscriptNotAvailableLanguageError extends Error {
     readonly videoId: string;
+    /** The requested language code that was not available. */
     readonly lang: string;
+    /** The language codes that are available for this video. */
     readonly availableLangs: string[];
     constructor(lang: string, availableLangs: string[], videoId: string);
 }
+/** Thrown when the provided `lang` option is not a valid BCP 47 language code. */
+export declare class YoutubeTranscriptInvalidLangError extends Error {
+    /** The invalid language code that was provided. */
+    readonly lang: string;
+    constructor(lang: string);
+}
+/** Thrown when the provided video ID or URL is invalid. */
 export declare class YoutubeTranscriptInvalidVideoIdError extends Error {
     constructor();
 }

package/dist/formatters.d.ts

@@ -0,0 +1,57 @@
+import { TranscriptSegment } from './types';
+/**
+ * Convert transcript segments to SubRip (SRT) format.
+ *
+ * @param segments - Array of transcript segments from {@link fetchTranscript}.
+ * @returns A string in SRT format with sequence numbers and `HH:MM:SS,mmm` timestamps.
+ *
+ * @example
+ * ```typescript
+ * import { fetchTranscript, toSRT } from 'youtube-transcript-plus';
+ * const transcript = await fetchTranscript('dQw4w9WgXcQ');
+ * const srt = toSRT(transcript);
+ *
+ * // With videoDetails enabled, use result.segments:
+ * const result = await fetchTranscript('dQw4w9WgXcQ', { videoDetails: true });
+ * const srt2 = toSRT(result.segments);
+ * ```
+ */
+export declare function toSRT(segments: TranscriptSegment[]): string;
+/**
+ * Convert transcript segments to WebVTT (VTT) format.
+ *
+ * @param segments - Array of transcript segments from {@link fetchTranscript}.
+ * @returns A string in VTT format with `WEBVTT` header and `HH:MM:SS.mmm` timestamps.
+ *
+ * @example
+ * ```typescript
+ * import { fetchTranscript, toVTT } from 'youtube-transcript-plus';
+ * const transcript = await fetchTranscript('dQw4w9WgXcQ');
+ * const vtt = toVTT(transcript);
+ *
+ * // With videoDetails enabled, use result.segments:
+ * const result = await fetchTranscript('dQw4w9WgXcQ', { videoDetails: true });
+ * const vtt2 = toVTT(result.segments);
+ * ```
+ */
+export declare function toVTT(segments: TranscriptSegment[]): string;
+/**
+ * Convert transcript segments to plain text.
+ *
+ * @param segments - Array of transcript segments from {@link fetchTranscript}.
+ * @param separator - String to join segments with. Defaults to `'\n'`.
+ * @returns A plain text string with segments joined by the separator.
+ *
+ * @example
+ * ```typescript
+ * import { fetchTranscript, toPlainText } from 'youtube-transcript-plus';
+ * const transcript = await fetchTranscript('dQw4w9WgXcQ');
+ * const text = toPlainText(transcript);
+ * const paragraph = toPlainText(transcript, ' ');
+ *
+ * // With videoDetails enabled, use result.segments:
+ * const result = await fetchTranscript('dQw4w9WgXcQ', { videoDetails: true });
+ * const text2 = toPlainText(result.segments);
+ * ```
+ */
+export declare function toPlainText(segments: TranscriptSegment[], separator?: string): string;

package/dist/index.d.ts

@@ -1,17 +1,148 @@
-import { TranscriptConfig, TranscriptResponse } from './types';
+import { TranscriptConfig, TranscriptSegment, TranscriptResult, CaptionTrackInfo } from './types';
 /**
- * Implementation notes:
- * - Keeps the public surface identical.
- * - Internals now use YouTube Innertube `player` to discover captionTracks instead of scraping the watch HTML.
- * - Honors `lang`, custom fetch hooks (`videoFetch`, `transcriptFetch`), and optional cache strategy.
+ * Fetches YouTube video transcripts and caption metadata using the Innertube API.
+ *
+ * Can be used as an instance (with shared config) or via static/convenience methods.
+ *
+ * @example
+ * ```typescript
+ * // Instance usage with shared config
+ * const yt = new YoutubeTranscript({ lang: 'en' });
+ * const transcript = await yt.fetchTranscript('dQw4w9WgXcQ');
+ * const languages = await yt.listLanguages('dQw4w9WgXcQ');
+ *
+ * // Static method
+ * const transcript = await YoutubeTranscript.fetchTranscript('dQw4w9WgXcQ', { lang: 'en' });
+ *
+ * // Opt-in to video details
+ * const { videoDetails, segments } = await YoutubeTranscript.fetchTranscript('dQw4w9WgXcQ', {
+ *   videoDetails: true,
+ * });
+ *
+ * // Convenience export
+ * const transcript = await fetchTranscript('dQw4w9WgXcQ');
+ * const languages = await listLanguages('dQw4w9WgXcQ');
+ * ```
  */
 export declare class YoutubeTranscript {
     private config?;
-    constructor(config?: TranscriptConfig);
-    fetchTranscript(videoId: string): Promise<TranscriptResponse[]>;
-    static fetchTranscript(videoId: string, config?: TranscriptConfig): Promise<TranscriptResponse[]>;
+    constructor(config?: TranscriptConfig | undefined);
+    /**
+     * Fetch caption tracks and the player response from the Innertube player API.
+     * Shared logic used by both fetchTranscript and listLanguages.
+     */
+    private _fetchCaptionTracks;
+    /**
+     * Extract VideoDetails from the Innertube player response.
+     */
+    private _extractVideoDetails;
+    /**
+     * Fetch the transcript for a YouTube video.
+     *
+     * When `videoDetails` is set to `true` in the config, returns a {@link TranscriptResult}
+     * containing both video metadata and transcript segments. Otherwise returns an array of
+     * {@link TranscriptSegment} objects.
+     *
+     * **Note:** The instance method returns a union type because `videoDetails` is set at
+     * construction time. For automatic type narrowing, use the static method or the
+     * `fetchTranscript` convenience export instead.
+     *
+     * @param videoId - A YouTube video ID (11 characters) or full YouTube URL.
+     * @returns An array of transcript segments, or a TranscriptResult if `videoDetails` is enabled.
+     * @throws {@link YoutubeTranscriptInvalidVideoIdError} if the video ID/URL is invalid.
+     * @throws {@link YoutubeTranscriptVideoUnavailableError} if the video is unavailable.
+     * @throws {@link YoutubeTranscriptDisabledError} if transcripts are disabled.
+     * @throws {@link YoutubeTranscriptNotAvailableError} if no transcript is available.
+     * @throws {@link YoutubeTranscriptNotAvailableLanguageError} if the requested language is unavailable.
+     * @throws {@link YoutubeTranscriptTooManyRequestError} if rate-limited by YouTube.
+     */
+    fetchTranscript(videoId: string): Promise<TranscriptSegment[] | TranscriptResult>;
+    /**
+     * List available caption languages for a YouTube video.
+     *
+     * Queries the Innertube player API to discover what caption tracks exist,
+     * without downloading any transcript data.
+     *
+     * @param videoId - A YouTube video ID (11 characters) or full YouTube URL.
+     * @returns An array of available caption track info objects.
+     * @throws {@link YoutubeTranscriptInvalidVideoIdError} if the video ID/URL is invalid.
+     * @throws {@link YoutubeTranscriptVideoUnavailableError} if the video is unavailable.
+     * @throws {@link YoutubeTranscriptDisabledError} if transcripts are disabled.
+     * @throws {@link YoutubeTranscriptNotAvailableError} if no captions are available.
+     * @throws {@link YoutubeTranscriptTooManyRequestError} if rate-limited by YouTube.
+     *
+     * @example
+     * ```typescript
+     * const yt = new YoutubeTranscript();
+     * const languages = await yt.listLanguages('dQw4w9WgXcQ');
+     * // [
+     * //   { languageCode: 'en', languageName: 'English', isAutoGenerated: false },
+     * //   { languageCode: 'es', languageName: 'Spanish (auto-generated)', isAutoGenerated: true },
+     * // ]
+     * ```
+     */
+    listLanguages(videoId: string): Promise<CaptionTrackInfo[]>;
+    /**
+     * Static convenience method to fetch a transcript without creating an instance.
+     *
+     * @param videoId - A YouTube video ID (11 characters) or full YouTube URL.
+     * @param config - Optional configuration options.
+     * @returns An array of transcript segments, or a {@link TranscriptResult} when `videoDetails: true`.
+     */
+    static fetchTranscript(videoId: string): Promise<TranscriptSegment[]>;
+    static fetchTranscript(videoId: string, config: TranscriptConfig & {
+        videoDetails: true;
+    }): Promise<TranscriptResult>;
+    static fetchTranscript(videoId: string, config: TranscriptConfig): Promise<TranscriptSegment[]>;
+    /**
+     * Static convenience method to list available caption languages without creating an instance.
+     *
+     * @param videoId - A YouTube video ID (11 characters) or full YouTube URL.
+     * @param config - Optional configuration options.
+     * @returns An array of available caption track info objects.
+     */
+    static listLanguages(videoId: string, config?: TranscriptConfig): Promise<CaptionTrackInfo[]>;
 }
-export type { CacheStrategy, TranscriptConfig, TranscriptResponse, FetchParams } from './types';
+export type { CacheStrategy, CaptionTrackInfo, Thumbnail, TranscriptConfig, TranscriptResponse, TranscriptResult, TranscriptSegment, VideoDetails, FetchParams, } from './types';
 export { InMemoryCache, FsCache } from './cache';
+export { toSRT, toVTT, toPlainText } from './formatters';
 export * from './errors';
-export declare const fetchTranscript: typeof YoutubeTranscript.fetchTranscript;
+/**
+ * Convenience function to fetch a YouTube video transcript.
+ *
+ * @param videoId - A YouTube video ID (11 characters) or full YouTube URL.
+ * @param config - Optional configuration options.
+ * @returns An array of transcript segments, or a {@link TranscriptResult} when `videoDetails: true`.
+ *
+ * @example
+ * ```typescript
+ * import { fetchTranscript } from 'youtube-transcript-plus';
+ *
+ * // Returns TranscriptSegment[]
+ * const transcript = await fetchTranscript('dQw4w9WgXcQ');
+ *
+ * // Returns TranscriptResult with video details
+ * const { videoDetails, segments } = await fetchTranscript('dQw4w9WgXcQ', {
+ *   videoDetails: true,
+ * });
+ * ```
+ */
+export declare function fetchTranscript(videoId: string): Promise<TranscriptSegment[]>;
+export declare function fetchTranscript(videoId: string, config: TranscriptConfig & {
+    videoDetails: true;
+}): Promise<TranscriptResult>;
+export declare function fetchTranscript(videoId: string, config: TranscriptConfig): Promise<TranscriptSegment[]>;
+/**
+ * Convenience function to list available caption languages for a YouTube video.
+ *
+ * @param videoId - A YouTube video ID (11 characters) or full YouTube URL.
+ * @param config - Optional configuration options.
+ * @returns An array of available caption track info objects.
+ *
+ * @example
+ * ```typescript
+ * import { listLanguages } from 'youtube-transcript-plus';
+ * const languages = await listLanguages('dQw4w9WgXcQ');
+ * ```
+ */
+export declare const listLanguages: typeof YoutubeTranscript.listLanguages;