التنزيل الأساسي
بلا أي خيارات، يختار yt-dlp أفضل تركيبة يستطيع دمجها ويسمّي الملف باسم العنوان. ومن المدهش كم مرة يكون هذا هو الأمر الصحيح فعلًا.
yt-dlp URL
قبل تنزيل شيء كبير، يستحق الأمر أن ترى ما هو متاح حقًا. هذا يطبع جدول الصيغ ثم ينتهي دون تنزيل أي شيء.
yt-dlp -F URL
العمود الأيسر في ذلك الجدول هو معرّف الصيغة، ويمكنك بعدها طلبه مباشرة. ومعرّفان موصولان بـ + يعنيان «نزّل كليهما وادمجهما».
yt-dlp -f 137+140 URL
الجودة واختيار الصيغة
معرّفات الصيغ المكتوبة بشكل ثابت تنكسر لحظة تغيير الموقع لسلّم الترميز عنده. تعبير المحدِّد هو النسخة التي تدوم: اطلب الخصائص التي تريدها ودع yt-dlp يبحث عن أفضل تطابق.
yt-dlp -f "bv*[height<=1080]+ba/b[height<=1080]" URL
اقرأه هكذا: أفضل مسار فيديو لا يزيد ارتفاعه على 1080 مع أفضل صوت، وإن لم يوجد هذا الزوج فأفضل ملف مفرد لا يزيد ارتفاعه على 1080. وهذا البديل بعد الشرطة المائلة هو ما يمنع فشل الأمر على المواقع التي تنشر مسارات تقدمية فقط.
دمج مسارين ينتج حاوية يتعين على yt-dlp اختيارها. MP4 يعمل في كل مكان؛ أما MKV فيقبل كل ما تلقيه فيه، وهذا يهم بمجرد دخول الترجمات والفصول في الحساب.
yt-dlp -f "bv*+ba" --merge-output-format mp4 URL
وللتعبير عن تفضيل بدل حدٍّ صارم، رتّب بدل أن تُرشّح. هذا يفضّل 1080p و MP4 لكنه ينزّل شيئًا رغم ذلك حين لا يتوفر أي منهما.
yt-dlp -S "res:1080,ext:mp4" URL
الصوت و MP3
استخراج الصوت يحتاج إلى ffmpeg — وهذا هو السبب الأكثر شيوعًا بفارق كبير لفشل الأمر أدناه على تنصيب جديد.
yt-dlp -x --audio-format mp3 URL
إضافة صورة الغلاف والوسوم تكلّف رايتين إضافيتين فقط، وتجعل الناتج صالحًا لمكتبة موسيقية بدل أن يكون مجلدًا من ملفات بلا هوية.
yt-dlp -x --audio-format mp3 --audio-quality 0 --embed-thumbnail --embed-metadata URL
--audio-quality 0 يعني معدل بت متغيرًا عند أفضل ضبط، لا «جودة صفر». وإن كنت تحتاج معدلًا ثابتًا فحدّده: --audio-quality 320K.
حين يكون المصدر أصلًا AAC أو Opus، فالتحويل إلى MP3 يعيد الترميز ويفقد الجودة بلا مقابل. والإبقاء على الأصل أسرع وأفضل معًا.
yt-dlp -x --audio-format best URL
الترجمات
الترجمات المضمّنة تسافر مع الملف؛ وملفات .srt المنفصلة أسهل في التحرير وفي تمريرها إلى شيء آخر.
yt-dlp --embed-subs --sub-langs en URL yt-dlp --write-subs --sub-langs en,vi --convert-subs srt URL
الترجمات المولّدة آليًا مفتاح منفصل. وبدونه، الفيديو الذي لا يملك ترجمة بشرية لا ينتج شيئًا على الإطلاق، ولا يعطي خطأ.
yt-dlp --write-auto-subs --sub-langs en --convert-subs srt --skip-download URL
قوائم التشغيل والقنوات
رابط YouTube ينتمي غالبًا إلى فيديو وقائمة تشغيل في الوقت نفسه، ويضطر yt-dlp إلى تخمين أيهما قصدت. قل ذلك صراحة.
yt-dlp --no-playlist URL yt-dlp --yes-playlist URL
ولأي شيء طويل، ملف الأرشيف يهم أكثر من أي خيار آخر هنا: فهو يسجّل ما جرى تنزيله، بحيث تستأنف الإعادة من حيث توقفت بدل أن تبدأ من الصفر.
yt-dlp --yes-playlist -i \ --download-archive archive.txt \ -o "%(playlist_index)02d - %(title)s.%(ext)s" \ URL
وبضمّه إلى -i، لم يعد فيديو واحد محجوب جغرافيًا أو محذوف يوقف المئتين الباقية. ولأخذ شريحة بدل الكل، يقبل -I النطاقات والقوائم: -I 1:10، -I "1,3,7-10".
المقاطع والفصول ولقطات الرعاية
يمكنك تنزيل جزء من الفيديو بدل تنزيله كاملًا. النجمة في البداية تعني طابعًا زمنيًا لا اسم فصل، وعلامتا الاقتباس إلزاميتان — إذ يوسّع bash النجمة * العارية مقابل أسماء ملفاتك.
yt-dlp --download-sections "*00:01:30-00:03:00" URL
يستخدم SponsorBlock علامات يرسلها المجتمع ليقتطع المقاطع كليًا، أو ليتركها فصولًا تتخطاها أنت بنفسك.
yt-dlp --sponsorblock-remove default URL yt-dlp --sponsorblock-mark all --embed-chapters URL
أسماء الملفات والمجلدات
قالب الإخراج يتحكم في الاثنين معًا. والشرطة المائلة تنشئ مجلدًا، فقالب واحد يكفي لترتيب أرشيف كامل.
yt-dlp -o "%(uploader)s/%(upload_date>%Y-%m-%d)s - %(title)s.%(ext)s" URL
العناوين تحتوي بانتظام على محارف ترفضها بعض أنظمة الملفات. و--restrict-filenames يردّ كل شيء إلى ASCII بسيط، وهو أمر يستحق العناء لأي شيء سيُنقل بين الأجهزة.
في ملف .bat على Windows يجب مضاعفة كل % — %%(title)s — وإلا التهم مفسّر الدفعات القالب قبل أن يراه yt-dlp. والمولّد يقوم بهذا نيابةً عنك حين تنزّل ملف .bat.
الأخطاء التي ستصادفها فعلًا
ffmpeg not found
كل ما يدمج أو يحوّل أو يضمّن أو يقتطع يحتاج إلى ffmpeg في مسار PATH لديك. ثبّته ثم تأكد بـ ffmpeg -version.
Sign in to confirm you are not a bot
جرّب --impersonate chrome أولًا، ثم --cookies-from-browser. وإن فشل الاثنان فحدّث yt-dlp — فهذا الفحص بالذات يتغير كثيرًا وعادةً ما يصل حله في إصدار خلال أيام.
Unable to extract player response
يكون السبب دائمًا تقريبًا نسخة قديمة من yt-dlp. حدّثه قبل أن تغيّر أي شيء آخر: yt-dlp -U، أو مدير الحزم لديك إن كنت ثبّته بتلك الطريقة.
Requested format is not available
محدِّدك لم يطابق شيئًا. شغّل -F لترى ما هو موجود، وفضّل الترتيب (-S) على الترشيح الصارم كي يبقى هناك بديل دائمًا.
HTTP Error 403
ذلك الرابط وُقّع لجلسة أخرى أو منطقة أخرى. أعد التشغيل بكوكيز جديدة، أو أضف --impersonate chrome، أو جرّب --geo-bypass.
إبقاء yt-dlp محدّثًا
عدد الأعطال المبلّغ عنها التي يصلحها التحديث أكبر من عدد ما تصلحه أي راية. إن كنت ثبّت الملف التنفيذي المستقل:
yt-dlp -U
وإن ثبّته عبر مدير حزم فحدّثه بالطريقة نفسها التي ثبّته بها — سيرفض -U، وهو محق في رفضه.