This package has been deprecated

Author message:

Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

youtube-transcript-js-api
TypeScript icon, indicating that this package has built-in type declarations

1.4.2 • Public • Published

YouTube Transcript API

npm version npm downloads CI codecov TypeScript MIT License GitHub issues

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:

🤝 Contributing

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

📄 License

MIT License - see LICENSE file for details.

Related Projects

Disclaimer

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

🔗 Links


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.

Package Sidebar

Install

npm i youtube-transcript-js-api

Weekly Downloads

15

Version

1.4.2

License

MIT

Unpacked Size

728 kB

Total Files

240

Last publish

Collaborators

  • cmyildirim