Przejdź do treści
PL
Uzyskaj klucz API
Przeglądaj dokumentację

Poradniki

Interfejs Python API yt-dlp

Przykłady w Pythonie do pobierania plików, pobierania metadanych, tworzenia zbiorów dla AI i wznawiania pracy.

Na tej stronie

Instalacja biblioteki Python

W Twoim środowisku Python 3.11+
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

Pobierz jeden film
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"])
To pisze lokalne media do 1080p i może połączyć oddzielne strumienia. pojemnik wyjściowy zależy od wybranych formatów źródłowych.

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

Eksportowanie małych rekordów metadanych
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 nadal wykonuje żądania sieciowe. sanitize_info sprawia, że wynik JSON jest zgodny; nie pisze tajemnic ani nie zmniejsza wyników do tych pól.

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

ZadanieOpcja PythonSzczegół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": TrueZestaw 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": FalsePozwó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.
MP3 Opcje konwersji
audio_options = {
    "format": "ba",
    "outtmpl": "audio/%(id)s.%(ext)s",
    "postprocessors": [{
        "key": "FFmpegExtractAudio",
        "preferredcodec": "mp3",
        "preferredquality": "192",
    }],
}
Przejście audio_options do YoutubeDL. Post-procesor FFmpeg konwertuje się na taryfę bitową 192 kbps; nie poprawia oryginalnej jakości źródła.

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.

Jedno elementy z zestawu danych w Pythonie
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])
Wymaga FFmpeg/ffprobe, Deno i instalacji nocnej [default,curl-cffi]. parametr preferowanego formatu remuxera jest w ten sposób wyświetlany w API yt-dlp.

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ówCo potrzebuje rejestr danych
Sprawdź ostatni MP4 z ffprobeVideo/audio kodeków, długości, wymiarów, ścieżki pliku i liczby bytu.
Sprawdź oddzielnie odcinkiJęzyk, ścieżka supplied/automatic, czasowe sztuczki i czy plik rzeczywiście istnieje.
Nie ma dostępnych kapsułekUtrzymuj media i oznacz tekst brakujący; wysyłaj audio do fazy transkrypcji, jeśli to konieczne.
Złoty wątek 429Retry 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ć.

EtapCo Ty wieszStany zastosowania
PobierzPrzybywają się media.bieganie
Transfer Hook: zakończonyTa transfer zakończyła się; przetwarzanie nadal może być kontynuowane.przetwarzanie
after_move Post-przetwarzaczPlik przeszedł konfigurowany post-procesing i ostateczne ruchy.Lokalne pliki gotowe
Upload i sprawdzenie integralnościTwó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.

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))
Pełny scenariusz jest również dostępny z linków do pobrania powyżej. posiada tylko lokalny wynik; dodać sprawdzania dekodowania i przesyłania rekordów w następnym etapie aplikacji.
Wykonaj jedną pracę
python download_video.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --output downloads

Zapis 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ł.

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)
Dodatek attempts.jsonl zachowuje zwrot jako oddzielne próby. linie podwójne w manifestu są usuwane; archiwum pobierania obsługuje identyfikatory zakończone przez biegi.
- wyprzedzać lub ponownie wyprzedzać ten sam batch
python download_batch.py urls.txt --output collection

Po 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

problemSprawdź
Prace w CLI, niepowodzenia w PythoniePorównaj rzeczywiste opcje. YoutubeDL nie automatycznie pobiera pliku konfiguracji CLI.
Progres mówi zakończony, brakuje plikuUż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_timeoutPraca może wykonywać wiele operations/retries. Dodaj termin na poziomie procesu, jeśli to konieczne.
403 lub bot sprawdza na serwerzeAktualizuj w nocy, sprawdź Deno, zmniejsz konkurencję i przetestuj IP wyjścia zastępczego, gdy trasa pozostaje odrzucona.
429 w metadatach / transcript praceZatrzymaj 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.