Przeglądaj dokumentację
Poradniki
Przykłady w Pythonie do pobierania plików, pobierania metadanych, tworzenia zbiorów dla AI i wznawiania pracy.
Na tej stronie
Instalacja biblioteki Python
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"Installuj również Deno, FFmpeg i ffprobe. Te przykłady działają lokalnie na Linuxie, macOS lub Windows i nie wymagają klucza API.
Pobierz swoje pierwsze wideo
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"])Nie dziedziczają się ustawienia CLI. Ustaw Deno, impersonalizacja i pacing w opcjach Python, nawet jeśli polecenie terminalu już je używa.
download() pobiera listę adresów URL i zwraca kod stanu. extract_info(url, download=True) zwraca informacje o ekstrakcji, a także wykonuje pobieranie. Użyj menedżera kontekstu, aby zamknąć przykład czysto i stworzyć nowy przykład dla niezależnej pracy zamiast dzielić się zmiennym stanem na filarach.
Czytaj metody bez mediów
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))
Wyciągnięte pola mogą być nieobecne lub zerowe. Użyj get() do opcjonalnych metadanych, a nie przypuszczać, że każdy źródło ma długość, identyfikator kanału lub kompletną listę formatów. Płyta lista odtwarzania różni się również od wideo w pełni rozdzielonego. W celu uzyskania publicznej odpowiedzi, projekt tylko pola, które zamierzasz wystawić.
Unikaj natychmiastowego ekstrakcji metadanych, a następnie identycznego ekstrakcji pobierania dla każdego źródła, chyba że aplikacja potrzebuje dodatkowego kroku planowania. Podwójnie podnosi się zapytania źródłowe. Jeśli potrzebujesz trwałej pracy, przechowuj identyfikator źródłowy i politykę wyjścia; podpisany adres URL mediów z metadanych nie jest trwałym zastępcą oryginalnego źródła.
Opcja Python opcja referencyjna
| Zadanie | Opcja Python | Szczegóły |
|---|---|---|
| Katalog wyjściowy i nazwa filen | "outtmpl": "downloads/%(id)s.%(ext)s" | Utrzymuj identyfikator źródłowy i dynamiczną rozszerzenie. |
| Twarde 1080p dach | "format": "bv*[height<=1080]+ba/b[height<=1080]" | Pozwala kodek źródłowy i nie działa, jeśli żaden z nich nie odpowiada ograniczonemu. |
| Metadatyka sidecar | "writeinfojson": True | Zestaw pełnych metadatu ekstrakcji obok mediów. |
| Wygląda na to, że identyfikacja checkpoint | "download_archive": "archive.txt" | Jeden archiwum na politykę wyjścia, a nie zapas czeku. |
| Strictwe błędy | "ignoreerrors": False | Pozwól, aby odbiorca nagrywał porażki zamiast traktować problemy po przetwarzaniu jako sukces. |
| Dane Runtime | "js_runtimes": {"deno": {}} | Instaluj Deno w pracowniku i uczyń jego binary widoczne na PATH. |
| Impersonalność przeglądarki | "impersonate": ImpersonateTarget() | Python równowartość --impersonate=""; wprowadź klasę docelową i zainstaluj curl-cffi. |
| Istniejące pliki cookie | "cookiefile": "private/youtube-cookies.txt" | Użyj prywatnych zaświadczeń sesji tylko wtedy, gdy jest to konieczne do uzyskania dostępu. |
audio_options = {
"format": "ba",
"outtmpl": "audio/%(id)s.%(ext)s",
"postprocessors": [{
"key": "FFmpegExtractAudio",
"preferredcodec": "mp3",
"preferredquality": "192",
}],
}Video + audio + captions dla zestawu danych AI
Użyj tej polityki wyjścia, gdy celem jest zestaw danych szkoleniowy zamiast zbioru przykładu pracownika 1080p. wymaga bestvideo i bestaudio, pozwala FFmpeg połączyć je w MP4, a także przechowuje dostępne angielskie wykresy i metadane obok mediów.
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() wybiera dowolny dostępny cel przeglądarki, odpowiadając --impersonate="". Przejdź do obiektu, a nie puste strumień kopiowane z syntax CLI. curl-cffi musi być zainstalowany w tym środowisku Python. Deno nadal wykonuje JavaScript solving; impersonalizacja nie zastępuje go.
MP4 to pojemnik wyjściowy; wybrane wideo może być nadal AV1 lub VP9. Jeśli decoder szkolenia wymaga H.264/AAC, zastosuj wyraźną politykę kodeków przed połączeniem lub zapisaniem oddzielnego FFmpeg transkodu. Dostępne podtytuły są odzyskane, nie generowane z mowy.
| Po zakończeniu mediów | Co potrzebuje rejestr danych |
|---|---|
| Sprawdź ostatni MP4 z ffprobe | Video/audio kodeków, długości, wymiarów, ścieżki pliku i liczby bytu. |
| Sprawdź oddzielnie odcinki | Język, ścieżka supplied/automatic, czasowe sztuczki i czy plik rzeczywiście istnieje. |
| Nie ma dostępnych kapsułek | Utrzymuj media i oznacz tekst brakujący; wysyłaj audio do fazy transkrypcji, jeśli to konieczne. |
| Złoty wątek 429 | Retry caption retrieval po IP cooldown z podtytuł pacing; nie ponownie pobrać zakończone media. |
W przypadku zestawu użyj oddzielnego archiwum dla tej polityki zestawu danych i przechowuj zapas wymaganych stron. Nie ponownie używaj wcześniejszych 1080p lub tylko archiwum mediów: może to przestać odtwarzać filmy przed ich nowo wymagane odbiory są zbierane. Użyj after_move do gotowości mediów, a następnie weryfikuj tekst i metadane przed publikacją pełnego elementu zbioru danych.
Zrozum, kiedy ostatni plik jest gotowy
Status = zakończony oznacza zakończony transfer. FFmpeg może nadal być konieczne połączenie wideo i audio, konwertowanie pliku audio lub przenoszenie wyjścia. Wideo tylko strumień osiągnięcia 100% nie jest zakończenie wydarzenia, którego aplikacja powinna publikować.
| Etap | Co Ty wiesz | Stany zastosowania |
|---|---|---|
| Pobierz | Przybywają się media. | bieganie |
| Transfer Hook: zakończony | Ta transfer zakończyła się; przetwarzanie nadal może być kontynuowane. | przetwarzanie |
| after_move Post-przetwarzacz | Plik przeszedł konfigurowany post-procesing i ostateczne ruchy. | Lokalne pliki gotowe |
| Upload i sprawdzenie integralności | Twój cel ma obiekt i zarejestrowane weryfikacje. | dostarczone |
Pełny przykład poniżej rejestruje przystosowany PostProcessor w after_move i czyta info["filepath"] tam. Sprawdzają, że plik istnieje i jest niepowtarzalny. To unika przewidywania ostatecznego rozszerzenia z prepare_filename(), który może odnosić się do nazwy pre-konwersji.
Kompletny scenariusz: Single-video worker
Zostaw to jako download_video.py. Akceptuje identyfikator wideo lub watch/Shorts/live/embed URL i odrzuca wpis playlist/channel. Każda inwokacja wykorzystuje jeden przykład YoutubeDL, ograniczone odliczenia pobieracza i archiwum kolekcjonerskie. Powtarzane zakończone źródło zwrotu przestaje zamiast domyślać się, że nowy plik został stworzony.
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 downloadsZapis zakończony zawiera kanoniczny adres źródłowy URL, identyfikator wideo, ostateczny ścieżka i rozmiar bajtu. Zapis przeniesiony oznacza, że nie ma nowego ostatniego pliku zwrotnego; pojednanie go przeciwko archiwum i istniejącym zapasowi, jeśli potrzebujesz dowodu, że plik jest nadal obecny. Archiwum nie sprawdza, czy użytkownik później usunął lub przeniósł się do mediów.
Pobierz błąd DownloadError dla extractor/download/post-processing, błąd wartości dla odrzuconych wpisów i błąd OSError dla lokalnych błędu systemu plików. Traktuj je jako odrębne klasy w logach aplikacji. Wiadomości błędne są przydatnymi diagnostykami, ale ich tekst nie jest stabilną strukturowaną taksonomii każdego niepowodzenia YouTube.
Scenariusz: powtarzalny batch worker
Wprowadź download_batch.py obok download_video.py. Tworzenie UTF-8 urls.txt z jednym adresem URL wideo lub identyfikatorem na linie. To celowo działa sekwencjonalnie, więc jeden proces jest własnością archiwum i katalogu wyjściowego. Napisał zakończony, przebił lub nie udało się wyniki dla każdego próbnego wejścia i wyjścia zero, gdy jakikolwiek element nie powiodł.
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 collectionPo każdym rekordie przepływa, aby przerwa nie pozostawiała każdego wyniku do końca. Wciąż istnieje małe okno między biblioteką rejestrującej jej archiwum a aplikacją piszącą próbny rekord. Jeśli tam doszło do wypadku, następny wyścig może zgłaszać przeniesione. W przypadku usługi, pojednanie filesystem/archive z trwałą bazą roboczą zamiast twierdzić, że ten przykład pliku tekstowego jest transakcyjny.
Utrzymaj attempts.jsonl prywatne: błędy mogą zawierać dane źródła i żądania. zgłaszać sumy według stanu, sprawdzić nieudane elementy i odtwarzać ten sam manifest po rozwiązaniu problemu środowiska udostępnionego. Nie dodawać każdego nieudanej identyfikator do archiwum sukcesu.
Produkcja: tarcza, terminy i przechowywanie
YouTube jest synchronizowany. Przeprowadzanie go bezpośrednio w bloku asyncowego handlowca, który jest przepływem wydarzeń handlowca; nawet wypłata strumienia nie sprawia, że żądanie przeglądarki ma odpowiedni czas życia na duże pobieranie. Przyjmuj pracę, trzymaj się jej source/options i pozwól pracownikowi wyprodukować ostateczny wynik.
- Przed wykonaniem utworzyć trwałe identyfikator pracy. przechowywać kanoniczny identyfikator wideo, politykę wyjścia, numer próbny i cel.
- Użyj katalogów pracy na pracę i ograniczonego basenu pracowników. Nie udostępniaj przykładu YoutubeDL w różnych miejscach pracy.
- Użyj oddzielnego procesu, gdy potrzebujesz terminu lub anulowania zegarka ściannego; socket_timeout ogranicza indywidualne operacje sieciowe, a nie całą pracę.
- Jeśli narażenie użytkownika wpływy nad HTTP, akceptuj wspierane identyfikatory wideo YouTube zamiast arbitralne adresy URL, drogi wyjścia, argumenty ekstraktorów lub szkielety.
- Zapisz gotowość lokalnego pliku i zakończenie pobierania w chmurze oddzielnie; utrzymaj wystarczającą ilość stanu, aby odzyskać pobieranie bez ponownego pobierania.
- Utrzymuj wersje FFmpeg, czas pracy, yt-dlp i wtyczki z rozmieszczeniem.
Prosty basen robotników jest lepszym punktem wyjścia niż nieograniczony asyncio.gather dzwoni wokół wielu pobierania. Koordynuj całkowitą pracę w procesach; ustawienia snu każdego pobierającego nie regulują całej usługi. Utrzymuj oddzielny budżet retry dla prób pracy, aby emerytury aplikacyjne nie powiększały liczby retry samego pobierającego.
Rozwiązywanie problemów z pracownikiem Python
| problem | Sprawdź |
|---|---|
| Prace w CLI, niepowodzenia w Pythonie | Porównaj rzeczywiste opcje. YoutubeDL nie automatycznie pobiera pliku konfiguracji CLI. |
| Progres mówi zakończony, brakuje pliku | Użyj after_move granicy i sprawdź błędy post-przetwarzania. |
| Powtarzane źródło zwraca się | Przeczytaj archiwum kolekcji; użyj innego archiwum podczas zmiany polityki wyjścia. |
| Pracownik wkłada się dłużej niż socket_timeout | Praca może wykonywać wiele operations/retries. Dodaj termin na poziomie procesu, jeśli to konieczne. |
| 403 lub bot sprawdza na serwerze | Aktualizuj w nocy, sprawdź Deno, zmniejsz konkurencję i przetestuj IP wyjścia zastępczego, gdy trasa pozostaje odrzucona. |
| 429 w metadatach / transcript prace | Zatrzymaj dotknięte IP, szybkość extraction/subtitle zapytania i dodać opóźnienia między metadany-tylko prace. |
Gdy produkcja należy do przewodu chmury
Jeśli chcesz posiadać pobieracza, powyższe przepływy pracy dają Ci kontrolę nad plikami, formatami i przetwarzaniem. Jeśli aplikacja potrzebuje kompletnych mediów dostarczonych do przechowywania, FlashData zapewnia śledzone YouTube stawki, roboty do obsługi botów, proxy routing i retries. Twoja aplikacja przedstawia ustawienia źródła i wyjścia, a następnie utrzymuje identyfikator pracy i rekord dostawy.