Обзор документации
Руководства
Готовые примеры Python для загрузки файлов и метаданных, подготовки наборов данных для ИИ и возобновления заданий.
На этой странице
Настройка библиотеки Python
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"])Настройки 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))
Выделенные поля могут быть отсутственными или нулевыми. Используйте get() для опциональных метаданных, и не предполагайте, что каждый источник имеет длительность, ID канала или полный список форматов. Платный перечень перечня также отличается от полностью разрешенного видео. Для публичной ответа вы планируете проектировать только поля, которые вы намерены выявить.
Избегайте метаданного, сразу же после которого будет следуться идентичная загрузка для каждого источника, если ваше приложение не потребует дополнительного шага планирования. Это дублирует источничные запросы. Если вам нужна устойчивая работа, хранить источник ID и политику выхода; подписанный медиа-URL из метаданных не является устойчивым заменой оригинального источника.
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" | Используйте поведенческие данные сеансов только в том случае, если это необходимо для доступа. |
audio_options = {
"format": "ba",
"outtmpl": "audio/%(id)s.%(ext)s",
"postprocessors": [{
"key": "FFmpegExtractAudio",
"preferredcodec": "mp3",
"preferredquality": "192",
}],
}Видео + аудио + капции для AI-данной
Используйте эту политику выхода, когда цель - это сборник данных обучения, а не сборник образца работника 1080p. она требует лучшего видео и bestaudio, позволяет FFmpeg сливаться в MP4, и сохраняет доступные английские записи и метаданные рядом с медиа.
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])
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 для готовности к медиа, затем подтверждайте текст и метаданные перед публикацией полного элемента набора данных.
Узнайте, когда финальный файл готов
Статус докладов прогресса = законченный означает завершенный перевод. FFmpeg может все же понадобиться сливать видео и аудио, конвертировать аудиофайл или перемещать выход. Видео-лишь потоки достигают 100% не является событием завершения, которое ваша заявка должна опубликовать.
| этап | Что вы знаете | Государство применения |
|---|---|---|
| Скачать | Приходят некоторые медиабайты. | бегство |
| Переводный хок: закончен | Этот перевод закончился; обработка может продолжаться. | Обработка |
| after_move Постпроцессор | Файл прошел конфигурированный пост-процесс и конечный шаг. | Местные файлы готовы |
| Загрузка и проверка целостности | Ваш пункт назначения имеет объект и зарегистрированную проверку. | Доставлен |
Полный пример ниже регистрирует персонализированный PostProcessor в after_move и читает info["filepath"] там. Он проверяет, что файл существует и не является свободным. Это избегает предположения окончательного расширения с prepare_filename(), который может ссылаться на предконверсионное название.
Полный сценарий: одновидео работник
Сберечь это как download_video.py. Он принимает видео-ID или watch/Shorts/live/embed URL и отвергает ввод playlist/channel. Каждый запрос использует один YoutubeDL-инстант, ограниченные выделения загрузчиков и локальный архив. Повторное завершенное исходные возвраты пересекаются вместо того, чтобы предположить, что был создан новый файл.
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 ошибок, ошибку для отклоненного ввода и ошибку для локальной файловой системы. Обратитесь к ним как к различным классам в ваших регистрациях. Послания ошибок являются полезными диагностическими методами, но их текст не является стабильной структурированной таксономией каждого неудачи YouTube.
Полный сценарий: восстановленный бач-работник
Введите download_batch.py рядом с download_video.py Создайте UTF-8 urls.txt с одним видео-URL или ID по линии. Это намеренно работает последовательно, поэтому один процесс принадлежит архиву и выходной директории. Он пишет завершенный, пропущенный или неудачный результат для каждого попытанного ввода и выхода не нулевой, когда любой элемент неудачен.
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)
python download_batch.py urls.txt --output collectionСпух после каждого записи, чтобы перерыв не оставил каждый результат буффер до конца. Есть еще небольшое окно между библиотекой, записывающей ее архив, и вашей заявкой, написанной записью попыток. Если там произойдет авария, то следующий раунд может сообщить о пересечении. Для сервиса, помирировать filesystem/archive с устойчивой рабочей базы вместо того, чтобы утверждать, что этот пример текстового файла является транзакционным.
Охраняйте attempts.jsonl в частном: ошибки могут включать источники и запросы. сообщать суммы по состоянию, проверять неудачные предметы и пересматривать тот же манифест после решения проблемы с общной средой. Не добавляйте каждый неудачный ID в архив успеха.
Производство: ковчег, сроки и хранение
YoutubeDL является синхронным. Используя его непосредственно внутри асинхронных блоков веб-трейдера, что трафик событий трейдера; даже отгрузка из нитки не делает запрос браузера подходящим сроком жизни для большого загрузки. Принимая работу, продолжая ее source/options и пусть работник произведет конечный результат.
- Создайте долговечный ID работы перед выполнением. хранить канонический видео-ID, политику выхода, номер попытки и место назначения.
- Используйте рабочие каталоги на рабочем месте и ограниченный рабочий бассейн. Не делитесь примерами YoutubeDL на сопутствующих работах.
- Используйте отдельный процесс, когда вам нужен срок или отмена; socket_timeout ограничивает индивидуальные сетевые операции, а не всю работу.
- Если выявляете пользовательский вклад над HTTP, принимайте поддерживаемые видеоидентификаторы YouTube вместо произвольных 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, бот-менеджмент, прокси-рутинг и выход. Ваша заявка подает настройки источника и выхода, а затем сохраняет идентификатор работы и запись доставки.