Überspringen zum Inhalt
DE
API-Schlüssel
Dokumentation durchsuchen

Anleitungen

Python-API von yt-dlp

Ausführbare Python-Beispiele für Downloads, Metadaten, KI-Datensätze und fortsetzbare Aufträge.

Auf dieser Seite

Installation der Python-Bibliothek

In Ihrem Python 3.11+ Umfeld
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"

Installieren Sie auch Deno, FFmpeg und ffprobe. Diese Beispiele funktionieren lokal auf Linux, macOS oder Windows und benötigen keine API-Schlüssel.

Download Dein erstes Video

1 Video herunterladen
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"])
Dies schreibt lokale Medien bis 1080p und kann separate Streams miteinander verbinden. Der Ausgangscontainer hängt von den ausgewählten Quellformaten ab.

CLI-Einstellungen sind nicht vererbt. Set Deno, Impersonen und Pacing in den Python-Optionen, auch wenn Ihre Terminal-Kommand bereits sie verwendet.

download() nimmt eine Liste der URLs und returns einen Statuscode. extract_info(url, download=True) returns extraction information as well as performing the download. Verwenden Sie einen Kontextmanager, um den Fall sauber zu schließen und einen neuen Fall für eine unabhängige Arbeit zu erstellen, anstatt sich über Streifen veränderliche Zustände zu teilen.

Lesen Sie Metadaten ohne Medien

Exportieren Sie ein kleines Metadaten-Rekord
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 erfüllt immer noch Netzwerkanfragen. sanitize_info macht das Ergebnis JSON-kompatibel; es redet keine Geheimnisse oder reduziert das Ergebnis auf diese Felder.

Die ausgehändten Felder können fehlen oder null sein. Verwenden Sie Get() für optionale Metadaten und nicht davon aus, dass jede Quelle eine Dauer, Kanal-ID oder eine vollständige Formatliste hat. Eine Flach-Playlist-Liste unterscheidet sich auch von einem vollständig aufgelösten Video. Für eine öffentliche Antwort, Projektieren Sie nur die Felder, die Sie exponieren möchten.

Vermeiden Sie eine Metadaten-Extraktion sofort, gefolgt von einer identischen Download-Extraktion für jede Quelle, es sei denn, Ihre Anwendung benötigt den zusätzlichen Planungsstap. Es dupliert Quellanfragen. Wenn Sie eine nachhaltige Arbeit benötigen, speichern Sie die Quell-ID und Ausgangspolitik; eine unterschriebene Medien-URL aus den Metadaten ist keine nachhaltige Ersatz für die ursprüngliche Quelle.

Python Option Referenz

AufgabePython OptionDetails
Ausgangsdirektiv und Filename"outtmpl": "downloads/%(id)s.%(ext)s"Halten Sie die Quell-ID und die dynamische Erweiterung.
Hard 1080p Dach"format": "bv*[height<=1080]+ba/b[height<=1080]"Erlaubt Quellcode und fehlt, wenn keiner der Grenzen entspricht.
Metadaten SideCar"writeinfojson": TrueKeeps vollständige Extraction-Metadaten neben den Medien.
Vollständige ID-Checkpoint"download_archive": "archive.txt"Ein Archiv pro Ausgangsbestimmung; kein Checksum-Inventory.
strenge Fehler"ignoreerrors": FalseLassen Sie den Anrufer Fehler aufzeichnen, anstatt nachverarbeitende Probleme als Erfolg zu behandeln.
Denos runtime"js_runtimes": {"deno": {}}Deno im Arbeiter installieren und seine binäre sichtbar auf PATH machen.
Browser Impersonen"impersonate": ImpersonateTarget()Python gleichwertig --impersonate=""; die Zielklasse importieren und installieren curl-cffi.
bestehende Cookie-Datei"cookiefile": "private/youtube-cookies.txt"Verwenden Sie private Sitzungs-Kreditationen nur, wenn sie für den Zugriff benötigt werden.
MP3 Konvertierungsoptionen
audio_options = {
    "format": "ba",
    "outtmpl": "audio/%(id)s.%(ext)s",
    "postprocessors": [{
        "key": "FFmpegExtractAudio",
        "preferredcodec": "mp3",
        "preferredquality": "192",
    }],
}
Pass audio_options auf YoutubeDL. Der FFmpeg Post-Prozessor konvertiert zu einer Zielsteile von 192 kbps; es verbessert nicht die ursprüngliche Qualität der Quelle.

Video + Audio + Captions für eine AI-Datenheit

Verwenden Sie diese Ausgangsbestimmung, wenn das Ziel ein Training-Datenset ist, anstatt die Sammlung des Arbeiters Beispiel 1080p. Es erfordert bestvideo und bestaudio, lässt FFmpeg sie in MP4 miteinander verbinden und speichert verfügbare Englisch-Fragungen und Metadaten neben den Medien.

Ein Datensatz in 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])
Erfordert FFmpeg/ffprobe, Deno und die Nachtinstellung [Default,curl-cffi]. Der bevorzugte Formatparameter des Remusters wird auf diese Weise in der API yt-dlp angezeigt.

ImpersonateTarget() wählt jede verfügbare Browser-Ziel, die mit --impersonate="" entspricht. Pass das Objekt, nicht eine leere Zeile kopiert von CLI Syntax. curl-cffi muss in diesem Python Umfeld installiert werden. Deno arbeitet noch JavaScript lösen; Impersonen ersetzt es nicht.

MP4 ist der Ausgangsbehälter; das ausgewählte Video kann noch AV1 oder VP9 sein. Wenn Ihr Training-Decoder H.264/AAC erfordert, verwenden Sie vor der Fusion oder Aufzeichnung eines separaten FFmpeg Transcode eine ausdrückliche Codec-Politik. Die verfügbaren Untertitel werden erholt, nicht aus der Rede erzeugt.

Nach dem Ende der MedienWas die Datensatz-Register benötigt
Schauen Sie sich die letzte MP4 mit ffprobe anVideo/audio Codecs, Dauer, Dimensionen, Dateiweg und Byte-Zahl.
Check caption Seitenkarten separatSprache, supplied/automatic-Track, Zeiten und ob die Datei tatsächlich existiert.
Keine matching captions verfügbarHalten Sie die Medien und markieren Sie den Text fehlend; senden Sie Audio zu Ihrem Transcription-Spiegel, wenn erforderlich.
Die Kaptionen schlagen 429Retry caption retrieval nach einem IP-Kühldown mit Subtitle pacing; nicht die fertigte Medien neu herunterladen.

Für eine Menge verwenden Sie für diese Datensatzrichtlinie einen separaten Archiv und halten Sie ein Inventor für die erforderlichen Seiten. Verwenden Sie keine früheren 1080p oder Medien-nur-Archiv neu: Es kann Videos abschließen, bevor ihre neu benötigten Abschnitte gesammelt werden. Verwenden Sie after_move für Medienbereitigkeit, validieren Sie dann Text und Metadaten, bevor Sie ein vollständiges Datensatz-Einstück veröffentlichen.

Erfahren Sie, wann die letzte Datei fertig ist

Eine Fortschritte-Hoch-Berichtung Status = fertig bedeutet eine Überweisung fertig. FFmpeg muss möglicherweise noch Video und Audio kombinieren, eine Audio-Datei konvertieren oder die Ausgabe bewegen. Ein Video-nur Stream erreicht 100% ist nicht das Abschluss-Event, das Ihre Anwendung veröffentlichen sollte.

PhaseWas du weißtAnwendungszustand
DownloadenEinige Medienbiten kommen.Laufen
Transfer Hook: FertigDieser Transfer ist beendet; die Verarbeitung kann noch folgen.Verarbeitung
after_move Post-ProzessorDie Datei hat die konfigurierte Post-Verarbeitung und endgültige Bewegung durchgeführt.Lokale Datei bereit
Upgrade und Integrität CheckIhr Ziel hat das Objekt und die registrierte Verifikation.Lieferung

Das vollständige Beispiel unten registriert einen benutzerdefinierten PostProcessor bei after_move und liest info["filepath"] dort. Es überprüft, dass die Datei existiert und unentbehrt ist. Dies verhindert, dass die letzte Erweiterung mit prepare_filename() gedacht wird, die sich auf einen Pre-Conversion-Namen bezieht.

Komplett Script: Single-Video Worker

So sparen Sie das wie download_video.py. Es akzeptiert eine Video-ID oder watch/Shorts/live/embed URL und verweigert playlist/channel Eingabe. Jede Anrufe verwendet eine YoutubeDL-Instanz, begrenzte Downloader-Retries und ein Sammel-Lokale-Archiv. Eine wiederholte vollendete Quell-Return wird verpasst, anstatt ein neues Datei zu behaupten, wurde erstellt.

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))
Das vollständige Script ist auch von der Download-Link oben erhältlich. Es besitzt nur lokale Ausgabe; fügen Sie Decoding-Checks und hochladen Sie die Aufzeichnungen im nächsten Schritt Ihrer Anwendung hinzu.
1 Arbeit durchführen
python download_video.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --output downloads

Die abgeschlossenen Aufzeichnung enthält die kanonische Quell-URL, Video-ID, endgültige Path und Byte-Größe. Ein geschlagenes Record bedeutet, dass keine neue Enddatei-Callback ausgeführt wird; vereinigen Sie es gegen das Archiv und bestehende Inventory, wenn Sie Nachweis benötigen, dass die Datei noch vorhanden ist. Die Archive allein überprüft nicht, ob ein Benutzer später die Medien gelöscht oder bewegt hat.

Catch DownloadError für extractor/download/post-processing Fehler, ValueError für abgelehntes Eingriff und OSError für lokalen Dateisystem-Fehler. Behandeln Sie diese als separate Klassen in Ihren Anwendungslogs. Fehlermeldungen sind nützliche Diagnosen, aber ihre Text ist nicht eine stabile strukturierte Taxonomie jeder YouTube-Fehler.

Komplett-Script: Wiederholbarer Battcharbeiter

Laden Sie download_batch.py neben download_video.py. Erstellen Sie eine UTF-8 urls.txt mit einem Video-URL oder ID pro Zeile. Dies funktioniert absichtlich sequentiell, so dass ein Prozess das Archiv- und Ausgangsdirektiv besitzt. Es schreibt ein abgeschlossenes, verschwundenes oder fehlendes Ergebnis für jedes versuchte Eingang und Ausgang null, wenn ein Element fehlte.

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)
Die Append-only attempts.jsonl hält Retries als separate Versuche. Duplikate Linien innerhalb eines Manifestes werden entfernt; das Download-Archiv verfolgt vollständige IDs über Rennen.
Lauf oder wiederholen Sie die gleiche Batch
python download_batch.py urls.txt --output collection

Flush nach jedem Record so dass eine Unterbrechung nicht jedes Ergebnis bis zum Ende bufferiert. Es gibt immer noch ein kleines Fenster zwischen der Bibliothek, die seine Archiv aufzeichnet, und Ihrer Anwendung, die eine Versuchsregister schreibt. Wenn ein Unfall dort landen, kann der nächste Rennen berichtet über verschwunden. Für einen Service vereinigen Sie die filesystem/archive mit einer nachhaltigen Arbeitsdatenbank anstatt zu behaupten, dass dieses Textdatei-Beispiel ist transaktionell.

Halten Sie attempts.jsonl privat: Fehler können Quell- und Anfragedetails enthalten. Berichten Sie Gesamtzahl nach Status, überprüfen Sie die fehlenden Elemente und wiederholen Sie das gleiche Manifest nach der Lösung eines gemeinsamen Umweltproblems. fügen Sie nicht jedes fehlende ID in den Erfolgsgeschäft hinzu.

Produktion: Quelle, Fristen und Lagerung

YoutubeDL ist synchronisch. Durchführen Sie es direkt in einem asynch-web-handler block, die handler's event loop; selbst ein thread offload macht nicht einen browser-anfrage eine angemessene lebensdauer für einen großen download. Akzeptieren Sie die Arbeit, halten Sie sie source/options fort und lassen Sie einen Arbeitnehmer ein endgültiges Ergebnis erzielen.

  • Erstellen Sie eine nachhaltige Job-ID vor der Ausführung. Speichern Sie die Canon Video-ID, Ausgangsbestimmungen, Versuchnummer und Zielort.
  • Verwenden Sie per-job-Arbeitdirektionen und eine begrenzte Arbeitskräfte. teilen Sie keine YoutubeDL-Einstellung über gleichzeitige Jobs.
  • Verwenden Sie einen separaten Prozess, wenn Sie eine harte Wänderaufzeit oder eine Löschung benötigen; socket_timeout beschränkt die einzelnen Netzwerkverkehrsaktivitäten, nicht die gesamte Arbeit.
  • Wenn Sie Benutzerinträge über HTTP exponieren, akzeptieren Sie unterstützte YouTube-Video-IDs anstatt arbiträre URLs, Ausgangswege, Extractor-Argumente oder Shell-Snippets.
  • Erhalten Sie die lokalen Datei-Vertrauen und die Cloud-Upload-Filme separat; halten Sie genug Status, um eine Upload ohne erneut herunterladen zu retreeren.
  • Halten Sie FFmpeg, runtime, yt-dlp und Plugin-Versionen mit Ihrer Entfernung. Üben Sie eine kleine bekannte Workload vor dem Ersatz eines Arbeiters Bild.

Ein einfacher Workers Pool ist ein besseres Ausgangspunkt als unbegrenzte Asyncio.gather rufen um viele Downloads. Koordinieren Sie die Gesamtarbeit durch Prozesse; die Schlaf-Einstellungen jedes Downloaders regulieren nicht den gesamten Service. Halten Sie einen separaten Retry-Budget für Arbeitsversuche so dass die Anwendung Retries nicht die eigene Retry-Zahl des Downloader multiplizieren.

Beendigung der Python-Arbeiter

ProblemÜberprüfung
Arbeiten in der CLI, fehlend in PythonVergleichen Sie die tatsächlichen Optionen. YoutubeDL laden Ihre CLI-Konfigurationsdatei nicht automatisch auf.
Fortschritt sagt fertig, Datei fehltVerwenden Sie die after_move Grenze und überprüfen Sie Post-Verarbeitung Fehler.
Wiederholte Quelle Rückkehr verschwundenLesen Sie das Sammelarchiv; verwenden Sie ein anderes Archiv, wenn Sie die Ausgangsbestimmungen ändern.
Die Arbeitnehmer hängen länger als socket_timeoutEin Job kann viele operations/retries. Ausführen, wenn nötig, ein Prozess-Level-Frist hinzufügen.
403 oder bot überprüft auf dem serverAktualisieren Sie die Nacht, überprüfen Sie Deno, reduzieren Sie die Konkurrenz und testen Sie eine Ersatz-Exit-IP, wenn die Route abgelehnt bleibt.
429 in Metadaten / Transcript JobsPause die betroffenen IP, Rate extraction/subtitle Anfragen und fügen Sie Verzögerungen zwischen Metadaten-nur Jobs hinzu.

Wenn die Produktion in einem Cloud-Pipeline gehört

Wenn Sie den Download-System besitzen möchten, geben Ihnen die oben genannten Workflows Kontrolle über Dateien, Formate und Verarbeitung. Wenn Ihre Anwendung vollständig aufgeführte Medien zur Speicherung benötigt, bietet FlashData traceed YouTube-Download-Arbeits, Bot-Management, Proxy-Routing und Retries. Ihre Anwendung stellt die Quell- und Ausgangsinstellungen ein, dann hält sie die Arbeits-ID und Lieferungspapier.