YouTube 스크립트 NPM 패키지: JavaScript & TypeScript SDK
Node.js 애플리케이션에서 프로그래밍 방식으로 YouTube 스크립트를 추출하세요. NPM에서 설치하고 API 키로 인증하면 몇 분 만에 동영상 전사를 시작할 수 있습니다.
설치
npm install youtube-transcript-api pnpm add youtube-transcript-api yarn add youtube-transcript-api
빠른 시작
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);기능
V2 API 전체 지원
전사, 일괄 처리, 작업, 폴링까지 모든 엔드포인트를 래핑했습니다.
TypeScript 우선
IntelliSense를 지원하는 완전한 타입 정의를 제공합니다.
의존성 제로
네이티브 fetch를 사용합니다. Node 18 이상 전용이며 군더더기가 없습니다.
타입이 지정된 오류
모든 API 오류 코드에 대응하는 세분화된 오류 클래스를 제공합니다.
내장 폴링
비동기 ASR 전사를 위한 waitForJob 헬퍼를 제공합니다.
ESM & CommonJS
두 모듈 시스템 모두에서 바로 작동합니다.
옵션과 함께 전사하기
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 consumed일괄 처리 (최대 100개 동영상)
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 오디오 전사
자막이 없는 동영상은 ASR로 오디오에서 직접 전사하세요. 웹훅 콜백 또는 내장 폴링을 지원합니다.
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,
});
}오류 처리
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`);
}
}구성
const yt = new YouTubeTranscript({
apiKey: "your_api_key",
baseUrl: "https://...", // Override API base URL
timeout: 60_000, // Request timeout in ms (default: 30s)
});Node.js 18 이상이 필요합니다(네이티브 fetch 사용). API 키 발급 위치: youtubetranscript.dev/dashboard/account.
기타 SDK 및 도구
상황별 선택 가이드
NPM 패키지
프로그래밍 방식의 접근이 필요한 Node.js 애플리케이션, 서버 사이드 렌더링, CLI 도구, 자동화 스크립트에 가장 적합합니다.
REST API
JavaScript 이외의 환경, 일회성 요청, 언어에 구애받지 않는 HTTP 접근이 필요할 때 가장 적합합니다.
MCP 서버
자연어로 상호작용하고 싶은 Claude, Cursor, VS Code Copilot 같은 AI 코딩 어시스턴트에 가장 적합합니다.
자주 묻는 질문
NPM 패키지는 무료인가요?+
패키지 자체는 무료로 설치할 수 있습니다. 요청을 보내려면 YouTubeTranscript.dev API 키가 필요하며, API 키는 모든 유료 플랜에서 제공됩니다.
브라우저에서도 작동하나요?+
이 패키지는 Node.js 서버 사이드 환경을 위해 설계되었습니다. 브라우저 기반 추출에는 fetch나 axios로 REST API를 직접 사용하세요.
어떤 Node.js 버전을 지원하나요?+
Node.js 18 이상을 지원합니다. 패키지는 네이티브 fetch와 최신 JavaScript 기능을 사용합니다.
Deno나 Bun에서도 사용할 수 있나요?+
네, NPM 패키지를 지원하는 Deno 및 Bun 런타임과 호환됩니다.