Ga naar de inhoud
NL
API-sleutel ophalen
Documentatie bekijken

Handleidingen

Python-API van yt-dlp

Uitvoerbare Python-voorbeelden voor downloads, metadata, AI-datasets en taken die je kunt hervatten.

Op deze pagina

Installeer de Python bibliotheek

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

Installeer ook Deno, FFmpeg en ffprobe. Deze voorbeelden werken lokaal op Linux, macOS of Windows en hebben geen API-toets nodig.

Download je eerste video

Download een 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"])
Dit schrijft lokale media tot 1080p en kan afzonderlijke stromen samengebracht. de uitgangscontainer hangt af van de geselecteerde bronformaten.

CLI-instellingen zijn niet geëerd. Set Deno, personalisatie en pacing in de Python-opties, zelfs wanneer uw terminalbestelling ze al gebruikt.

download() neemt een lijst met URL's en geeft een statuscode terug. extract_info(url, download=True) geeft extractinformatie terug, evenals het uitvoeren van de download. Gebruik een contextmanager om het voorbeeld schoon te sluiten en creëren een nieuw voorbeeld voor een onafhankelijke baan in plaats van de veranderlijke staat over de draad te delen.

Metadata lezen zonder media

Een kleine metadata-record uit te brengen
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 doet nog steeds netwerkverzoeken. sanitize_info maakt het resultaat JSON-compatibel; het redt geen geheimen of vermindert het resultaat naar deze velden.

De geëxtrakteerde velden kunnen afwezig of nul zijn. Gebruik get() voor optionele metadata en veronderstel niet dat elke bron een duur, kanaal-ID of volledige formatslijst heeft. Een flat playlist lijst is ook anders dan een volledig opgelost video. Voor een openbare reactie, project alleen de velden die u van plan bent te blootstellen.

Vermijd een metadata-extractie onmiddellijk gevolgd door een identieke download-extractie voor elke bron, tenzij uw applicatie de extra planningstep nodig heeft. Het dupliceren van de bronverzoeken. Als u een duurzame baan nodig hebt, sla dan de bron-ID en het uitgangsbeleid op; een ondertekend media-URL van de metadata is geen duurzame vervanging voor de oorspronkelijke bron.

Python optie referentie

TaakPython optieDetail
Uitgangsdirectie en filename"outtmpl": "downloads/%(id)s.%(ext)s"Houd de bron-ID en dynamische uitbreiding vast.
Hard 1080p dak"format": "bv*[height<=1080]+ba/b[height<=1080]"Toegeeft source codecs en faalt als er geen van de limiet overeenkomt.
Metadata sidecar"writeinfojson": TrueKeep volledige extractietaten naast de media.
Volledige ID checkpoint"download_archive": "archive.txt"Een archief per uitvoerbeleid; geen checksum inventaris.
Strikte fouten"ignoreerrors": FalseLaat de oproepgever fouten opnemen in plaats van post-processing problemen als succes behandelen.
De Runtime"js_runtimes": {"deno": {}}Installeren Deno in de werknemer en maken zijn binaire zichtbaar op PATH.
Browser Impersoonlijn"impersonate": ImpersonateTarget()Python equivalent van --impersonate=""; de doelklasse invoeren en installeren curl-cffi.
bestaande cookie bestanden"cookiefile": "private/youtube-cookies.txt"Gebruik privé-session-creditials alleen wanneer het nodig is voor toegang.
MP3 Conversie opties
audio_options = {
    "format": "ba",
    "outtmpl": "audio/%(id)s.%(ext)s",
    "postprocessors": [{
        "key": "FFmpegExtractAudio",
        "preferredcodec": "mp3",
        "preferredquality": "192",
    }],
}
Pass audio_options naar YoutubeDL. De FFmpeg post-processor converteert naar een doelbitrate van 192 kbps; het verbetert niet de oorspronkelijke kwaliteit van de bron.

Video + audio + capties voor een AI-dataset

Gebruik dit output beleid wanneer het doel een training dataset is in plaats van de verzameling van de werknemer voorbeeld 1080p. Het vereist bestvideo en bestaudio, laat FFmpeg ze combineren in MP4, en slaat beschikbare Engelse capties en metadata naast de media op.

Een dataset item 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])
Verplicht FFmpeg/ffprobe, Deno en de nachtelijke [default,curl-cffi] installatie. de voorkeursformatparameters van de remuxer worden op die manier weergegeven in de API van yt-dlp.

ImpersonateTarget() selecteert een beschikbare browserdoel, die overeenkomt met --impersonate="". Pass het object, niet een lege string gecopiëerd van CLI syntax. curl-cffi moet worden geïnstalleerd in deze Python-omgeving. Deno werkt nog steeds JavaScript oplossen; impersonatie vervangt het niet.

MP4 is de uitgangscontainer; de geselecteerde video kan nog steeds AV1 of VP9 zijn. Als uw training decoder H.264/AAC vereist, toepast u een uitdrukkelijke codecbeleid voordat u een afzonderlijke FFmpeg transcode fusieert of opneemt. De beschikbare ondertitels worden teruggebracht, niet van de toespraak.

Na het einde van de mediaWat de dataset-record nodig heeft
Bekijk de laatste MP4 met ffprobeVideo/audio codecs, duur, dimensies, bestand pad en byte tellen.
Check caption zijkantjes afzonderlijkTaal, supplied/automatic track, timestamps en of de bestand echt bestaat.
Geen matching capties beschikbaarHoud de media en merk tekst ontbreken; stuur audio naar uw transcriptie fase indien nodig.
De kapsels zijn getekend 429Retry caption retrieval na een IP cooldown met subtitle pacing; niet de voltooide media te herdownload.

Voor een set, gebruik een afzonderlijke archief voor dit dataset beleid en bewaar een inventaris voor de vereiste zijdeecars. Gebruik geen eerder 1080p of media-only archief: het kan video's verlaten voordat hun nieuw vereiste capties worden verzameld. Gebruik after_move voor media klaarheid, valideren dan tekst en metadata voordat u een volledige dataset item publiceren.

Weet wanneer de laatste bestand klaar is

Een progress hook rapportage status = afgerond betekent een overdracht afgerond. FFmpeg kan nog steeds nodig zijn om video en audio te combineren, een audiobestand te converteren of de uitgang te verplaatsen. Een video-eigen stream bereiken 100% is niet het voltooid evenement uw aanvraag moet publiceren.

FaseWat je weetAanvullingsstaat
DownloadenSommige media bytes komen er aan.Rennen
Transfer hook: klaarDeze overdracht is afgerond; de verwerking kan nog steeds worden gevolgd.verwerking
after_move PostprocessorDe bestand heeft de geconfigureerde post-verwerking en de uiteindelijke beweging overgenomen.Locale bestanden klaar
Upload en integriteit checkUw bestemming heeft het object en geregistreerde verificatie.Leverde

Het volledige voorbeeld hieronder registreert een aangepaste PostProcessor op after_move en leest info["filepath"] daar. Het controleert dat de bestand bestaat en onuitputtelijk is. Dit vermijdt het verwachten van de laatste uitbreiding met prepare_filename(), die kan verwijzen naar een pre-conversie naam.

Complete script: single-video worker

Hiermee kunt u download_video.py gebruiken. Het accepteert een video-ID of watch/Shorts/live/embed URL en weigert playlist/channel input. Elke oproep maakt gebruik van één YoutubeDL-instantie, beperkte downloaderretries en een collectie-locale archief. Een herhaaldelijke voltooide bron-retouren worden verlaten in plaats van een nieuw bestand te pretenden gemaakt.

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))
Het volledige script is ook beschikbaar vanaf de downloadlink hierboven. het bezit alleen lokale output; voeg decodering checks toe en upload records in de volgende fase van uw toepassing.
1 Een werk doen
python download_video.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --output downloads

De voltooide record bevat de canonische bron URL, video-ID, eindpad en byte-grootte. Een geschorst record betekent geen nieuwe definitieve bestand callback; het op elkaar brengen tegen het archief en bestaande inventory als u bewijs nodig het bestand is nog steeds aanwezig. Het archief alleen controleert niet of een gebruiker later de media heeft verwijderd of verplaatst.

Catch DownloadError voor extractor/download/post-processing-fouten, ValueError voor afgewezen input en OSError voor lokale bestandsysteemfouten. Behandel deze als onderscheidende klassen in uw applicatielogs. Error berichten zijn nuttige diagnoses, maar hun tekst is niet een stabiele gestructureerde taxonomie van elke YouTube-fout.

Complete script: herhaaldbare batch worker

Laat download_batch.py naast download_video.py plaatsen. Creëer een UTF-8 urls.txt met één video URL of ID per lijn. Dit loopt intentioneel op een sequentiële manier, dus één proces is eigendom van het archief- en output-director. Het schrijft een voltooide, gesloten of mislukt resultaat voor elke geprobeerde input en uitgang nonzero wanneer een item mislukt.

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)
De append-only attempts.jsonl houdt retries als afzonderlijke pogingen. Duplicate lijnen binnen een manifest worden verwijderd; het downloadsarchief handels voltooide ID's over de loop.
Run of reageer op dezelfde batch
python download_batch.py urls.txt --output collection

Flush na elke record zodat een onderbreking niet laat elk resultaat buffer tot het einde. Er is nog steeds een klein venster tussen de bibliotheek die zijn archief opneemt en uw applicatie een pogingsrecord schrijft. Als er een ongeluk landt, kan de volgende ronde verslag over het verlaten. Voor een service, de filesystem/archive met een duurzame job database te verzoeken in plaats van dit tekstbestand voorbeeld is transactief.

Houd attempts.jsonl privé: fouten kunnen bronnen en verzoeken details bevatten. verslag totalen per status, inspecteer de mislukte items en herspel hetzelfde manifest na het oplossen van een gedeelde omgevingsprobleem. Voeg niet elke mislukte ID toe aan het succesarchief.

Productie: kooi, deadlines en opslag

YoutubeDL is synchronisch. Het draaien van het rechtstreeks binnen een async web handler blokken dat de handleider event loop; zelfs een thread offload maakt geen browser aanvraag een geschikte levensduur voor een grote download. Accepteer de baan, blijf haar source/options en laat een werknemer een eindresultaat produceren.

  • Creëer een duurzame job ID voor uitvoering. bewaar de canonische video ID, output policy, tent-number en bestemming.
  • Gebruik per-job werkdirectieven en een beperkte werkbank. Deel geen YoutubeDL-instelling over concurrerende banen.
  • Gebruik een aparte proces wanneer u een harde muur-hour deadline of annulering nodig heeft; socket_timeout beperkt individuele netwerkactiviteiten, niet het hele werk.
  • Als u gebruikersinvoer over HTTP blootstelt, accepteert u ondersteunde YouTube-video-identificatoren in plaats van arbitrarische URL's, uitgangspuiten, extractorargumenten of shell snippets.
  • Record de lokale bestandbereidheid en cloud-upload-volledige afzonderlijk; houd voldoende staat om een upload terug te trekken zonder opnieuw te downloaden.
  • Houd FFmpeg, runtime, yt-dlp en plug-in versies met uw implementatie. oefenen een kleine bekende werkbelasting voordat u een werknemersbeeld vervangt.

Een eenvoudige werkerspools is een betere startpunt dan onbeperkte asyncio.gather roepen rond vele downloads. Coördineren van het totale werk door middel van processen; de slaapinstellingen van elke downloader regelen niet de hele service. Houd een afzonderlijke retry budget voor werkpogingen, zodat de aanvraag retries niet het eigen retry-titel van de downloader vermenigvuldigen.

Ontwikkel de Python-werknemers

ProbleemControleren
Werken in de CLI, mislukken in PythonYoutubeDL laden uw CLI-configuratiebestand niet automatisch op.
Progress zegt klaar, bestanden ontbrekenGebruik de after_move grens en inspecteer post-verwerking fouten.
Herhaalde bron teruggekeerdLees het collectiearchief; gebruik een ander archief bij het wijzigen van de outputbeleid.
De werknemer hangt langer dan socket_timeoutEen baan kan veel operations/retries. uitvoeren Voeg een procesniveau deadline toe indien nodig.
403 of bot checks op de serverUpdate 's nachts, check Deno, verminderen concurrentie en testen een vervangende IP-uitgang wanneer de route wordt weigerd.
429 in metadata / transcript jobsStop de aangetaste IP, tempo extraction/subtitle verzoeken en voeg vertragingen toe tussen metadata-only jobs.

Wanneer de uitstoot behoort tot een cloudpipe

Als u de downloader wilt bezitten, geven de bovenstaande werkstromen u controle over bestanden, formaten en verwerking. Als uw applicatie een voltooide media nodig heeft die naar opslag is geleverd, biedt FlashData traceerde YouTube-download jobs, botbehandeling, proxy-routing en retries. Uw aanvraag stuurt de bron- en uitgangsinstellingen, behoudt vervolgens het werk-ID en leveringsprekend.