yt-transcript-api

✨ YT-TRANSCRIPT-API ✨

A lightweight JavaScript API and CLI for retrieving YouTube video transcripts and subtitles (including auto-generated and translated ones). No headless browsers required.

Author: Chintamani Pala

Features

• Fetch YouTube video transcripts (captions/subtitles) via API or CLI.
• Supports auto-generated and manually created transcripts.
• Supports translation (where available).
• No browser automation or scraping required.
• Proxy support for bypassing IP blocks.
• Multiple output formats: JSON, text, SRT, WebVTT, pretty-print.

Installation

npm install yt-transcript-api

Or clone this repository and install dependencies:

git clone https://github.com/chintamani-pala/yt-transcript-api.git
cd yt-transcript-api
npm install

Usage

Fetch Transcript (Default Language)

const { YouTubeTranscriptApi } = require('yt-transcript-api');
const ytt_api = new YouTubeTranscriptApi();
const video_id = '0Okxsszt624';

(async () => {
    const transcript = await ytt_api.fetch(video_id);
    console.log(transcript);
})();

Fetch Transcript (Specific Language)

(async () => {
    const transcript = await ytt_api.fetch(video_id, ["en"]);
    console.log(transcript);
})();

Fetch Transcript (Unavailable Language)

(async () => {
    try {
        await ytt_api.fetch(video_id, ["zz"]);
    } catch (err) {
        console.error("Transcript not found for requested language.");
    }
})();

List Available Transcripts

(async () => {
    const list = await ytt_api.list(video_id);
    console.log(list);
})();

Save Transcript to File

const fs = require('fs');
(async () => {
    const transcript = await ytt_api.fetch(video_id, ["en"]);
    fs.writeFileSync("transcript.json", JSON.stringify(transcript, null, 2));
})();

Format Transcript as JSON (Pretty)

const { formatters } = require('yt-transcript-api');
(async () => {
    const transcript = await ytt_api.fetch(video_id, ["en"]);
    const json = new formatters.JSONFormatter().formatTranscript(transcript, { space: 2 });
    console.log(json);
})();

Format Transcript as SRT

const { formatters } = require('yt-transcript-api');
(async () => {
    const transcript = await ytt_api.fetch(video_id, ["en"]);
    const srt = new formatters.SRTFormatter().formatTranscript(transcript);
    console.log(srt);
})();

Format Transcript as Text

const { formatters } = require('yt-transcript-api');
(async () => {
    const transcript = await ytt_api.fetch(video_id, ["en"]);
    const text = new formatters.TextFormatter().formatTranscript(transcript);
    console.log(text);
})();

Format Transcript as Pretty Print

const { formatters } = require('yt-transcript-api');
(async () => {
    const transcript = await ytt_api.fetch(video_id, ["en"]);
    const pretty = new formatters.PrettyPrintFormatter().formatTranscript(transcript);
    console.log(pretty);
})();

Format Transcript as WebVTT

const { formatters } = require('yt-transcript-api');
(async () => {
    const transcript = await ytt_api.fetch(video_id, ["en"]);
    const vtt = new formatters.WebVTTFormatter().formatTranscript(transcript);
    console.log(vtt);
})();

Error Handling: Invalid Video ID

(async () => {
    try {
        await ytt_api.fetch("invalid_video_id");
    } catch (err) {
        console.error("Invalid video ID.");
    }
})();

Using a Proxy

const { YouTubeTranscriptApi, GenericProxyConfig } = require('yt-transcript-api');
const proxyConfig = new GenericProxyConfig("http://proxy:8080");
const ytt_api = new YouTubeTranscriptApi({ proxy: proxyConfig });
(async () => {
    const transcript = await ytt_api.fetch(video_id, ["en"]);
    console.log(transcript);
})();

CLI Usage

Fetch transcript and print as JSON:

npx yt-transcript-api 0Okxsszt624 --lang en --format json

List available languages:

npx yt-transcript-api 0Okxsszt624 --list

Fetch transcript in a different language:

npx yt-transcript-api 0Okxsszt624 --lang es --format text

Use a proxy:

npx yt-transcript-api 0Okxsszt624 --lang en --proxy http://proxy:8080

API Exports

• YouTubeTranscriptApi - Main API class
• YouTubeTranscriptCli - CLI class
• TranscriptListFetcher - Fetches transcript lists
• ProxyConfig, GenericProxyConfig, WebshareProxyConfig, InvalidProxyConfig - Proxy support
• formatters - Output formatters (JSON, SRT, WebVTT, etc.)
• errors - Custom error classes
• settings - Internal constants

CLI Options

Option / Flag	Description
--video-ids <ids>	Comma-separated list of YouTube video IDs, or provide as positional arguments.
--format <type>	Output format: json, pretty, text, srt, webvtt. Default: pretty.
--languages <codes>	Comma-separated language codes (e.g. en,hi).
--excludeManuallyCreated	Exclude manually created transcripts.
--excludeGenerated	Exclude auto-generated transcripts.
--httpProxy <url>	Use an HTTP proxy server (e.g. http://proxy:8080).
--httpsProxy <url>	Use an HTTPS proxy server.
--webshareProxyUsername <u>	Username for Webshare proxy authentication.
--webshareProxyPassword <p>	Password for Webshare proxy authentication.
--preserveFormatting	Preserve original transcript formatting (where available).
--list	List available transcript languages for the video.

Note:

• Video IDs can be provided as a comma-separated list with --video-ids or as positional arguments.
• Language codes can be provided as a comma-separated list with --languages.

Supported Output Formats

• json: Raw transcript as JSON
• text: Plain text transcript
• srt: SubRip subtitle format
• webvtt: Web Video Text Tracks format
• pretty: Human-readable pretty print

Contributing

Contributions are welcome! To contribute:

• Fork the repository and create your branch.
• Make your changes with clear commit messages.
• Ensure all tests pass (npm test).
• Submit a pull request describing your changes.

For major changes, please open an issue first to discuss what you would like to change.

Support / Contact

• For bug reports or feature requests, please open an issue on GitHub.
• For questions, suggestions, or sponsorship, contact the author via GitHub or use the GitHub Sponsor button.

License

MIT

Author

Chintamani Pala