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.
- 🎯 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
npm install youtube-transcript-js-api
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);
# 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"
# 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
# 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
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
);
Gets transcript for specific language with validation.
const transcript = await api.getTranscriptByLanguage(
'https://www.youtube.com/watch?v=VIDEO_ID',
'en'
);
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
const api = new YouTubeTranscriptApi({
debug: true,
rateLimit: {
enabled: true,
maxConcurrentRequests: 2,
baseDelay: { min: 1000, max: 2000 }
},
timeout: 30000
});
The library includes several predefined rate limiting configurations for different use cases:
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
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
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
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
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
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
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
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
const api = new YouTubeTranscriptApi({
rateLimit: SCENARIO_CONFIGS.EDUCATION
});
- Optimized for educational content processing
- Handles large video libraries
- Consistent performance during class hours
const api = new YouTubeTranscriptApi({
rateLimit: SCENARIO_CONFIGS.CONTENT_MODERATION
});
- Fast processing for content review workflows
- High concurrent request handling
- Quick recovery from rate limits
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
});
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>;
}
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
[
{ text: "Hello world", start: 0, duration: 2.5 },
{ text: "How are you?", start: 2.5, duration: 1.8 }
]
-
text
- Plain text (default) -
srt
- SubRip subtitle format -
vtt
- WebVTT format -
json
- JSON format -
timestamp
- Text with timestamps
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');
}
}
git clone https://github.com/cmyildirim/youtube-transcript-js-api.git
cd youtube-transcript-js-api
npm install
# Run all tests
npm test
# Batch test with CLI
npx tsx tests/batch-test.ts 10
npm run build
Detailed documentation available in the docs
folder:
Contributions are welcome! Please read our contributing guidelines and ensure all tests pass.
MIT License - see LICENSE file for details.
- youtube-transcript-api - The original Python library
- youtube-dl - Download YouTube videos
This library is for educational and research purposes only. Please respect YouTube's Terms of Service and use this library responsibly.
- 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.