YouTube Transcript NPM Package — JavaScript & TypeScript SDK
Extract YouTube transcripts programmatically in your Node.js applications. Install from NPM, authenticate with your API key, and start transcribing videos in minutes.
INSTALLATION
npm install youtube-transcript-api pnpm add youtube-transcript-api yarn add youtube-transcript-api
QUICK START
import { YouTubeTranscript } from "youtube-transcript-api";
const yt = new YouTubeTranscript({ apiKey: "your_api_key" });
const result = await yt.getTranscript("dQw4w9WgXcQ");
console.log(result.data?.transcript.text);FEATURES
Full V2 API Coverage
Transcribe, batch, jobs, polling — every endpoint wrapped.
TypeScript-First
Complete type definitions with IntelliSense support.
Zero Dependencies
Uses native fetch. Node 18+ only, no bloat.
Typed Errors
Granular error classes for every API error code.
Built-in Polling
waitForJob helper for async ASR transcription.
ESM & CommonJS
Works in both module systems out of the box.
TRANSCRIBE WITH OPTIONS
const result = await yt.transcribe({
video: "dQw4w9WgXcQ",
language: "fr",
source: "manual",
format: {
timestamp: true,
paragraphs: true,
words: false,
},
});
console.log(result.status); // "completed"
console.log(result.data?.transcript.text); // Full transcript text
console.log(result.data?.transcript.language); // "fr"
console.log(result.data?.transcript.segments); // Timestamped segments
console.log(result.credits_used); // Credits consumedBATCH PROCESSING (UP TO 100 VIDEOS)
const result = await yt.batch({
video_ids: ["dQw4w9WgXcQ", "jNQXAC9IVRw", "9bZkp7q19f0"],
format: { timestamp: true },
});
console.log(result.summary);
// { total: 3, succeeded: 3, failed: 0, processing: 0 }
for (const item of result.results) {
console.log(`${item.data?.video_id}: ${item.data?.transcript.text.slice(0, 100)}...`);
}ASR AUDIO TRANSCRIPTION
For videos without captions, use ASR to transcribe directly from audio. Supports webhook callbacks or built-in polling.
const result = await yt.transcribe({
video: "VIDEO_ID",
source: "asr",
allow_asr: true,
webhook_url: "https://yoursite.com/webhook",
});const result = await yt.transcribe({
video: "VIDEO_ID",
source: "asr",
allow_asr: true,
});
if (result.job_id) {
const final = await yt.waitForJob(result.job_id, {
interval: 5000,
maxAttempts: 60,
});
console.log(final.data?.transcript.text);
}const result = await yt.transcribe({
video: "VIDEO_WITHOUT_CAPTIONS",
source: "asr",
// allow_asr not set — V2 requires explicit confirmation
});
if (result.status === "requires_asr_confirmation") {
console.log(result.estimated_credits); // e.g. 5
console.log(result.duration_minutes); // e.g. 7.5
// User confirms → retry with allow_asr
const confirmed = await yt.transcribe({
video: "VIDEO_WITHOUT_CAPTIONS",
source: "asr",
allow_asr: true,
});
}ERROR HANDLING
import {
YouTubeTranscript,
InvalidRequestError,
AuthenticationError,
InsufficientCreditsError,
NoCaptionsError,
RateLimitError,
} from "youtube-transcript-api";
try {
await yt.getTranscript("invalid");
} catch (error) {
if (error instanceof AuthenticationError) {
console.log("Bad API key");
} else if (error instanceof InsufficientCreditsError) {
console.log("Top up at https://youtubetranscript.dev/pricing");
} else if (error instanceof NoCaptionsError) {
console.log("No captions — try source: 'asr' with allow_asr: true");
} else if (error instanceof RateLimitError) {
console.log(`Rate limited. Retry after ${error.retryAfter}s`);
}
}CONFIGURATION
const yt = new YouTubeTranscript({
apiKey: "your_api_key",
baseUrl: "https://...", // Override API base URL
timeout: 60_000, // Request timeout in ms (default: 30s)
});Requires Node.js 18+ (uses native fetch). Get your API key from youtubetranscript.dev/dashboard/account.
OTHER SDKs & TOOLS
WHEN TO USE WHAT
NPM Package
Best for Node.js applications, server-side rendering, CLI tools, and automated scripts where you need programmatic access.
REST API
Best for non-JavaScript environments, one-off requests, and when you need language-agnostic HTTP access.
MCP Server
Best for AI coding assistants like Claude, Cursor, and VS Code Copilot where you want natural language interaction.
FREQUENTLY ASKED QUESTIONS
Is the NPM package free to use?+
The package itself is free to install. You need a YouTubeTranscript.dev API key to make requests. API keys are available on all paid plans.
Does it work in the browser?+
The package is designed for Node.js server-side use. For browser-based extraction, use our REST API directly with fetch or axios.
What Node.js versions are supported?+
Node.js 18 and above. The package uses native fetch and modern JavaScript features.
Can I use it with Deno or Bun?+
Yes, the package is compatible with Deno and Bun runtimes that support NPM packages.
Start Building with the NPM Package
Install in seconds. Full TypeScript support. Comprehensive documentation.
VIEW ON NPM →