Package Exports

youtube-captions-api
youtube-captions-api/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (youtube-captions-api) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

youtube-captions-api

A reliable, self-contained Node.js/TypeScript port of the popular Python youtube-transcript-api (as of December 2025).

This is mostly an AI-generated port (created with assistance from Grok by xAI), faithfully replicating the Python library's core logic, error handling, consent handling, and reliability.

Fetches timed transcripts (manual or auto-generated) using YouTube's internal Innertube API — no official API key required.

Warning: This uses undocumented endpoints. It may break if YouTube changes their internals.

Features

Instance-based API (new YouTubeTranscriptApi())
fetch(videoIdOrUrl, { languages }) → timed segments with start/duration
Language priority (prefers manual captions over auto-generated)
Consent cookie handling
Proxy support for production/cloud use
Full concatenated text via .getText()
Debug logging of transcript URL
Minimal dependencies (only undici)

Installation

npm install youtube-captions-api

Usage

import YouTubeTranscriptApi from 'youtube-captions-api';

(async () => {
  try {
    // Optional: use a residential proxy for cloud deployments (highly recommended)
    // const api = new YouTubeTranscriptApi('http://user:pass@residential-ip:port');

    const api = new YouTubeTranscriptApi();

    const transcript = await api.fetch('dQw4w9WgXcQ', {
      languages: ['en'], // priority list – falls back automatically
    });

    // First timed segment
    console.log(transcript.snippets[0]);
    // → { text: "We're no strangers to love", start: 12.5, duration: 3.2 }

    // Full concatenated text
    console.log(transcript.getText());

    // Metadata
    console.log('Language:', transcript.language_code);
    console.log('Auto-generated:', transcript.is_generated);
    console.log('Segments count:', transcript.snippets.length);
  } catch (err) {
    console.error(err instanceof Error ? err.message : err);
  }
})();

Express Server Example

See server.js in the repo for a ready-to-run API endpoint:

GET /transcript?id=dQw4w9WgXcQ
→ { video_id, text, language, timed_segments: [{ timestamp, seconds, text }, ...] }

Run:

npm run build
node server.js

Test: http://localhost:3000/transcript?id=dQw4w9WgXcQ

Production Notes

Works reliably locally on residential IPs.
In cloud/server environments, YouTube frequently blocks datacenter IPs → use rotating residential proxies (e.g., Webshare, Bright Data, Oxylabs).
Simply pass the proxy URL to the constructor when deploying.

License

MIT

Inspired by the excellent Python original — huge thanks to jdepoix!