AI YouTube Transcript API


A Node.js library for retrieving and processing YouTube video transcripts. This package uses the unofficial YouTube API to fetch transcripts without requiring an API key or headless browser.

Table of Contents

- Features
- Installation
- Basic Usage
- Advanced Usage
- Listing Available Transcripts
- Fetching with Language Preferences
- Translating Transcripts
- Using Formatters
- Authentication for Age-Restricted Videos
- Using Proxies to Handle IP Bans
- Common Use Cases
- Batch Processing Multiple Videos
- Saving Transcripts to Files
- CLI Usage
- CLI Options
- CLI Examples
- API Reference
- YoutubeTranscript
- Transcript
- TranscriptList
- FetchedTranscript
- Formatters
- Proxy Support
- Troubleshooting
- Development
- Setting Up
- Running Tests
- Contributing
- Warning
- License

Features

- Fetch transcripts from YouTube videos
- Support for multiple languages with preference ordering
- Distinguish between manually created and auto-generated transcripts
- Translate transcripts to different languages
- Preserve HTML formatting in transcripts
- Format transcripts in various formats (JSON, Text, SRT)
- Support for authentication via cookies for age-restricted videos
- Proxy support for handling IP bans
- Comprehensive CLI tool

Installation

``bash
npm install ai-youtube-transcript
`

or

`bash
yarn add ai-youtube-transcript
`

Basic Usage

`javascript
import { YoutubeTranscript } from 'ai-youtube-transcript';

// Create a new instance
const ytTranscript = new YoutubeTranscript();

// Fetch transcript with default options (English)
ytTranscript.fetch('VIDEO_ID_OR_URL')
.then(transcript => {
console.log(Video ID: ${transcript.videoId});
console.log(Language: ${transcript.language} (${transcript.languageCode}));
console.log(Auto-generated: ${transcript.isGenerated ? 'Yes' : 'No'});
console.log(Number of segments: ${transcript.length});

// Get the full text
console.log(transcript.getText());

// Get raw data
console.log(transcript.toRawData());
})
.catch(error => {
console.error('Error:', error.message);
});
`

$3

`javascript
import { YoutubeTranscript } from 'ai-youtube-transcript';

// Using the static method (legacy approach)
YoutubeTranscript.fetchTranscript('VIDEO_ID_OR_URL')
.then(console.log)
.catch(console.error);
`

Advanced Usage

$3

`javascript
import { YoutubeTranscript } from 'ai-youtube-transcript';

const ytTranscript = new YoutubeTranscript();

// List all available transcripts
ytTranscript.list('VIDEO_ID_OR_URL')
.then(transcriptList => {
console.log('Available transcripts:');
for (const transcript of transcriptList) {
console.log(- ${transcript.language} (${transcript.languageCode}));
console.log( Auto-generated: ${transcript.isGenerated ? 'Yes' : 'No'});
console.log( Translatable: ${transcript.isTranslatable ? 'Yes' : 'No'});

if (transcript.isTranslatable) {
console.log(' Available translations:');
for (const lang of transcript.translationLanguages) {
console.log( - ${lang.languageName} (${lang.languageCode}));
}
}
}
})
.catch(error => {
console.error('Error:', error.message);
});
`

$3

`javascript
import { YoutubeTranscript } from 'ai-youtube-transcript';

const ytTranscript = new YoutubeTranscript();

// Fetch transcript with language preferences
ytTranscript.fetch('VIDEO_ID_OR_URL', {
languages: ['fr', 'en', 'es'], // Try French first, then English, then Spanish
preserveFormatting: true // Keep HTML formatting
})
.then(transcript => {
console.log(Selected language: ${transcript.language} (${transcript.languageCode}));
console.log(transcript.getText());
})
.catch(error => {
console.error('Error:', error.message);
});
`

$3

Translation is a two-step process:
1. First, find a transcript in a specific language
2. Then, translate that transcript to another language

`javascript
import { YoutubeTranscript } from 'ai-youtube-transcript';

const ytTranscript = new YoutubeTranscript();

// Get the list of available transcripts
ytTranscript.list('VIDEO_ID_OR_URL')
.then(async transcriptList => {
// Step 1: Find a transcript in English
const transcript = transcriptList.findTranscript(['en']);

// Check if it can be translated
if (transcript.isTranslatable) {
console.log(Found translatable transcript in ${transcript.language});
console.log('Available translation languages:');
transcript.translationLanguages.forEach(lang => {
console.log(- ${lang.languageName} (${lang.languageCode}));
});

// Step 2: Translate to Spanish
const translatedTranscript = transcript.translate('es');

// Fetch the translated transcript
const fetchedTranslation = await translatedTranscript.fetch();
console.log(Translated to Spanish: ${fetchedTranslation.getText().substring(0, 100)}...);
} else {
console.log(Transcript in ${transcript.language} is not translatable);
}
})
.catch(error => {
console.error('Error:', error.message);
});
`

You can also do this in a single chain:

`javascript
ytTranscript.list('VIDEO_ID_OR_URL')
.then(list => list.findTranscript(['en']))
.then(transcript => transcript.isTranslatable ? transcript.translate('es') : null)
.then(translatedTranscript => translatedTranscript ? translatedTranscript.fetch() : null)
.then(result => {
if (result) console.log(Translated transcript: ${result.getText().substring(0, 100)}...);
else console.log('Translation not available');
})
.catch(error => console.error('Error:', error.message));
`

$3

`javascript
import { YoutubeTranscript, JSONFormatter, TextFormatter, SRTFormatter } from 'ai-youtube-transcript';

const ytTranscript = new YoutubeTranscript();

ytTranscript.fetch('VIDEO_ID_OR_URL')
.then(transcript => {
// Format as JSON
const jsonFormatter = new JSONFormatter();
const jsonOutput = jsonFormatter.formatTranscript(transcript, { indent: 2 });
console.log(jsonOutput);

// Format as plain text
const textFormatter = new TextFormatter();
const textOutput = textFormatter.formatTranscript(transcript);
console.log(textOutput);

// Format as SRT
const srtFormatter = new SRTFormatter();
const srtOutput = srtFormatter.formatTranscript(transcript);
console.log(srtOutput);
})
.catch(error => {
console.error('Error:', error.message);
});
`

$3

`javascript
import { YoutubeTranscript } from 'ai-youtube-transcript';

// Create an instance with cookie authentication
const ytTranscript = new YoutubeTranscript('/path/to/cookies.txt');

// Now you can access age-restricted videos
ytTranscript.fetch('AGE_RESTRICTED_VIDEO_ID')
.then(transcript => {
console.log(transcript.getText());
})
.catch(error => {
console.error('Error:', error.message);
});
`

$3

`javascript
import { YoutubeTranscript, GenericProxyConfig, WebshareProxyConfig } from 'ai-youtube-transcript';

// Using a generic proxy
const genericProxy = new GenericProxyConfig(
'http://username:password@proxy-host:port',
'https://username:password@proxy-host:port'
);
const ytTranscript1 = new YoutubeTranscript(null, genericProxy);

// Using Webshare proxy
const webshareProxy = new WebshareProxyConfig('username', 'password');
const ytTranscript2 = new YoutubeTranscript(null, webshareProxy);

// Now use ytTranscript1 or ytTranscript2 as usual
`

Common Use Cases

$3

`javascript
import { YoutubeTranscript } from 'ai-youtube-transcript';
import fs from 'fs';

async function batchProcessVideos(videoIds) {
const ytTranscript = new YoutubeTranscript();
const results = [];

for (const videoId of videoIds) {
try {
console.log(Processing video ${videoId}...);
const transcript = await ytTranscript.fetch(videoId);

results.push({
videoId,
language: transcript.language,
text: transcript.getText(),
segments: transcript.length
});

console.log(✅ Successfully processed ${videoId});
} catch (error) {
console.error(❌ Error processing ${videoId}: ${error.message});
results.push({
videoId,
error: error.message
});
}
}

return results;
}

// Example usage
const videoIds = [
'dQw4w9WgXcQ', // Rick Astley - Never Gonna Give You Up
'UF8uR6Z6KLc', // Steve Jobs' 2005 Stanford Commencement Address
'YbJOTdZBX1g' // YouTube Rewind 2018
];

batchProcessVideos(videoIds)
.then(results => {
console.log(Processed ${results.length} videos);
fs.writeFileSync('results.json', JSON.stringify(results, null, 2));
});
`

$3

`javascript
import { YoutubeTranscript, JSONFormatter, TextFormatter, SRTFormatter } from 'ai-youtube-transcript';
import fs from 'fs';
import path from 'path';

async function saveTranscriptInMultipleFormats(videoId, outputDir) {
const ytTranscript = new YoutubeTranscript();

try {
// Create output directory if it doesn't exist
if (!fs.existsSync(outputDir)) {
fs.mkdirSync(outputDir, { recursive: true });
}

// Fetch the transcript
const transcript = await ytTranscript.fetch(videoId);

// Save as JSON
const jsonFormatter = new JSONFormatter();
const jsonOutput = jsonFormatter.formatTranscript(transcript, { indent: 2 });
fs.writeFileSync(
path.join(outputDir, ${videoId}.json),
jsonOutput
);

// Save as plain text
const textFormatter = new TextFormatter();
const textOutput = textFormatter.formatTranscript(transcript);
fs.writeFileSync(
path.join(outputDir, ${videoId}.txt),
textOutput
);

// Save as SRT
const srtFormatter = new SRTFormatter();
const srtOutput = srtFormatter.formatTranscript(transcript);
fs.writeFileSync(
path.join(outputDir, ${videoId}.srt),
srtOutput
);

console.log(Transcript for ${videoId} saved in multiple formats to ${outputDir});
return true;
} catch (error) {
console.error(Error saving transcript for ${videoId}: ${error.message});
return false;
}
}

// Example usage
saveTranscriptInMultipleFormats('dQw4w9WgXcQ', './transcripts');
`

CLI Usage

The package includes a command-line interface for easy transcript retrieval:

`bash
npx ai-youtube-transcript [options]
`

$3

`
Options:
--languages, -l Comma-separated list of language codes in order of preference (default: en)
--format, -f Output format: text, json, srt (default: text)
--output, -o Write output to a file instead of stdout
--translate, -t Translate transcript to the specified language (can be combined with --languages)
--list-transcripts List all available transcripts for the video
--exclude-generated Only use manually created transcripts
--exclude-manually-created Only use automatically generated transcripts
--preserve-formatting Preserve HTML formatting in the transcript
--cookies Path to cookies.txt file for authentication
--http-proxy HTTP proxy URL
--https-proxy HTTPS proxy URL
--webshare-proxy-username Webshare proxy username
--webshare-proxy-password

Webshare proxy password
--help, -h Show this help message
`

$3

`bash


Basic usage