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();
const transcript = await api.getTranscript('https://www.youtube.com/watch?v=dQw4w9WgXcQ', ['en']);
console.log(transcript);
CLI Usage
Basic Commands
npx youtube-transcript get "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
npx youtube-transcript get "VIDEO_URL" --language en
npx youtube-transcript get "VIDEO_URL" --language en --translate es
npx youtube-transcript list "VIDEO_URL"
npx youtube-transcript debug "VIDEO_URL"
Output Formats
npx youtube-transcript get "VIDEO_URL" --format text
npx youtube-transcript get "VIDEO_URL" --format srt --output transcript.srt
npx youtube-transcript get "VIDEO_URL" --format vtt --output transcript.vtt
npx youtube-transcript get "VIDEO_URL" --format json --output transcript.json
npx youtube-transcript get "VIDEO_URL" --format timestamp
Advanced Options
npx youtube-transcript get "VIDEO_URL" --language "en,es,fr"
npx youtube-transcript get "VIDEO_URL" --output "my-transcript.txt"
npx youtube-transcript get "VIDEO_URL" --debug
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']
);
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);
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 {
debug?: boolean;
timeout?: number;
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;
};
};
userAgent?: string;
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
npm test
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.