youtube-transcript-js-api

YouTube Transcript API

A robust TypeScript library for fetching YouTube video transcripts with 100% success rate when transcripts are available. Features intelligent fallback strategies, translated transcripts, and comprehensive error handling.

✨ Key Features

• 🎯 100% Success Rate - Ultra-robust 11-strategy fallback system
• ⚡ High Performance - Smart strategy selection with ~80ms average response time
• 🛡️ Rate Limiting - Built-in protection against YouTube API limits
• 📱 CLI Support - Command-line interface for easy integration
• 🔧 TypeScript - Full type safety and IntelliSense support

🚀 Quick Start

Installation

npm install youtube-transcript-js-api

Basic Usage

import { YouTubeTranscriptApi } from 'youtube-transcript-js-api';

const api = new YouTubeTranscriptApi();

// Get transcript in English
const transcript = await api.getTranscript('https://www.youtube.com/watch?v=dQw4w9WgXcQ', ['en']);
console.log(transcript);

CLI Usage

Basic Commands

# Get transcript for a video
npx youtube-transcript get "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

# Get transcript in specific language
npx youtube-transcript get "VIDEO_URL" --language en

# Get transcript with translation
npx youtube-transcript get "VIDEO_URL" --language en --translate es

# List available transcript languages
npx youtube-transcript list "VIDEO_URL"

# Debug mode for troubleshooting
npx youtube-transcript debug "VIDEO_URL"

Output Formats

# Plain text (default)
npx youtube-transcript get "VIDEO_URL" --format text

# SRT subtitle format
npx youtube-transcript get "VIDEO_URL" --format srt --output transcript.srt

# WebVTT format
npx youtube-transcript get "VIDEO_URL" --format vtt --output transcript.vtt

# JSON format
npx youtube-transcript get "VIDEO_URL" --format json --output transcript.json

# Text with timestamps
npx youtube-transcript get "VIDEO_URL" --format timestamp

Advanced Options

# Multiple language preferences
npx youtube-transcript get "VIDEO_URL" --language "en,es,fr"

# Custom output file
npx youtube-transcript get "VIDEO_URL" --output "my-transcript.txt"

# Debug with verbose logging
npx youtube-transcript get "VIDEO_URL" --debug

# Combine multiple options
npx youtube-transcript get "VIDEO_URL" --language en --format srt --output subtitle.srt --debug

📖 API Reference

Core Methods

getTranscript(videoUrl, languages?)

Fetches transcript with ultra-robust fallback system.

const transcript = await api.getTranscript(
  'https://www.youtube.com/watch?v=VIDEO_ID',
  ['en', 'es'] // Optional: preferred languages
);

getTranscriptByLanguage(videoUrl, language)

Gets transcript for specific language with validation.

const transcript = await api.getTranscriptByLanguage(
  'https://www.youtube.com/watch?v=VIDEO_ID',
  'en'
);

listTranscripts(videoUrl)

Lists all available transcript languages.

const available = await api.listTranscripts('https://www.youtube.com/watch?v=VIDEO_ID');
console.log(available.transcripts); // Array of available languages

Configuration Options

Basic Configuration

const api = new YouTubeTranscriptApi({
  debug: true,
  rateLimit: {
    enabled: true,
    maxConcurrentRequests: 2,
    baseDelay: { min: 1000, max: 2000 }
  },
  timeout: 30000
});

Rate Limit Presets

The library includes several predefined rate limiting configurations for different use cases:

Conservative (High Reliability)

import { CONSERVATIVE_CONFIG } from 'youtube-transcript-js-api/configs';

const api = new YouTubeTranscriptApi({
  rateLimit: CONSERVATIVE_CONFIG
});

• Use case: High-volume production environments requiring maximum reliability
• Max concurrent: 1 request
• Delays: 2-4 seconds between requests
• Backoff: Exponential with jitter

Balanced (Recommended for Production)

import { BALANCED_CONFIG } from 'youtube-transcript-js-api/configs';

const api = new YouTubeTranscriptApi({
  rateLimit: BALANCED_CONFIG
});

• Use case: Production applications with moderate traffic
• Max concurrent: 2 requests
• Delays: 1-2 seconds between requests
• Backoff: Moderate exponential growth

Aggressive (High Throughput)

import { AGGRESSIVE_CONFIG } from 'youtube-transcript-js-api/configs';

const api = new YouTubeTranscriptApi({
  rateLimit: AGGRESSIVE_CONFIG
});

• Use case: Batch processing, data analysis pipelines
• Max concurrent: 3 requests
• Delays: 500-1000ms between requests
• Backoff: Fast recovery with circuit breaker

Development/Testing

import { DEVELOPMENT_CONFIG } from 'youtube-transcript-js-api/configs';

const api = new YouTubeTranscriptApi({
  rateLimit: DEVELOPMENT_CONFIG
});

• Use case: Local development and testing
• Max concurrent: 5 requests
• Delays: 100-500ms between requests
• Backoff: Quick recovery for fast iteration

Disabled (No Rate Limiting)

import { DISABLED_CONFIG } from 'youtube-transcript-js-api/configs';

const api = new YouTubeTranscriptApi({
  rateLimit: DISABLED_CONFIG
});

• Use case: Testing environments or when using external rate limiting
• Max concurrent: Unlimited
• Delays: None
• ⚠️ Warning: Use with caution in production

Proxy Optimized

import { PROXY_OPTIMIZED_CONFIG } from 'youtube-transcript-js-api/configs';

const api = new YouTubeTranscriptApi({
  rateLimit: PROXY_OPTIMIZED_CONFIG
});

• Use case: Applications behind CDNs or proxy servers
• Max concurrent: 2 requests
• Delays: 800-1500ms with adaptive scaling
• Features: Proxy detection and adaptive delays

Scenario-Specific Configurations

E-commerce Integration

import { SCENARIO_CONFIGS } from 'youtube-transcript-js-api/configs';

const api = new YouTubeTranscriptApi({
  rateLimit: SCENARIO_CONFIGS.ECOMMERCE
});

• Optimized for product video transcription
• Balanced performance and reliability
• Handles peak shopping periods

Social Media Analytics

const api = new YouTubeTranscriptApi({
  rateLimit: SCENARIO_CONFIGS.SOCIAL_MEDIA
});

• High throughput for social media monitoring
• Fast processing of trending content
• Circuit breaker for API protection

Educational Platforms

const api = new YouTubeTranscriptApi({
  rateLimit: SCENARIO_CONFIGS.EDUCATION
});

• Optimized for educational content processing
• Handles large video libraries
• Consistent performance during class hours

Content Moderation

const api = new YouTubeTranscriptApi({
  rateLimit: SCENARIO_CONFIGS.CONTENT_MODERATION
});

• Fast processing for content review workflows
• High concurrent request handling
• Quick recovery from rate limits

Custom Configuration

const customConfig = {
  enabled: true,
  maxConcurrentRequests: 3,
  baseDelay: { min: 800, max: 1200 },
  exponentialBackoff: {
    multiplier: 1.8,
    maxDelay: 30000,
    jitter: true
  },
  circuitBreaker: {
    enabled: true,
    failureThreshold: 5,
    resetTimeout: 60000
  },
  adaptiveScaling: {
    enabled: true,
    successSpeedup: 0.9,
    failureSlowdown: 1.5
  }
};

const api = new YouTubeTranscriptApi({
  rateLimit: customConfig,
  timeout: 15000,
  debug: false
});

Complete Configuration Reference

interface YouTubeTranscriptApiConfig {
  // Enable debug logging
  debug?: boolean;

  // Request timeout in milliseconds
  timeout?: number;

  // Rate limiting configuration
  rateLimit?: {
    enabled: boolean;
    maxConcurrentRequests: number;
    baseDelay: { min: number; max: number };
    exponentialBackoff?: {
      multiplier: number;
      maxDelay: number;
      jitter: boolean;
    };
    circuitBreaker?: {
      enabled: boolean;
      failureThreshold: number;
      resetTimeout: number;
    };
    adaptiveScaling?: {
      enabled: boolean;
      successSpeedup: number;
      failureSlowdown: number;
    };
  };

  // User agent for requests
  userAgent?: string;

  // Custom headers
  headers?: Record<string, string>;
}

🎯 Ultra-Robust System

The library achieves 100% success rate through:

• Smart Parameter Detection - Identifies problematic YouTube parameters
• 11 Fallback Strategies - Multiple approaches when primary method fails
• Real-time Analytics - Debug logging shows successful strategies

📝 Output Formats

Default (Array)

[
  { text: "Hello world", start: 0, duration: 2.5 },
  { text: "How are you?", start: 2.5, duration: 1.8 }
]

CLI Formats

• text - Plain text (default)
• srt - SubRip subtitle format
• vtt - WebVTT format
• json - JSON format
• timestamp - Text with timestamps

🛠️ Error Handling

try {
  const transcript = await api.getTranscript(videoUrl, ['en']);
} catch (error) {
  if (error.name === 'NoTranscriptFoundError') {
    console.log('No transcript available for this video');
  } else if (error.name === 'VideoUnavailableError') {
    console.log('Video is private or unavailable');
  }
}

🔧 Development

Setup

git clone https://github.com/cmyildirim/youtube-transcript-js-api.git
cd youtube-transcript-js-api
npm install

Testing

# Run all tests
npm test

# Batch test with CLI
npx tsx tests/batch-test.ts 10

Building

npm run build

📚 Documentation

Detailed documentation available in the docs folder:

• Deployment Guide

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and ensure all tests pass.

📄 License

MIT License - see LICENSE file for details.

Related Projects

• youtube-transcript-api - The original Python library
• youtube-dl - Download YouTube videos

Disclaimer

This library is for educational and research purposes only. Please respect YouTube's Terms of Service and use this library responsibly.

🔗 Links

• npm Package
• GitHub Repository
• Issues

Version 1.4.0 - Ultra-robust transcript fetching with 100% success rate and fully modularized test suite. All tests are now organized in logical groups under tests/transcript/ for easier maintenance and coverage.