حزمة NPM لنصوص فيديوهات YouTube: SDK للغتَي JavaScript وTypeScript
استخرج نصوص فيديوهات YouTube برمجيًا في تطبيقات Node.js. ثبّت الحزمة من 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.
استطلاع دوري مدمج
الدالة المساعدة waitForJob لتفريغ ASR غير المتزامن.
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 للتفريغ مباشرةً من الصوت. يدعم استدعاءات Webhook أو الاستطلاع الدوري المدمج.
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 والعرض من جهة الخادم وأدوات سطر الأوامر والسكربتات المؤتمتة التي تحتاج فيها إلى وصول برمجي.
REST API
الأفضل للبيئات غير المعتمدة على JavaScript والطلبات لمرة واحدة، وعندما تحتاج إلى وصول HTTP مستقل عن لغة البرمجة.
خادم MCP
الأفضل لمساعدي البرمجة بالذكاء الاصطناعي مثل Claude وCursor وVS Code Copilot عندما تريد التفاعل باللغة الطبيعية.
الأسئلة الشائعة
هل حزمة NPM مجانية الاستخدام؟+
تثبيت الحزمة نفسها مجاني، لكنك تحتاج إلى مفتاح API من YouTubeTranscript.dev لإرسال الطلبات. مفاتيح API متاحة في جميع الخطط المدفوعة.
هل تعمل في المتصفح؟+
صُممت الحزمة للاستخدام من جهة الخادم في Node.js. للاستخراج من المتصفح، استخدم REST API الخاصة بنا مباشرةً عبر fetch أو axios.
ما إصدارات Node.js المدعومة؟+
Node.js 18 وما بعده. تستخدم الحزمة fetch الأصلية ومزايا JavaScript الحديثة.
هل يمكنني استخدامها مع Deno أو Bun؟+
نعم، الحزمة متوافقة مع بيئتَي تشغيل Deno وBun اللتين تدعمان حزم NPM.
ابدأ البناء باستخدام حزمة NPM
ثبّتها في ثوانٍ. دعم كامل لـ TypeScript. توثيق شامل.
اطّلع عليها في NPM ←