Repository navigation
Releases
v2.0.0 — dual ESM/CJS build + critical import fixes
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
exportsmap was restructured:importresolves the ESM build,requireresolves 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:
importfrom a"type": "module"project no longer fails withERR_MODULE_NOT_FOUND(compiled ESM emitted extensionless relative re-exports). - Critical:
new YouTubeTranscriptApi()no longer throwsrequire is not definedin ESM (require('http')/require('https')in an ES module). - Robust
ytInitialPlayerResponseand 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 raisesNoTranscriptFound. - Typed error mapping:
IpBlocked(403),VideoUnavailable(404/410), and a retryableRequestFailed(429 / transport failures / 5xx, carryingcause). - 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.
axiosbumped 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/clitype-resolution check. - CI matrix (Node 18/20/22), husky pre-commit/pre-push hooks, a
filesallowlist, and anenginesfloor. - Exported option and transcript types plus the new
RequestFailederror.
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
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-agentandhttps-proxy-agentpackages for proxy support
Full Changelog: v1.2.0...v1.3.0
v1.2.0
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
IpBlockederror type for rate limiting scenarios
Full Changelog: v1.1.0...v1.2.0
v1.1.0
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
Full Changelog: https://github.com/wickes1/youtube-transcript-ts/commits/v1.0.0