youtube-transcript-plus

The library supports caching to avoid redundant requests. You can use built-in strategies or implement the CacheStrategy interface.

Built-in: In-Memory Cache

Use InMemoryCache for transient, memory-based caching.

Built-in: File System Cache

Use FsCache to persist cache to a directory.

Custom Cache

Implement the get and set methods of the CacheStrategy interface.

import { fetchTranscript, InMemoryCache, FsCache, CacheStrategy } from 'youtube-transcript-plus';

// In-Memory
fetchTranscript('videoId', { cache: new InMemoryCache(1800000) });

// File System
fetchTranscript('videoId', { cache: new FsCache('./my-cache-dir', 86400000) });

// Custom
class CustomCache implements CacheStrategy {
  async get(key: string): Promise<string | null> { /* ... */ }
  async set(key: string, value: string, ttl?: number): Promise<void> { /* ... */ }
}
fetchTranscript('videoId', { cache: new CustomCache() });

The fetchTranscript function accepts an optional TranscriptConfig object to customize the request behavior:

Use fetchTranscript(videoId, config) to retrieve the transcript for a specific YouTube video.

By default, it returns an array of TranscriptSegment objects. If you set videoDetails: true in the configuration, it returns a TranscriptResult object containing both the video metadata and the transcript segments.

TranscriptSegment properties:

• text: The text content.
• duration: Duration in seconds.
• offset: Start time in seconds.
• lang: Language code.

TranscriptResult properties (when videoDetails: true):

• videoDetails: Object containing title, author, channelId, lengthSeconds, viewCount, description, keywords, thumbnails, and isLiveContent.
• segments: Array of TranscriptSegment objects.

// Basic usage returning segments
const segments = await fetchTranscript('VIDEO_ID');

// Usage with video metadata
const result = await fetchTranscript('VIDEO_ID', { videoDetails: true });
console.log(result.videoDetails.title);

You can override the internal HTTP request logic by providing custom implementations for the three types of requests the library makes. This is useful for using proxies or custom headers.

1. videoFetch: Fetches the YouTube video page (GET).
2. playerFetch: Calls YouTube's Innertube API to get caption tracks (POST).
3. transcriptFetch: Downloads the actual transcript data (GET).

fetchTranscript('videoId_or_URL', {
  videoFetch: async ({ url, lang, userAgent }) => {
    return fetch(`https://my-proxy-server.com/?url=${encodeURIComponent(url)}`, {
      headers: {
        ...(lang && { 'Accept-Language': lang }),
        'User-Agent': userAgent,
      },
    });
  },
  playerFetch: async ({ url, method, body, headers, lang, userAgent }) => {
    return fetch(`https://my-proxy-server.com/?url=${encodeURIComponent(url)}`, {
      method,
      headers: {
        ...(lang && { 'Accept-Language': lang }),
        'User-Agent': userAgent,
        ...headers,
      },
      body,
    });
  },
  transcriptFetch: async ({ url, lang, userAgent }) => {
    return fetch(`https://my-proxy-server.com/?url=${encodeURIComponent(url)}`, {
      headers: {
        ...(lang && { 'Accept-Language': lang }),
        'User-Agent': userAgent,
      },
    });
  },
})
  .then(console.log)
  .catch(console.error);

The TranscriptConfig object allows you to customize the behavior of the transcript fetching process. You can control language preferences, user agents, caching, and even provide custom fetch implementations for different parts of the YouTube request lifecycle.

Key configuration options:

• lang: BCP 47 language code (e.g., 'en').
• userAgent: Custom User-Agent string.
• cache: An object implementing the CacheStrategy interface.
• cacheTTL: Time-to-live for cache entries in milliseconds (defaults to 1 hour).
• videoDetails: Set to true to return a TranscriptResult containing both video metadata and segments.
• retries: Maximum retry attempts for transient failures (429, 5xx). Defaults to 0.
• retryDelay: Base delay in milliseconds for exponential backoff. Defaults to 1000.
• signal: An AbortSignal to cancel in-flight requests.
• disableHttps: Use HTTP instead of HTTPS (not recommended for production).

Custom Fetch Functions: You can override the default fetching logic by providing custom functions that accept FetchParams and return a Promise<Response>:

• videoFetch: For the YouTube watch page (GET).
• transcriptFetch: For the transcript XML data (GET).
• playerFetch: For the YouTube Innertube player API (POST).

export interface TranscriptConfig {
  lang?: string;
  userAgent?: string;
  cache?: CacheStrategy;
  cacheTTL?: number;
  disableHttps?: boolean;
  videoFetch?: (params: FetchParams) => Promise<Response>;
  transcriptFetch?: (params: FetchParams) => Promise<Response>;
  playerFetch?: (params: FetchParams) => Promise<Response>;
  retries?: number;
  retryDelay?: number;
  signal?: AbortSignal;
  videoDetails?: boolean;
}