🎬 YouTube Captions TypeScript

A powerful TypeScript library to fetch YouTube video transcripts/captions. Supports automatic translation, multiple output formats, and proxy configurations to avoid IP blocks.

✨ Features

• 🎯 Simple API - Fetch transcripts with just a video ID
• 🌍 Multi-language - Support for all languages available on YouTube
• 🔄 Auto-translation - Translate transcripts to any supported language
• 📝 Multiple formats - JSON, SRT, WebVTT, CSV, plain text
• 🛡️ Proxy support - Avoid IP blocks with rotating proxies
• 🎨 Formatting options - Preserve or strip HTML formatting
• 📱 CLI included - Command-line interface for easy usage
• 🚀 TypeScript - Full type safety and IntelliSense support

📦 Installation

npm install youtube-captions-ts

🚀 Quick Start

Basic Usage

import { YouTubeCaptionsApi } from 'youtube-captions-ts';

const api = new YouTubeCaptionsApi();

// Fetch transcript for a video
const transcript = await api.fetch('dQw4w9WgXcQ');

// Access transcript data
console.log('Language:', transcript.language);
console.log('Total snippets:', transcript.length);

// Iterate through transcript snippets
for (const snippet of transcript) {
  console.log(`${snippet.start}s: ${snippet.text}`);
}

Language Selection

// Fetch with language preference (fallback order)
const transcript = await api.fetch('dQw4w9WgXcQ', {
  languages: ['es', 'en', 'fr'], // Spanish first, then English, then French
  preserveFormatting: true
});

List Available Transcripts

const transcriptList = await api.list('dQw4w9WgXcQ');

console.log('Available transcripts:');
for (const transcript of transcriptList) {
  console.log(`- ${transcript.languageCode}: ${transcript.language}`);
  console.log(`  Generated: ${transcript.isGenerated}`);
  console.log(`  Translatable: ${transcript.isTranslatable}`);
}

// Find specific transcript types
const manual = transcriptList.findManuallyCreatedTranscript(['en']);
const generated = transcriptList.findGeneratedTranscript(['en']);

Translation

const transcriptList = await api.list('dQw4w9WgXcQ');
const englishTranscript = transcriptList.findTranscript(['en']);

// Translate to Spanish
const spanishTranscript = englishTranscript.translate('es');
const fetchedSpanish = await spanishTranscript.fetch();

🎨 Formatters

Convert transcripts to different formats:

import { 
  SRTFormatter, 
  WebVTTFormatter, 
  JSONFormatter,
  TextFormatter 
} from 'youtube-captions-ts/formatters';

const transcript = await api.fetch('dQw4w9WgXcQ');

// SRT format
const srtFormatter = new SRTFormatter();
const srtContent = srtFormatter.formatTranscript(transcript);

// WebVTT format
const webvttFormatter = new WebVTTFormatter();
const webvttContent = webvttFormatter.formatTranscript(transcript);

// JSON format with indentation
const jsonFormatter = new JSONFormatter();
const jsonContent = jsonFormatter.formatTranscript(transcript, 2);

// Plain text only
const textFormatter = new TextFormatter();
const textContent = textFormatter.formatTranscript(transcript);

🛡️ Proxy Support

Avoid IP blocks with proxy configurations:

Generic Proxy

import { GenericProxyConfig } from 'youtube-captions-ts/proxies';

const proxyConfig = new GenericProxyConfig(
  'http://proxy-server:8080',
  'https://proxy-server:8080'
);

const api = new YouTubeCaptionsApi({ proxyConfig });

Webshare Rotating Proxies

import { WebshareProxyConfig } from 'youtube-captions-ts/proxies';

const proxyConfig = new WebshareProxyConfig(
  'your-username',
  'your-password',
  ['US', 'CA'], // Filter to US and Canada IPs only
  10 // Retry 10 times on blocks
);

const api = new YouTubeCaptionsApi({ proxyConfig });

🖥️ CLI Usage

Installation

npm install -g youtube-captions-ts

Basic Usage

# Fetch transcript for a video
youtube-captions dQw4w9WgXcQ

# Multiple videos
youtube-captions dQw4w9WgXcQ oHg5SJYRHA0

# Specify languages
youtube-captions dQw4w9WgXcQ --languages es en

# Output to file
youtube-captions dQw4w9WgXcQ --format srt --output transcript.srt

# List available transcripts
youtube-captions dQw4w9WgXcQ --list-transcripts

Advanced Options

# Use proxy
youtube-captions dQw4w9WgXcQ --http-proxy http://proxy:8080

# Use Webshare
youtube-captions dQw4w9WgXcQ --webshare-username user --webshare-password pass

# Translate transcript
youtube-captions dQw4w9WgXcQ --translate es

# Exclude auto-generated
youtube-captions dQw4w9WgXcQ --exclude-generated

# Preserve formatting
youtube-captions dQw4w9WgXcQ --preserve-formatting

🔧 Advanced Configuration

Custom HTTP Client

import axios from 'axios';

const customClient = axios.create({
  timeout: 60000,
  headers: {
    'User-Agent': 'MyApp/1.0'
  }
});

const api = new YouTubeCaptionsApi({ 
  httpClient: customClient 
});

Batch Processing

const videoIds = ['dQw4w9WgXcQ', 'oHg5SJYRHA0', 'jNQXAC9IVRw'];

const results = await api.fetchMultiple(videoIds, {
  languages: ['en', 'es']
});

results.forEach((result, index) => {
  if (result.success) {
    console.log(`Video ${index + 1}: Success!`);
    console.log(result.transcript?.snippets.length, 'snippets');
  } else {
    console.log(`Video ${index + 1}: Error -`, result.error?.message);
  }
});

🚫 Error Handling

The library provides detailed error types:

import { 
  TranscriptsDisabled,
  NoTranscriptFound,
  VideoUnavailable,
  IpBlocked,
  AgeRestricted 
} from 'youtube-captions-ts/errors';

try {
  const transcript = await api.fetch('videoId');
} catch (error) {
  if (error instanceof TranscriptsDisabled) {
    console.log('Transcripts are disabled for this video');
  } else if (error instanceof NoTranscriptFound) {
    console.log('No transcript found for requested languages');
  } else if (error instanceof IpBlocked) {
    console.log('IP blocked - consider using proxies');
  } else if (error instanceof AgeRestricted) {
    console.log('Video is age-restricted');
  }
}

📊 Supported Formats

• JSON - Raw transcript data
• SRT - SubRip subtitle format
• WebVTT - Web Video Text Tracks
• CSV - Comma-separated values
• Text - Plain text only
• Pretty - Formatted JSON with indentation

⚠️ Important Notes

1. Rate Limiting: YouTube aggressively blocks IPs making too many requests
2. Proxies Recommended: Use rotating residential proxies for production
3. Video ID Format: Use video IDs (e.g., dQw4w9WgXcQ), not full URLs
4. Transcript Availability: Not all videos have transcripts available

🛠️ Development

# Clone the repository
git clone https://github.com/yourusername/youtube-captions-ts.git

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run linting
npm run lint

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

📞 Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: [email protected]

⭐ If this library helps you, please consider giving it a star on GitHub!