تخطَّ إلى المحتوى
AR
الحصول على مفتاح API
تصفح الوثائق

الأدلة

واجهة Python في yt-dlp

أمثلة Python قابلة للتشغيل للتنزيل والبيانات الوصفية ومجموعات بيانات الذكاء الاصطناعي والمهام القابلة للاستئناف.

في هذه الصفحة

تثبيت مكتبة Python

في بيئتك Python 3.11+
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"

ثبّت أيضًا Deno وFFmpeg وffprobe. تعمل الأمثلة محليًا على Linux وmacOS وWindows دون مفتاح API. اجعل الملفات التنفيذية متاحة عبر PATH في بيئة التنزيل.

تحميل أول فيديو

تحميل الفيديو واحد
from yt_dlp import YoutubeDL
from yt_dlp.networking.impersonate import ImpersonateTarget

options = {
    "js_runtimes": {"deno": {}},
    "impersonate": ImpersonateTarget(),
    "concurrent_fragment_downloads": 1,
    "noplaylist": True,
    "outtmpl": "downloads/%(id)s.%(ext)s",
    "format": "bv*[height<=1080]+ba/b[height<=1080]",
}
with YoutubeDL(options) as downloader:
    downloader.download(["https://www.youtube.com/watch?v=jNQXAC9IVRw"])
هذا يكتب وسائل الإعلام المحلية حتى 1080p ويمكن دمج تدفقات منفصلة.

لا تتراث إعدادات CLI. إعداد Deno، وتصميم وارتباط في خيارات Python، حتى عندما تستخدم الأوامر النهائية بالفعل.

download() يأخذ قائمة من عناوين URL ويعيد رمز الحالة. extract_info(url، download=True) يعود معلومات الاستخراج وكذلك إجراء التنزيل. استخدم مدير السياق لإغلاق المثال نظيفا، وخلق مثالا طازجة للعمل المستقل بدلا من مشاركة حالة متغيرة عبر الأسلاك.

قراءة البيانات بدون وسائل الإعلام

تصدير سجلات متايدات صغيرة
import json
from yt_dlp import YoutubeDL
from yt_dlp.networking.impersonate import ImpersonateTarget

url = "https://www.youtube.com/watch?v=jNQXAC9IVRw"
options = {
    "js_runtimes": {"deno": {}},
    "impersonate": ImpersonateTarget(),
    "noplaylist": True,
    "sleep_interval_requests": 3,
}
with YoutubeDL(options) as downloader:
    info = downloader.sanitize_info(downloader.extract_info(url, download=False))

record = {key: info.get(key) for key in (
    "id", "webpage_url", "title", "channel_id", "duration", "upload_date"
)}
print(json.dumps(record, ensure_ascii=False, indent=2))
تحميل=False لا يزال يقوم بتنفيذ طلبات الشبكة. sanitize_info يجعل النتيجة متوافقة مع JSON؛ فإنه لا يصدر أسرار أو يقلل من النتيجة إلى هذه الحقول.

يمكن أن تكون الحقول المستخرجة غائبة أو صفر. استخدم Get() للحصول على البيانات الميتا إختيارية، ولا تفترض أن كل مصدر لديه مدة أو معرف القناة أو قائمة تنسيقات كاملة. كما أن قائمة القائمة المسطحة تختلف عن مقطع فيديو معلول بالكامل. للحصول على استجابة عامة، تخطي فقط الحقول التي تريد عرضها.

تجنب استخراج البيانات الميتا على الفور تليها استخراج تنزيل مماثل لكل مصدر ما لم تحتاج تطبيقك إلى خطوة التخطيط الإضافية. يكرر طلبات المصدر. إذا كنت بحاجة إلى وظيفة دائمة، تخزين معرف المصدر وسياسة النتيجة؛ عنوان URL الموقعة من البيانات الميتاتية ليست بديلا دائم للمصدر الأصلي.

Python الخيارات المرجعية

المهامPython الخياراتالتفاصيل
دليل النتيجة و اسم الفيلم"outtmpl": "downloads/%(id)s.%(ext)s"الحفاظ على معرف المصدر والتمديد الديناميكي.
سقف صعب 1080p"format": "bv*[height<=1080]+ba/b[height<=1080]"يسمح بترشيحات المصدر وتفشل إذا لم يتوافق أحد مع الحدود.
متايتات الجانب"writeinfojson": Trueيضع متايدات الاستخراج الكاملة بجانب وسائل الإعلام.
نقطة التحقق الكاملة"download_archive": "archive.txt"ملف واحد لكل سياسة الإنتاج، وليس ملف التفتيش.
أخطاء صارمة"ignoreerrors": Falseاترك المكالمة تسجيل الفشل بدلا من التعامل مع مشاكل ما بعد المعالجة كإنجاز.
دينا Runtime"js_runtimes": {"deno": {}}قم بتثبيت Deno في العامل وجعل ثنائيه مرئيًا على PATH.
براءة اختراع"impersonate": ImpersonateTarget()Python معادل --impersonate="؛ استيراد الفئة المستهدفة وتثبيت curl-cffi.
ملف الكوكيز الحالي"cookiefile": "private/youtube-cookies.txt"استخدم شهادات الجلسة الخاصة فقط عندما يكون ذلك ضروريًا للوصول.
MP3 خيارات التحويل
audio_options = {
    "format": "ba",
    "outtmpl": "audio/%(id)s.%(ext)s",
    "postprocessors": [{
        "key": "FFmpegExtractAudio",
        "preferredcodec": "mp3",
        "preferredquality": "192",
    }],
}
يُمكن أن يُدخل audio_options إلى YoutubeDL. يُمكن أن يُدخل FFmpeg ما بعد المعالج إلى معدل بيت المستهدف 192 كيلو بايت في الثانية؛ فإنه لا يحسن الجودة الأصلية للمصدر.

الفيديو + الصوت + الكمبيوتر لـ AI

استخدم هذا سياسة النتيجة عندما يكون الهدف هو مجموعة بيانات التدريب بدلاً من مجموعة 1080p من نموذج العامل. فإنه يتطلب أفضل الفيديو والفيديو، ويسمح FFmpeg لدمجها في MP4، ويخزن المقبرات الإنجليزية المتاحة والبيانات الميتا بجانب وسائل الإعلام.

إعداد واحد في Python
from yt_dlp import YoutubeDL
from yt_dlp.networking.impersonate import ImpersonateTarget

url = "https://www.youtube.com/watch?v=jNQXAC9IVRw"
options = {
    "js_runtimes": {"deno": {}},
    "impersonate": ImpersonateTarget(),
    "noplaylist": True,
    "format": "bestvideo+bestaudio/best",
    "merge_output_format": "mp4",
    "postprocessors": [{
        "key": "FFmpegVideoRemuxer",
        "preferedformat": "mp4",
    }],
    "outtmpl": "dataset/%(id)s/%(id)s.%(ext)s",
    "writeinfojson": True,
    "writesubtitles": True,
    "writeautomaticsub": True,
    "subtitleslangs": ["en"],
    "subtitlesformat": "vtt/best",
    "sleep_interval_requests": 2,
    "sleep_interval_subtitles": 5,
    "sleep_interval": 5,
    "max_sleep_interval": 10,
    "concurrent_fragment_downloads": 1,
    "retries": 3,
    "fragment_retries": 3,
}
with YoutubeDL(options) as downloader:
    downloader.download([url])
يتطلب FFmpeg/ffprobe، Deno، والليلة [المعيارcurl-cffi] التثبيت.يتم عرض المعيار المفضل للفرم من remuxer بهذه الطريقة في API yt-dlp.

يختار ImpersonateTarget() أي هدف متاح للمتصفح، يتوافق مع --impersonate="". اجتياز الكائن، وليس سلك فارغ نسخ من CLI syntax. curl-cffi يجب أن تكون مثبتة في هذا البيئة Python. لا يزال Deno يعمل على حل JavaScript ؛ لا يحل محلها من قبل impersonation.

MP4 هو حاوية الإنتاج؛ يمكن أن يكون الفيديو المختار AV1 أو VP9. إذا كان مدرب التدريب الخاص بك يتطلب H.264/AAC، تطبيق سياسة التشفير الصريحة قبل دمج أو تسجيل ترانسكود منفصل FFmpeg. يتم استرداد العناوين الفرعية المتاحة ، وليس من الكلام.

بعد أن انتهى الإعلامما يحتاجه سجلات البيانات
انظروا إلى النهاية MP4 مع ffprobeVideo/audio الكوديك، مدة، الأبعاد، مسار الملفات، وبايت العد.
تحقق من كلمات الجانب بشكل منفصلاللغة، supplied/automatic المسار، علامات الزمن وما إذا كان الملف موجودا فعلا.
لا توجد مقاعد متوافقة متوفرةالحفاظ على وسائل الإعلام وتحديد النص المفقود؛ إرسال الصوت إلى مرحلة الترجمة الخاصة بك إذا لزم الأمر.
كلمات مفتاحية 429استرداد العلامة بعد انخفاض IP مع التخفيضات الفرعية؛ لا تحميل إعادة وسائل الإعلام المكتملة.

للحصول على مجموعة، استخدم أرشيفًا منفصلًا لهذا سياسة مجموعة البيانات والحفاظ على مستند للصفحات المطلوبة. لا تستخدم مرة أخرى 1080p أو الأرشيف الوحيد لوسائل الإعلام: قد يقطع الفيديوهات قبل جمع مقاطع الفيديو المطلوبة حديثا. استخدم after_move لإعداد وسائل الإعلام، ثم تأكيد النص والبيانات الميتا قبل نشر عنصر مجموعة بيانات كاملة.

تعرف على متى يكون الملف النهائي جاهزًا

تحديث التقدم هوك = النهائي يعني التحويل النهائي. FFmpeg قد لا يزال من الضروري الجمع بين الفيديو والصوت، وتحويل ملف الصوت، أو تحريك النتيجة. إن تسجيل الفيديو فقط يصل إلى 100% ليس حدث الانتهاء الذي ينبغي أن ينشره تطبيقك.

المرحلةما تعرفهدولة التطبيق
تحميلبعض أشرطة الإعلام تصل.الركض
النقل الداكن: انتهىهذا التحويل قد انتهى؛ لا يزال المعالجة قادرة على متابعة.المعالجة
after_move ما بعد المعالجوقد مر الملف بالحركة التالية المعالجة المعدلة والحركة النهائية.الملفات المحلية جاهزة
التحقق من النزاهة والنزاهةوجهتك لديها الكائن والتحقق المسجل.تسليم

ويُسجل المثال الكامل أدناه معالج بريد مخصص في after_move ويقرأ info["filepath"] هناك. يفتتح أن الملف موجود و غير مكتوب. هذا يمنع تخمين التمديد النهائي مع prepare_filename()، والتي يمكن أن تشير إلى اسم التحويل المسبق.

سجل كامل: عامل الفيديو الفردي

احفظ هذا ك download_video.py يقبل معرف الفيديو أو watch/Shorts/live/embed URL ويدخل playlist/channel. يستخدم كل استدعاء مثال واحد على YoutubeDL، والخروج المحدود من المتصفح، وأرشيف جمع محلي. تكرار إرجاع المصدر المكتمل تم التخلي عنه بدلا من الاعتقاد أن ملف جديد تم إنشاؤه.

download_video.py
import argparse
import json
import re
from pathlib import Path
from urllib.parse import parse_qs, urlparse

from yt_dlp import YoutubeDL
from yt_dlp.networking.impersonate import ImpersonateTarget
from yt_dlp.postprocessor.common import PostProcessor
from yt_dlp.utils import DownloadError, PostProcessingError


def watch_url(value):
    """Accept a video ID or a single YouTube video URL, never a playlist."""
    video_id = value
    if not re.fullmatch(r"[A-Za-z0-9_-]{11}", value):
        parsed = urlparse(value)
        parts = parsed.path.strip("/").split("/")
        host = (parsed.hostname or "").lower()
        if parsed.scheme not in {"http", "https"}:
            raise ValueError("Use a YouTube watch URL or 11-character video ID")
        if host in {"youtu.be", "www.youtu.be"}:
            video_id = parts[0]
        elif host in {"youtube.com", "www.youtube.com", "m.youtube.com"}:
            if parsed.path == "/watch":
                video_id = parse_qs(parsed.query).get("v", [""])[0]
            elif len(parts) == 2 and parts[0] in {"shorts", "live", "embed"}:
                video_id = parts[1]
            else:
                video_id = ""
        else:
            video_id = ""
    if not re.fullmatch(r"[A-Za-z0-9_-]{11}", video_id):
        raise ValueError("Expected one YouTube video, not a channel or playlist")
    return "https://www.youtube.com/watch?v=" + video_id


class FinalFile(PostProcessor):
    def __init__(self):
        super().__init__()
        self.result = None

    def run(self, info):
        path = Path(info["filepath"]).resolve()
        if not path.is_file() or path.stat().st_size == 0:
            raise PostProcessingError("Final media file is missing or empty")
        self.result = {
            "status": "completed", "video_id": info["id"],
            "title": info.get("title"), "duration": info.get("duration"),
            "path": str(path), "bytes": path.stat().st_size,
        }
        return [], info


def download_video(source, output="downloads"):
    url = watch_url(source)
    folder = Path(output).resolve()
    folder.mkdir(parents=True, exist_ok=True)
    final_file = FinalFile()
    options = {
        "js_runtimes": {"deno": {}},
        "impersonate": ImpersonateTarget(),
        "concurrent_fragment_downloads": 1,
        "noplaylist": True,
        "format": "bv*[height<=1080]+ba/b[height<=1080]",
        "outtmpl": str(folder / "%(id)s.%(ext)s"),
        "download_archive": str(folder / "archive.txt"),
        "writeinfojson": True,
        "ignoreerrors": False,
        "retries": 3, "fragment_retries": 3, "socket_timeout": 30,
        "sleep_interval_requests": 1,
        "sleep_interval": 5, "max_sleep_interval": 10,
    }
    with YoutubeDL(options) as downloader:
        downloader.add_post_processor(final_file, when="after_move")
        downloader.extract_info(url, download=True)
    if final_file.result is None:
        return {"status": "skipped", "source": url,
                "reason": "No new file recorded; check the archive"}
    return {**final_file.result, "source": url}


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("source", help="YouTube video URL or ID")
    parser.add_argument("--output", default="downloads")
    args = parser.parse_args()
    try:
        result = download_video(args.source, args.output)
    except (DownloadError, ValueError, OSError) as error:
        raise SystemExit(f"Job failed: {error}") from error
    print(json.dumps(result, ensure_ascii=False, indent=2))
يتوفر السيناريو الكامل أيضًا من الرابط المذكور أعلاه.إنه يمتلك النتيجة المحلية فقط ؛ إضافة فحوصات التشفير وتحميل السجلات في المرحلة التالية من تطبيقك.
ابدأ عمل واحد
python download_video.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --output downloads

يحتوي السجل المكتمل على عنوان URL المصدر الكاني، و ID الفيديو، والطريق النهائي وحجم بايت. سجل متسارع يعني عدم إعادة استدعاء الملف النهائي الجديد؛ توحيدها ضد الأرشيف والمخزون الحالي إذا كنت بحاجة إلى إثبات أن الملف لا يزال موجودا. لا يفحص الأرشيف وحده ما إذا كان المستخدم قد حذف أو نقل وسائل الإعلام في وقت لاحق.

أخطاء التعريفات: أخطاء extractor/download/post-processing، أخطاء القيمة للإدخال المرفوض، وخطط OSError لإخطاءات نظام الملفات المحلي. تعامل هذه الفصول على أنها فصول منفصلة في سجلات التطبيق الخاصة بك. رسائل الخطأ هي تشخيص مفيد، ولكن نصها ليس تقسيمًا مستقرًا منظمًا لكل فشل في YouTube.

سجل كامل: عمال المجموعة المتجددة

إدخال download_batch.py بجانب download_video.py. إنشاء UTF-8 urls.txt مع URL الفيديو أو ID واحد لكل خط. هذا يعمل عن قصد على التوالي ، لذلك يمتلك عملية واحدة السجلات والخروج. يكتب نتيجة كاملة أو مفقودة أو فاشلة لكل محاولة إدخال وخروج صفر عندما فشلت أي عنصر.

download_batch.py
import argparse
import json
from datetime import datetime, timezone
from pathlib import Path

from yt_dlp.utils import DownloadError
from download_video import download_video


def run_batch(manifest, output):
    folder = Path(output).resolve()
    folder.mkdir(parents=True, exist_ok=True)
    sources = list(dict.fromkeys(
        line.strip()
        for line in Path(manifest).read_text(encoding="utf-8-sig").splitlines()
        if line.strip() and not line.lstrip().startswith("#")
    ))
    counts = {"completed": 0, "skipped": 0, "failed": 0}
    with (folder / "attempts.jsonl").open("a", encoding="utf-8") as log:
        for source in sources:
            try:
                result = download_video(source, folder)
            except (DownloadError, ValueError, OSError) as error:
                result = {"source": source, "status": "failed",
                          "error_type": type(error).__name__, "error": str(error)}
            result["recorded_at"] = datetime.now(timezone.utc).isoformat()
            log.write(json.dumps(result, ensure_ascii=False) + "\n")
            log.flush()
            counts[result["status"]] += 1
    return counts


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("manifest", help="UTF-8 file, one video URL or ID per line")
    parser.add_argument("--output", default="collection")
    args = parser.parse_args()
    counts = run_batch(args.manifest, args.output)
    print(json.dumps(counts, indent=2))
    raise SystemExit(1 if counts["failed"] else 0)
ويحتفظ المرفق فقط attempts.jsonl بالتراجع كحاولات منفصلة. يتم إزالة الخطوط المزدوجة داخل بيان؛ يتم إزالة أرشيف التنزيل من خلال التحكم في الهوية الكاملة عبر الجولات.
إعادة تشغيل أو إعادة تشغيل نفس المجموعة
python download_batch.py urls.txt --output collection

يمر بعد كل سجل بحيث لا يترك انقطاع كل نتيجة مكسورة حتى النهاية. لا يزال هناك نافذة صغيرة بين المكتبة تسجيل أرشيفها وتطبيقك كتابة سجل محاولة. إذا كان هناك حادث يقع هناك ، يمكن أن يبلغ الجولة التالية عن الانسحاب. بالنسبة لخدمة، وافق filesystem/archive مع قاعدة بيانات العمل المستدامة بدلا من ادعاء هذا المثال الملف النصي هو التداول.

الحفاظ على attempts.jsonl خاصة: يمكن أن تشمل الأخطاء تفاصيل المصدر والطلب. إبلاغ المجموعات حسب الحالة، والتحقق من العناصر المفقودة، وإعادة تشغيل نفس المظاهر بعد حل مشكلة البيئة المشتركة. لا تضيف كل ID المفقود إلى أرشيف النجاح.

الإنتاج: المقاييس، الموعد النهائي والتخزين

يوتيوب ديل متزامنة. تشغيلها مباشرة داخل كتلة التداول على شبكة الإنترنت غير متزامن التي تتحول إلى حفل الأحداث التداول؛ حتى إزالة الشريط لا يجعل طلب المتصفح مدة حياة مناسبة لتحميل كبير. وقبل العمل، استمر في source/options، والسماح للعامل أن ينتج النتيجة النهائية.

  • إنشاء معرف وظيفة دائمة قبل التنفيذ.تخزين معرف الفيديو القنوني، سياسة النتيجة، رقم المحاولة والهدف.
  • استخدم السجلات العملية لكل وظيفة ومستشفى العمال المحدود.لا تشارك مثال YoutubeDL بين الوظائف المتنافسة.
  • استخدم عملية منفصلة عندما تحتاج إلى موعد أو إلغاء ساعة جدارية صعبة؛ socket_timeout يحد من عمليات الشبكة الفردية، وليس العمل بأكمله.
  • إذا تعرضت إدخال المستخدم على HTTP، وقبول المحددين فيديو يوتيوب المدعومة بدلا من عناوين URL العشوائية، وطرق النتيجة، وحجج المستخرج أو القطع الصنوبر.
  • تسجيل استعداد الملفات المحلية وإكمال تحميل السحابة بشكل منفصل؛ الحفاظ على ما يكفي من الحالة لإعادة تحميل دون تحميل مرة أخرى.
  • الحفاظ على FFmpeg، وقت التشغيل، yt-dlp وإصدارات المكونات الإضافية مع إطلاقك.

حوض العمال البسيط هو نقطة انطلاق أفضل من غير محدود asyncio.gather المكالمات حول العديد من التنزيلات. تنسيق العمل الإجمالي عبر العمليات؛ لا تنظم إعدادات النوم لكل تنزيل الخدمة بأكملها. الحفاظ على ميزانية الانسحاب منفصلة لمحاولات العمل بحيث لا تتضاعف التقاعدات التطبيقية عدد الانسحاب الخاص بالمنزّل.

حل مشكلة العامل Python

المشكلةتحقق
العمل في CLI ، فشل في Pythonمقارنة الخيارات الفعلية. YoutubeDL لا يحمل تلقائيا ملف تكوين CLI الخاص بك.
التقدم يقول الانتهاء، الملف مفقوداستخدم الحدود after_move ومراجعة أخطاء ما بعد المعالجة.
عودة المصدر المتكرراقرأ ملف المجموعة؛ استخدم ملفًا مختلفًا عند تغيير سياسات الإخراج.
العامل يرتفع أطول من socket_timeoutيمكن للعمل أن يلعب العديد من operations/retries. إضافة موعد مستوى العملية إذا لزم الأمر.
403 أو بوت التحقق على الخادمتحديث ليلاً، تحقق من Deno، والحد من التنافس، واختبار IP الخروج بديلاً عندما يبقى الطريق مرفوعاً.
429 في بيانات / وظائف النسختوقف IP المتأثر، وتردد extraction/subtitle المطالبات وإضافة التأخير بين البيانات الميتا-العمل فقط.

عندما ينتمي الإنتاج إلى خط أنابيب السحابة

إذا كنت ترغب في امتلاك المتصفح، وتدفقات العمل أعلاه يعطيك السيطرة على الملفات والفرم ومعالجة. إذا كانت التطبيق بحاجة إلى وسائل الإعلام المكتملة التي يتم تسليمها إلى التخزين ، فإن FlashData يوفر وظائف تنزيل YouTube المتابعة ، ومعالجة الروبوتات ، وتوجيه البروكسي ، والتقاعد. يقدم تطبيقك إعدادات المصدر والخروج، ثم يحافظ على معرف العمل وسجل التسليم.