Skip to content

Releases

v2.0.0 — dual ESM/CJS build + critical import fixes

Choose a tag to compare

@wickes1 wickes1 released this 08 Jun 16:05

A remediation release. 1.x was not importable in standard Node ESM; this release fixes that and ships a proper dual ESM/CJS build, plus parsing, security, and type-surface hardening.

⚠️ Breaking

  • The exports map was restructured: import resolves the ESM build, require resolves the CJS build, and TypeScript resolves the matching declarations for each.
  • fetchTranscript(id, ['en'], false, 'text') → options object: fetchTranscript(id, { languages: ['en'], formatter: 'text' }). The positional form still works but is deprecated.
  • Requires Node >= 18.

Fixed

  • Critical: import from a "type": "module" project no longer fails with ERR_MODULE_NOT_FOUND (compiled ESM emitted extensionless relative re-exports).
  • Critical: new YouTubeTranscriptApi() no longer throws require is not defined in ESM (require('http')/require('https') in an ES module).
  • Robust ytInitialPlayerResponse and captions extraction via a string/escape-aware brace-depth scanner that survives }; inside JSON string values.
  • Correct caption decode order (escaped </> no longer drop cues); a transcript that parses to zero snippets now raises NoTranscriptFound.
  • Typed error mapping: IpBlocked (403), VideoUnavailable (404/410), and a retryable RequestFailed (429 / transport failures / 5xx, carrying cause).
  • Cache hits no longer make a network round-trip; the HTML and transcript caches are LRU-bounded (cache.maxSize, default 100).

Security

  • Invidious caption-URL SSRF hardening: origin-pinned, absolute-URL override and redirects disabled, private/loopback/link-local hosts blocked.
  • ReDoS-bounded caption tag stripping with a per-snippet length cap.
  • axios bumped to ^1.17.0, clearing known runtime advisories on the proxy/redirect paths.

Added

  • Dual ESM + CJS build via tsup, a post-build ESM/CJS smoke gate, and an @arethetypeswrong/cli type-resolution check.
  • CI matrix (Node 18/20/22), husky pre-commit/pre-push hooks, a files allowlist, and an engines floor.
  • Exported option and transcript types plus the new RequestFailed error.

Verified: 80 tests, attw clean across node10 / node16-CJS / node16-ESM / bundler, npm audit --prod clean, and a real packed-tarball consumer imports by name in both ESM and CJS.

v1.3.0

Choose a tag to compare

@wickes1 wickes1 released this 27 Mar 20:37

YouTube Transcript API v1.3.0

New Features

HTTP/HTTPS Proxy Support 🌐

You can now configure HTTP and HTTPS proxies for all API requests:

// Configure separate proxies for HTTP and HTTPS
const api = new YouTubeTranscriptApi({
  proxy: {
    enabled: true,
    http: 'http://http-proxy-server.com:8080',
    https: 'http://https-proxy-server.com:8443',
  },
});

// Or set the same proxy for both
api.setProxyOptions({
  enabled: true,
  http: 'http://username:password@proxy.com:8080',
  https: 'http://username:password@proxy.com:8080',
});

This feature is particularly useful for:

  • Bypassing network restrictions
  • Routing requests through specific servers
  • Adding an extra layer of privacy

Breaking Changes

Batch Transcript Fetching Removed ⚠️

The fetchTranscripts method has been removed as it was not properly implemented. If you were using this functionality, you'll need to implement your own solution using the single fetchTranscript method:

// Before (no longer works)
const { results, errors } = await api.fetchTranscripts(['VIDEO_ID_1', 'VIDEO_ID_2']);

// After (implement your own batch processing)
const results = {};
const errors = {};

for (const videoId of ['VIDEO_ID_1', 'VIDEO_ID_2']) {
  try {
    results[videoId] = await api.fetchTranscript(videoId);
  } catch (error) {
    errors[videoId] = error;
  }
}

Dependencies

  • Added http-proxy-agent and https-proxy-agent packages for proxy support

Full Changelog: v1.2.0...v1.3.0

v1.2.0

Choose a tag to compare

@wickes1 wickes1 released this 27 Mar 18:07

v1.2.0

Features

  • Invidious Proxy Support: Access transcripts via Invidious when YouTube API access is restricted

    const api = new YouTubeTranscriptApi({
      cache: {
        enabled: true,
        maxAge: 1000 * 60 * 60 * 24 * 30, // 30 days
      },
      logger: {
        enabled: true,
        namespace: "youtube-transcript",
      },
      invidious: {
        enabled: true,
        instanceUrls: 'https://yewtu.be'
      }
    });
  • Multiple Fallback Instances: Configure multiple Invidious instances for reliability

    invidious: {
      enabled: true,
      instanceUrls: ['https://yewtu.be']
    }
  • Dynamic Invidious Configuration:

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

Self-Hosting Note

If self-hosting Invidious for transcript fetching, set use_innertube_for_captions: true in your Invidious configuration file.

Improvements

  • Enhanced error handling for region-restricted videos
  • Automatic fallback between YouTube and Invidious
  • Added WebVTT format parsing support
  • Added IpBlocked error type for rate limiting scenarios

Full Changelog: v1.1.0...v1.2.0

v1.1.0

Choose a tag to compare

@wickes1 wickes1 released this 27 Mar 18:02

v1.1.0

Breaking Changes

  • Constructor Signature Change: The API constructor now takes a single options object instead of separate parameters

    // Before (v1.0.0)
    const api = new YouTubeTranscriptApi(
      // Cache options as first parameter
      {
        enabled: true,
        maxAge: 1000 * 60 * 60 * 24 * 30, // 30 days
      },
      // Logger options as second parameter
      {
        enabled: true,
        namespace: "youtube-transcript",
      }
    );
    
    // After (v1.1.0)
    const api = new YouTubeTranscriptApi({
      // All options in a single object
      cache: {
        enabled: true,
        maxAge: 1000 * 60 * 60 * 24 * 30, // 30 days
      },
      logger: {
        enabled: true,
        namespace: "youtube-transcript",
      }
    });
  • Error Handling: Updated error hierarchy with more specific error types

Improvements

  • Improved performance with optimized caching
  • Better metadata extraction
  • Enhanced error reporting with more specific error types

v1.0.0

Choose a tag to compare

@wickes1 wickes1 released this 20 Mar 22:49