✨ YouTube Transcript API ✨

A powerful JavaScript/TypeScript API which allows you to retrieve the transcript/subtitles for any YouTube video. It supports automatically generated subtitles, translation to multiple languages, advanced proxy support, and works without requiring a headless browser!

🚀 Built with modern JavaScript/TypeScript for maximum performance and developer experience!

✨ Features

- ✅ Auto-Generated Transcript Detection - Automatically detects and fetches auto-generated subtitles
- ✅ Translation Support - Translate transcripts to 17+ languages
- ✅ Multiple Format Support - JSON, SRT, WebVTT, Text, Pretty Print
- ✅ Advanced Proxy Support - HTTP/HTTPS proxy agents with http-proxy-agent and https-proxy-agent
- ✅ Invidious Fallback - Alternative YouTube frontend support for when YouTube blocks requests
- ✅ Multiple Instance Failover - Automatic failover between multiple Invidious instances
- ✅ Dynamic Configuration - Runtime configuration changes for proxy and Invidious settings
- ✅ TypeScript Support - Full type safety and IntelliSense
- ✅ CLI Interface - Command-line tool for easy usage (some features may not work as expected)
- ✅ Error Handling - Comprehensive error handling with specific error types
- ✅ High Performance - Optimized for speed and efficiency
- ✅ No Dependencies - No headless browser required
- ✅ Modern JavaScript - Built with ES6+ and TypeScript

📦 Install

Install the package using npm:

``bash
npm install @playzone/youtube-transcript
`

Or using yarn:

`bash
yarn add @playzone/youtube-transcript
`

🚀 Quick Start

$3

`javascript
const { YouTubeTranscriptApi } = require('@playzone/youtube-transcript');

const api = new YouTubeTranscriptApi();

// Fetch transcript for a video
const transcript = await api.fetch('3bSukjgCGcc');
console.log(transcript.snippets[0].text); // "Hyderabad, capital of Telangana"
`

$3

`typescript
import { YouTubeTranscriptApi } from '@playzone/youtube-transcript';

const api = new YouTubeTranscriptApi();
const transcript = await api.fetch('3bSukjgCGcc');
console.log(transcript.snippets[0].text);
`

$3

`javascript
const { EnhancedYouTubeTranscriptApi } = require('@playzone/youtube-transcript');

// Basic enhanced API
const api = new EnhancedYouTubeTranscriptApi();

// With proxy support
const apiWithProxy = new EnhancedYouTubeTranscriptApi({
enabled: true,
http: 'http://proxy.example.com:8080',
https: 'https://proxy.example.com:8080'
});

// With Invidious fallback
const apiWithInvidious = new EnhancedYouTubeTranscriptApi({}, {
enabled: true,
instanceUrls: ['https://yewtu.be', 'https://invidious.io']
});

const transcript = await apiWithProxy.fetch('3bSukjgCGcc');
`

📖 API Documentation

$3

The main YouTubeTranscriptApi class provides the following methods:

#### fetch(videoId: string, options?: FetchOptions): Promise

Fetches a transcript for the given video ID.

`javascript
const api = new YouTubeTranscriptApi();

// Basic fetch
const transcript = await api.fetch('3bSukjgCGcc');

// With language preference
const transcript = await api.fetch('3bSukjgCGcc', {
languages: ['en', 'es']
});

// Exclude auto-generated transcripts
const transcript = await api.fetch('3bSukjgCGcc', {
excludeGenerated: true
});

// Exclude manual transcripts
const transcript = await api.fetch('3bSukjgCGcc', {
excludeManuallyCreated: true
});
`

#### list(videoId: string): Promise

Lists all available transcripts for a video.

`javascript
const api = new YouTubeTranscriptApi();
const transcriptList = await api.list('3bSukjgCGcc');

// Find specific transcript
const transcript = await transcriptList.findTranscript(['en']);

// Check if translatable
if (transcript.isTranslatable) {
const translated = transcript.translate('es');
const translatedData = await translated.fetch();
}
`

$3

The EnhancedYouTubeTranscriptApi provides advanced features:

#### Constructor Options

`javascript
const api = new EnhancedYouTubeTranscriptApi(proxyOptions, invidiousOptions);
`

Proxy Options:
`javascript
{
enabled: boolean, // Enable/disable proxy
http?: string, // HTTP proxy URL
https?: string // HTTPS proxy URL
}
`

Invidious Options:
`javascript
{
enabled: boolean, // Enable/disable Invidious
instanceUrls: string | string[], // Invidious instance URLs
timeout?: number // Request timeout (default: 10000ms)
}
`

#### Dynamic Configuration

`javascript
const api = new EnhancedYouTubeTranscriptApi();

// Change proxy settings at runtime
api.setProxyOptions({
enabled: true,
http: 'http://new-proxy.com:8080'
});

// Change Invidious settings at runtime
api.setInvidiousOptions({
enabled: true,
instanceUrls: ['https://yewtu.be']
});
`

🌐 Proxy Support

$3

`javascript
const { YouTubeTranscriptApi, GenericProxyConfig } = require('@playzone/youtube-transcript');

const api = new YouTubeTranscriptApi(new GenericProxyConfig(
'http://user:pass@proxy.example.com:8080',
'https://user:pass@proxy.example.com:8080'
));
`

$3

`javascript
const { YouTubeTranscriptApi, WebshareProxyConfig } = require('@playzone/youtube-transcript');

const api = new YouTubeTranscriptApi(new WebshareProxyConfig(
'your-username',
'your-password',
['us', 'de'], // Optional: filter by country
5 // retries
));
`

$3

The enhanced API provides advanced proxy support with better reliability and fallback mechanisms:

`javascript
const { EnhancedYouTubeTranscriptApi } = require('@playzone/youtube-transcript');

// Basic enhanced proxy
const api = new EnhancedYouTubeTranscriptApi({
enabled: true,
http: 'http://proxy.example.com:8080',
https: 'https://proxy.example.com:8080'
});

// With Invidious fallback
const apiWithFallback = new EnhancedYouTubeTranscriptApi({
enabled: true,
http: 'http://proxy.example.com:8080'
}, {
enabled: true,
instanceUrls: ['https://yewtu.be', 'https://invidious.io'],
timeout: 10000
});

// Dynamic configuration
api.setProxyOptions({
enabled: true,
http: 'http://new-proxy.com:8080'
});

api.setInvidiousOptions({
enabled: true,
instanceUrls: 'https://yewtu.be'
});
`

$3

- HTTP/HTTPS Proxy Agents: Uses http-proxy-agent and https-proxy-agent for better proxy handling
- Invidious Fallback: Alternative YouTube frontend when YouTube blocks requests
- Multiple Instance Support: Automatic failover between multiple Invidious instances
- Dynamic Configuration: Change proxy and Invidious settings at runtime
- Browser Compatibility: Proxy agents only used in Node.js environments
- Keep-Alive Optimization: Enhanced connection handling when not using proxies

🖥️ CLI Usage

$3

`bash


Fetch transcript

npx @playzone/youtube-transcript 3bSukjgCGcc

List available transcripts

npx @playzone/youtube-transcript --list-transcripts 3bSukjgCGcc

Fetch with specific language

npx @playzone/youtube-transcript 3bSukjgCGcc --languages en es

Exclude auto-generated transcripts

npx @playzone/youtube-transcript 3bSukjgCGcc --exclude-generated

Exclude manual transcripts

npx @playzone/youtube-transcript 3bSukjgCGcc --exclude-manually-created

Translate transcript

npx @playzone/youtube-transcript 3bSukjgCGcc --translate es

Output in specific format

npx @playzone/youtube-transcript 3bSukjgCGcc --format json
npx @playzone/youtube-transcript 3bSukjgCGcc --format srt
npx @playzone/youtube-transcript 3bSukjgCGcc --format webvtt
`

$3

| Option | Description | Example |
|--------|-------------|---------|
| --languages | Preferred languages (space-separated) | --languages en es fr |
| --exclude-generated | Exclude auto-generated transcripts | --exclude-generated |
| --exclude-manually-created | Exclude manual transcripts | --exclude-manually-created |
| --translate | Translate to specific language | --translate es |
| --format | Output format (json, srt, webvtt, text, pretty) | --format json |
| --list-transcripts | List available transcripts | --list-transcripts |
| --http-proxy | HTTP proxy URL | --http-proxy http://proxy:8080 |
| --https-proxy | HTTPS proxy URL | --https-proxy https://proxy:8080 |
| --webshare-proxy-username | Webshare proxy username | --webshare-proxy-username user |
| --webshare-proxy-password | Webshare proxy password | --webshare-proxy-password pass |

$3

Important Note: Some CLI commands may not work as expected due to implementation issues. However, all programmatic API features work perfectly. For reliable usage, we recommend using the programmatic API instead of the CLI.

Known CLI Issues:
- --list-transcripts flag may show full transcript instead of language list
- Some format options may not work correctly
- Translation commands may not work as expected

Recommended Usage:
Use the programmatic API for all features as it provides full functionality and reliability.

🚨 Error Handling

The library provides comprehensive error handling with specific error types:

`javascript
const {
NoTranscriptFound,
TranscriptsDisabled,
VideoUnavailable,
NotTranslatable,
TranslationLanguageNotAvailable,
IpBlocked
} = require('@playzone/youtube-transcript');

try {
const transcript = await api.fetch('invalid-video-id');
} catch (error) {
if (error instanceof NoTranscriptFound) {
console.log('No transcript found for this video');
} else if (error instanceof VideoUnavailable) {
console.log('Video is unavailable');
} else if (error instanceof TranscriptsDisabled) {
console.log('Transcripts are disabled for this video');
} else if (error instanceof IpBlocked) {
console.log('IP address is blocked, try using a proxy');
}
}
`

📊 Output Formats

The library supports multiple output formats:

$3


`javascript
const transcript = await api.fetch('3bSukjgCGcc');
console.log(JSON.stringify(transcript.toRawData(), null, 2));
`

$3

`javascript
const { FormatterLoader } = require('@playzone/youtube-transcript');
const formatter = new FormatterLoader().load('srt');
const srtOutput = formatter.formatTranscripts([transcript]);
console.log(srtOutput);
`

$3

`javascript
const formatter = new FormatterLoader().load('webvtt');
const webvttOutput = formatter.formatTranscripts([transcript]);
console.log(webvttOutput);
`

🔧 Development

$3

- Node.js 16+
- npm or yarn

$3

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

$3

`bash
npm run build
`

$3

`bash
npm test
`

$3

`bash
npm run lint
npm run lint:fix
`

📁 Project Structure

`
youtube-transcript-api-js/
├── api/ # Core API implementation
├── cli/ # CLI implementation
├── errors/ # Error classes
├── formatters/ # Output formatters
├── proxies/ # Proxy configurations
├── transcripts/ # Transcript models and parsing
├── enhanced-api/ # Enhanced API with advanced features
└── index.ts # Main exports
``

🎯 Use Cases

- Content Analysis: Analyze video content through transcripts
- Accessibility: Generate subtitles for videos
- Language Learning: Get transcripts in different languages
- SEO: Extract text content for search optimization
- Data Mining: Collect and analyze video content at scale
- Automation: Integrate transcript fetching into automated workflows

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

- Built with modern JavaScript/TypeScript
- Inspired by the need for reliable YouTube transcript access
- Enhanced with advanced proxy and fallback mechanisms

📞 Support

If you encounter any issues or have questions:

1. Check the Issues page
2. Create a new issue with detailed information
3. Use the programmatic API for reliable functionality

---

Made with ❤️ by the PlayZone