# Python API yt-dlp

Готовые примеры Python для загрузки файлов и метаданных, подготовки наборов данных для ИИ и возобновления заданий.

Каноническая ссылка: https://flashdata.dev/ru/docs/guides/yt-dlp-python-api
Разработчик: 2026-11-13 by FlashData

- [Начните с Python](https://flashdata.dev/ru/docs/guides/yt-dlp-python-api/reference.md#first-call) — Загрузить и сделать один звонок
- [Найти последний файл](https://flashdata.dev/ru/docs/guides/yt-dlp-python-api/reference.md#completion) — После перевода и обработки
- [Получите работника](https://flashdata.dev/ru/docs/guides/yt-dlp-python-api/reference.md#worker) — Скачать .py
- [Проведение коллекции](https://flashdata.dev/ru/docs/guides/yt-dlp-python-api/reference.md#batch) — По источникам результаты и восстановление

<a id="setup"></a>

## Настройка библиотеки Python


**В вашем Python 3.11+ среде**

```bash
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
```

**Так же установите Deno, FFmpeg и ffprobe.** Эти примеры работают локально на Linux, macOS или Windows и не требуют ключа API.

- [Установка внешних зависимостей](https://flashdata.dev/ru/docs/guides/how-to-use-yt-dlp/reference.md#install)
- [Upstream встроенный референт](https://github.com/yt-dlp/yt-dlp#embedding-yt-dlp)

<a id="first-call"></a>

## Скачать свой первый видео


**Скачать одно видео**

```python
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) возвращает информацию об экстракции, а также выполняет загрузку. Используйте менеджер контекста, чтобы закрыть пример чистым образом, и создать новый пример для независимой работы, а не делиться переменным состоянием по целям.

> **Python-опции не являются механическими переводами флагов**
> --write-info-json Карты для писания; --no-playlist Карты для noplaylist. Аудиоконверсия использует список послепроцессоров. Проконсультируйтесь с документацией параметров YoutubeDL или с помощником cli_to_api.py вместо того, чтобы предположить имена опций.

<a id="metadata"></a>

## Читать метаданные без СМИ


**Экспорт небольшого метаданного**

```python
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() для опциональных метаданных, и не предполагайте, что каждый источник имеет длительность, ID канала или полный список форматов. Платный перечень перечня также отличается от полностью разрешенного видео. Для публичной ответа вы планируете проектировать только поля, которые вы намерены выявить.

Избегайте метаданного, сразу же после которого будет следуться идентичная загрузка для каждого источника, если ваше приложение не потребует дополнительного шага планирования. Это дублирует источничные запросы. Если вам нужна устойчивая работа, хранить источник ID и политику выхода; подписанный медиа-URL из метаданных не является устойчивым заменой оригинального источника.

<a id="options"></a>

## Python Option Референт


| Задание | Python опция | Подробности |
| --- | --- | --- |
| Диалог выхода и фамилия | "outtmpl": "downloads/%(id)s.%(ext)s" | Сохраняйте источник ID и динамическое расширение. |
| Тверд 1080p потолок | "format": "bv*[height<=1080]+ba/b[height<=1080]" | Допускает кодексы источника и неудача, если ни один из них не соответствует ограничению. |
| Метаданные SideCar | "writeinfojson": True | Полное извлечение метаданных убирается рядом с медиа. |
| Завершенный пункт проверки ID | "download_archive": "archive.txt" | Один архив по политике выхода; не чекс-инвентарь. |
| Строгие ошибки | "ignoreerrors": False | Пусть звонок записывает провалы вместо того, чтобы рассматривать проблемы после обработки как успех. |
| ДЕНО РУНТИМ | "js_runtimes": {"deno": {}} | Настроить Deno в рабочем и сделать его бинарный видимый на PATH. |
| Браузер имперсонации | "impersonate": ImpersonateTarget() | Python эквивалент --impersonate=""; введите целевую класу и установите curl-cffi. |
| Существующие файлы cookie | "cookiefile": "private/youtube-cookies.txt" | Используйте поведенческие данные сеансов только в том случае, если это необходимо для доступа. |

**MP3 Опции конверсии**

```python
audio_options = {
    "format": "ba",
    "outtmpl": "audio/%(id)s.%(ext)s",
    "postprocessors": [{
        "key": "FFmpegExtractAudio",
        "preferredcodec": "mp3",
        "preferredquality": "192",
    }],
}
```

Перейти audio_options в YoutubeDL. Post-процессор FFmpeg конвертирует к целевой бит-разоте 192 kbps; он не улучшает оригинальную качество источника.

- [Python параметры](https://github.com/yt-dlp/yt-dlp/blob/master/yt_dlp/YoutubeDL.py)
- [Конвертировать опции CLI в Python](https://github.com/yt-dlp/yt-dlp/blob/master/devscripts/cli_to_api.py)

<a id="dataset"></a>

## Видео + аудио + капции для AI-данной


Используйте эту политику выхода, когда цель - это сборник данных обучения, а не сборник образца работника 1080p. она требует лучшего видео и bestaudio, позволяет FFmpeg сливаться в MP4, и сохраняет доступные английские записи и метаданные рядом с медиа.

**Один элемент набора данных в Python**

```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 с ffprobe | Video/audio кодек, продолжительность, размеры, путь файла и число байтов. |
| Проверьте страничные каналы отдельно | Язык, supplied/automatic траектории, временные знаки и то, действительно ли файл существует. |
| Нет соответствующих капсион доступных | Сохраняйте медиа и отмечайте отсутствие текста; посылайте аудио на ваш переписный этап, если это необходимо. |
| Капции ударили 429 | Отзывы о выходе после IP-сохранения с подзаголовной пакетом; не перезагрузите завершенные медиа. |

Для комплекта используйте отдельный архив для этой политики набора данных и сохраняйте запас необходимых страничных точек. Не используйте ранее 1080p или только медиа-архив: он может перекрыть видео до того, как их новое требование записей собирается. Используйте after_move для готовности к медиа, затем подтверждайте текст и метаданные перед публикацией полного элемента набора данных.

- [Рецепт CLI и запас данных](https://flashdata.dev/ru/docs/guides/how-to-use-yt-dlp/reference.md#dataset)
- [Печать Python и метаданные](https://flashdata.dev/ru/docs/guides/yt-dlp-429-too-many-requests/reference.md#python)

<a id="completion"></a>

## Узнайте, когда финальный файл готов


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

| этап | Что вы знаете | Государство применения |
| --- | --- | --- |
| Скачать | Приходят некоторые медиабайты. | бегство |
| Переводный хок: закончен | Этот перевод закончился; обработка может продолжаться. | Обработка |
| after_move Постпроцессор | Файл прошел конфигурированный пост-процесс и конечный шаг. | Местные файлы готовы |
| Загрузка и проверка целостности | Ваш пункт назначения имеет объект и зарегистрированную проверку. | Доставлен |

Полный пример ниже регистрирует персонализированный PostProcessor в after_move и читает info["filepath"] там. Он проверяет, что файл существует и не является свободным. Это избегает предположения окончательного расширения с prepare_filename(), который может ссылаться на предконверсионное название.

> **Завершенный локальный загрузка не является завершенным доставкой в облако**
> Если следующий шаг загружает файл, сохраняйте состояние загрузки отдельно. Архив загрузки может пропустить источник на следующем раунде даже при неудаче предыдущего загрузки.

<a id="worker"></a>

## Полный сценарий: одновидео работник


Сберечь это как download_video.py. Он принимает видео-ID или watch/Shorts/live/embed URL и отвергает ввод playlist/channel. Каждый запрос использует один YoutubeDL-инстант, ограниченные выделения загрузчиков и локальный архив. Повторное завершенное исходные возвраты пересекаются вместо того, чтобы предположить, что был создан новый файл.

- [Скачать download_video.py](https://flashdata.dev/examples/yt-dlp/download_video.py)

**download_video.py**

```python
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))
```

Полный скрипт также доступен с ссылки на загрузку выше. он владеет только местным выходом; добавить декодирующие проверки и загружать записи на следующей стадии вашей приложения.

**Проводит одну работу**

```bash
python download_video.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --output downloads
```

Завершенный запис содержит канонический источник URL, видео-ID, конечный путь и размер байта. Открытый запис означает, что нет нового окончательного звонка; согласи его против архива и существующего запаса, если вам нужно доказать, что файл все еще присутствует. Сама архива не проверяет, удалил ли пользователь или переместил СМИ.

Уловить ошибку загрузки для extractor/download/post-processing ошибок, ошибку для отклоненного ввода и ошибку для локальной файловой системы. Обратитесь к ним как к различным классам в ваших регистрациях. Послания ошибок являются полезными диагностическими методами, но их текст не является стабильной структурированной таксономией каждого неудачи YouTube.

<a id="batch"></a>

## Полный сценарий: восстановленный бач-работник


Введите download_batch.py рядом с download_video.py Создайте UTF-8 urls.txt с одним видео-URL или ID по линии. Это намеренно работает последовательно, поэтому один процесс принадлежит архиву и выходной директории. Он пишет завершенный, пропущенный или неудачный результат для каждого попытанного ввода и выхода не нулевой, когда любой элемент неудачен.

- [Скачать download_batch.py](https://flashdata.dev/examples/yt-dlp/download_batch.py)

**download_batch.py**

```python
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 сохраняет отходы как отдельные попытки. Удаляются дублированные линии в пределах манифеста; архивы загрузки справляются с завершенными ID-ими в течение пробегов.

**Проводить или перезагрузить ту же батальон**

```bash
python download_batch.py urls.txt --output collection
```

Спух после каждого записи, чтобы перерыв не оставил каждый результат буффер до конца. Есть еще небольшое окно между библиотекой, записывающей ее архив, и вашей заявкой, написанной записью попыток. Если там произойдет авария, то следующий раунд может сообщить о пересечении. Для сервиса, помирировать filesystem/archive с устойчивой рабочей базы вместо того, чтобы утверждать, что этот пример текстового файла является транзакционным.

Охраняйте attempts.jsonl в частном: ошибки могут включать источники и запросы. сообщать суммы по состоянию, проверять неудачные предметы и пересматривать тот же манифест после решения проблемы с общной средой. Не добавляйте каждый неудачный ID в архив успеха.

<a id="service"></a>

## Производство: ковчег, сроки и хранение


YoutubeDL является синхронным. Используя его непосредственно внутри асинхронных блоков веб-трейдера, что трафик событий трейдера; даже отгрузка из нитки не делает запрос браузера подходящим сроком жизни для большого загрузки. Принимая работу, продолжая ее source/options и пусть работник произведет конечный результат.

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

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

<a id="diagnostics"></a>

## Устранение проблем рабочего Python


| Проблема | Проверить |
| --- | --- |
| Работа в CLI, неудача в Python | YoutubeDL не автоматически загружает файл конфигурации CLI. |
| Прогресс говорит закончен, файл пропал | Используйте границу after_move и проверьте ошибки после обработки. |
| Повторный источник возвращается | Читайте архив сборки; используйте другой архив при изменении политики выхода. |
| Работник завязывается дольше socket_timeout | Работа может выполнять много operations/retries. Добавить срок на уровне процесса, если это необходимо. |
| 403 или бот проверяет сервер | Ночной обновление, проверка Deno, снижение конкуренции и испытание IP выхода замены, когда маршрут остается отвергнутым. |
| 429 в метаданных / транскриптных работах | Перерыв пораженного IP, темпы extraction/subtitle запросов и добавление задержек между метаданными-лишь работы. |

- [403 диагностический рабочий поток](https://flashdata.dev/ru/docs/guides/yt-dlp-403-forbidden/reference.md)
- [Рабочий поток сессии и бот-чека](https://flashdata.dev/ru/docs/guides/yt-dlp-sign-in-not-a-bot/reference.md)
- [429 восстановление и Python pacing](https://flashdata.dev/ru/docs/guides/yt-dlp-429-too-many-requests/reference.md)
- [Проверьте спасенные СМИ](https://flashdata.dev/ru/docs/guides/how-to-use-yt-dlp/reference.md#verify)

<a id="managed-downloads"></a>

## Когда вывод принадлежит облачному трубопроводу


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

- [Сравнить два операционных модела](https://flashdata.dev/ru/docs/guides/flashdata-vs-yt-dlp/reference.md)
- [Массовая загрузка видео с YouTube](https://flashdata.dev/ru/products/youtube-download#bulk-downloads)
- [Попробуйте скачать демо](https://flashdata.dev/ru/products/youtube-download#playground)
- [Скачать API Reference](https://flashdata.dev/ru/docs/sources/youtube_download/reference.md)
