Dokumentation durchsuchen
Anleitungen
Ausführbare Python-Beispiele für Downloads, Metadaten, KI-Datensätze und fortsetzbare Aufträge.
Auf dieser Seite
Installation der Python-Bibliothek
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
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-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
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))
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
| Aufgabe | Python Option | Details |
|---|---|---|
| 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": True | Keeps 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": False | Lassen 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. |
audio_options = {
"format": "ba",
"outtmpl": "audio/%(id)s.%(ext)s",
"postprocessors": [{
"key": "FFmpegExtractAudio",
"preferredcodec": "mp3",
"preferredquality": "192",
}],
}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.
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() 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 Medien | Was die Datensatz-Register benötigt |
|---|---|
| Schauen Sie sich die letzte MP4 mit ffprobe an | Video/audio Codecs, Dauer, Dimensionen, Dateiweg und Byte-Zahl. |
| Check caption Seitenkarten separat | Sprache, supplied/automatic-Track, Zeiten und ob die Datei tatsächlich existiert. |
| Keine matching captions verfügbar | Halten Sie die Medien und markieren Sie den Text fehlend; senden Sie Audio zu Ihrem Transcription-Spiegel, wenn erforderlich. |
| Die Kaptionen schlagen 429 | Retry 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.
| Phase | Was du weißt | Anwendungszustand |
|---|---|---|
| Downloaden | Einige Medienbiten kommen. | Laufen |
| Transfer Hook: Fertig | Dieser Transfer ist beendet; die Verarbeitung kann noch folgen. | Verarbeitung |
| after_move Post-Prozessor | Die Datei hat die konfigurierte Post-Verarbeitung und endgültige Bewegung durchgeführt. | Lokale Datei bereit |
| Upgrade und Integrität Check | Ihr 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.
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 downloadsDie 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.
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 collectionFlush 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 Python | Vergleichen Sie die tatsächlichen Optionen. YoutubeDL laden Ihre CLI-Konfigurationsdatei nicht automatisch auf. |
| Fortschritt sagt fertig, Datei fehlt | Verwenden Sie die after_move Grenze und überprüfen Sie Post-Verarbeitung Fehler. |
| Wiederholte Quelle Rückkehr verschwunden | Lesen Sie das Sammelarchiv; verwenden Sie ein anderes Archiv, wenn Sie die Ausgangsbestimmungen ändern. |
| Die Arbeitnehmer hängen länger als socket_timeout | Ein Job kann viele operations/retries. Ausführen, wenn nötig, ein Prozess-Level-Frist hinzufügen. |
| 403 oder bot überprüft auf dem server | Aktualisieren 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 Jobs | Pause 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.