npm package: @playzone/youtube-transcript
Description: A JavaScript API which allows you to get the transcripts/subtitles for a given YouTube video. It also works for automatically generated subtitles and it does not require a headless browser.
Author: Pavan Reddy
Latest version: 1.0.0

<h1 align="center">
  ✨ YouTube Transcript API ✨
</h1>

<p align="center">
  <a href="https://www.npmjs.com/package/@playzone/youtube-transcript">
    <img src="https://img.shields.io/npm/v/@playzone/youtube-transcript.svg" alt="Current Version">
  </a>
  <a href="https://www.npmjs.com/package/@playzone/youtube-transcript">
    <img src="https://img.shields.io/npm/dm/@playzone/youtube-transcript.svg" alt="Downloads">
  </a>
  <a href="http://opensource.org/licenses/MIT">
    <img src="http://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat" alt="MIT license">
  </a>
  <a href="https://nodejs.org/">
    <img src="https://img.shields.io/node/v/@playzone/youtube-transcript.svg" alt="Supported Node.js Versions">
  </a>
  <a href="https://github.com/features/actions">
    <img src="https://github.com/actions/actions/workflows/ci.yml/badge.svg" alt="Build Status">
  </a>
</p>

<p align="center">
  <b>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!</b>
</p>

<p align="center">
  <b>🚀 Built with modern JavaScript/TypeScript for maximum performance and developer experience!</b>
</p>

## ✨ 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

### Basic Usage

```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"
```

### TypeScript Usage

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

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

### Enhanced API with Advanced Proxy Support

```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

### Core API

The main `YouTubeTranscriptApi` class provides the following methods:

#### `fetch(videoId: string, options?: FetchOptions): Promise<FetchedTranscript>`

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<TranscriptList>`

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();
}
```

### Enhanced API

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

### Generic Proxy Configuration

```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'
));
```

### Webshare Rotating Proxies

```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
));
```

### Enhanced Proxy Support

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'
});
```

### Key Enhanced Features

- **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

### Basic Commands

```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
```

### CLI Options

| 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` |

### ⚠️ CLI Limitations

**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:

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

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

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

## 🔧 Development

### Prerequisites
- Node.js 16+ 
- npm or yarn

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

### Build
```bash
npm run build
```

### Test
```bash
npm test
```

### Lint
```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](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](https://github.com/playzone/youtube-transcript-api-js/issues) page
2. Create a new issue with detailed information
3. Use the programmatic API for reliable functionality

---

<p align="center">
  <b>Made with ❤️ by the PlayZone</b>
</p>