Перейти до вмісту
UK
Отримати ключ API
Переглянути документацію

Посібники

Python API 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.

Завантажити свій перший відео

Завантажити один відео
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 не успадковуються. Налаштуйте Дено, персоналізацію та пакінг в варіантах 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))
Download=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Зверніть увагу на недоліки запису замість того, щоб розглядати проблеми після обробки як успіх.
Деніо Ронтіма"js_runtimes": {"deno": {}}Налаштуйте Deno в роботодавця і зробіть його бінарний видимий на PATH.
Браузерна імперіація"impersonate": ImpersonateTarget()Python еквівалент --impersonate=""; імпортуйте цільову класу і встановіть curl-cffi.
Постачаючі файли cookie"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 працівника. вона вимагає кращого відео і bestaudio, дозволяє FFmpeg поєднувати їх в MP4, і зберігає доступні англійські знімки і метадани поряд з засобами масової інформації.

1 Елементи набору даних в 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]. параметр улюбленого формату ремуксера відображається таким чином в API yt-dlp.

ImpersonateTarget() вибирає будь-яку доступну ціль браузера, що відповідає --impersonate="". Пройде об'єкт, а не порожній ряд, копійований з CLI-синтакси. curl-cffi повинен бути встановлений в цьому Python середовищі. Deno все ще виконує JavaScript-розв'язання; імперіація не замінює його.

MP4 - це контейнер виходу; вибраний відео може все ще бути AV1 або VP9. Якщо ваш тренувальний декодер вимагає H.264/AAC, застосовуйте чітку політику кодек перед поєднанням або записом окремого FFmpeg транскоду. Доступні субтитри отримуються, не генеруються з виступу.

Після закінчення медіаЩо потрібно для реєстрації даних
Подивимося, що в кінці MP4 з ffprobeVideo/audio кодек, тривалість, розміри, шлях файлу і кількість байтів.
Перевірка списку бокових точок окремоМова, supplied/automatic трак, часові знаки і чи дійсно файл існує.
Не доступні відповідні капсулиЗберігайте засоби масової інформації і вкажіть текст відсутній; надішліть звук до етапу транскрипції, якщо це необхідно.
Завантажити 429Відновлення відновлення після IP-холодону з підзаголошенням; не перезавантажуйте завершені медіа.

Для комплекту використовуйте окремий архів для цієї політики набору даних і зберігайте інвентар для необхідних бокових копій. Не використовуйте попередній 1080p або тільки медіа-архіви: це може відключити відео, перш ніж їх новозаписані записи зібрані. Використовуйте after_move для підготовки засобів масової інформації, а потім підтверджуйте текст і метадані перед публікацією повного елемента набору даних.

Знайте, коли завершальний файл готовий

Статус доповіді про прогрес = завершено означає завершений перехід. FFmpeg може все ще потрібно поєднувати відео і аудіо, конвертувати аудіофайл або перемістити вихід. Відео-один потік досягнення 100% не є завершення події, що ваша заявка повинна публікувати.

ЕтапиЩо ти знаєшДержава застосування
ЗавантажитиДеякі медіа-байти вже прибувають.бігати
Перехідний хок: завершеноЦей трансфер завершився; обробка може продовжуватися.обробка
after_move ПостпроцесорФайл пройшов конфігурований пост-процесування і остаточний крок.Місцеві файли готові
Завантаження та контроль цілісностіВашій мети є об'єкт і зареєстрована перевірка.Доставка

Повний приклад нижче записує пристосований PostProcessor в after_move і читає info["filepath"] там. Він перевіряє, чи існує файл і чи є він недійсним. Це уникає припущення кінцевого розширення з prepare_filename(), що може відноситися до прі-конверсійного імені.

Сценарій: одновідеопрацівники

Зберегти це як download_video.py. Він приймає відео-ID або URL watch/Shorts/live/embed і відкидає вхід 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-адрес джерела, відео-ІД, кінцевий шлях і розмір байту. Перерваний запис означає, що не буде нового кінцевого файлу зворотного зв'язку; погоджуйте його проти архіву і існуючого запасу, якщо вам потрібно довести, що файл все ще присутній. Сама архіва не перевіряє, чи користувач пізніше видалив або перемістив медіа.

Утримуйте помилку DownloadError для extractor/download/post-processing помилок, помилку ValueError для відхилених входів і помилку 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 до архіву успіху.

Виробництво: ковчег, терміни та зберігання

YouTubeDL є синхронічним. Виконувати його безпосередньо в межах асинхронних блоків веб-трейдера, що обертається на події трейдера; навіть відвантаження стрічки не робить запит браузера відповідним життєвим часом для великого завантаження. Приймати роботу, тримати її source/options і дозволити працівникам виробляти кінцевий результат.

  • Створіть тривалий робочий ідентифікатор перед виконанням. Зберігайте канонічний відео-ідентифікатор, політика виходу, номер спроби та місце призначення.
  • Використовуйте робочі каталоги на роботу та обмежений робочий басейн. Не діліться прикладом YoutubeDL на конкурентних роботах.
  • Використовуйте окремий процес, коли вам потрібен термін або скасування жорсткого стінового годинника; socket_timeout обмежує окремі операції мережі, а не всю роботу.
  • Якщо виявляти вхід користувача над HTTP, прийняти підтримувані ідентифікатори відео YouTube замість произвольних URL-адресів, вихідних шляхів, аргументів екстрактора або шейл снайппетів.
  • Запишіть готування локального файлу і завершення завантаження в хмарі окремо; зберігайте достатньо стану, щоб відновити завантаження без завантаження знову.
  • Зберігайте FFmpeg, робочий час, yt-dlp і версії плагінів з вашим запуском.

Простий робочий басейн є кращим початковим пунктом, ніж без обмежень asyncio.gather дзвінки навколо багатьох завантажень. Координація загальної роботи по процесам; налаштування сну кожного завантажувача не регулюють всю службу. Зберігайте окремий бюджет відходу на робочі спроби, щоб відходи від заявки не збільшували свій ретрит.

Вирішити проблеми працівника Python

ПроблемаПро нас
Робочі в CLI, невдачі в PythonYouTubeDL не автоматично завантажує файл конфігурації CLI.
Прогрес говорить завершено, файл відсутнійВикористовуйте after_move кордон і перевіряйте помилки після обробки.
Повторні джерела повертаютьсяЧитайте архіву збірки; використовуйте інший архів при зміні політики виходу.
Працівники витримують довше, ніж socket_timeoutОдна робота може виконувати багато operations/retries. Додати термін процесу, якщо це необхідно.
403 або бот перевіряє на серверіОновлюйте нічно, перевірте Deno, зменшуйте конкуренцію і перевіряйте IP-адресу заміни, коли маршрут залишається відхиленим.
429 в метаданних / транскриптованих роботахПерервати уражені IP, темпи extraction/subtitle запитів і додати затримки між метаданними-лише робочих місць.

Коли вихід належить до облачного трубопроводу

Якщо ви хочете володіти завантажувачем, то вищезазначені робочі потоки дають вам контроль над файлами, форматами та обробкою. Якщо вашій програмі потрібні завершені засоби масової інформації, які надаються для зберігання, FlashData забезпечує відстежені робочі місця для завантаження YouTube, обробку ботів, прокси-рутінг і відступ. Ваша заявка подає налаштування джерела і виходу, а потім зберігає робочий ідентифікатор та запис доставки.