# Python-API van yt-dlp

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

Canonische referentie: https://flashdata.dev/nl/docs/guides/yt-dlp-python-api
Beoordeeld: 2026-11-13 door FlashData

- [Begin met Python](https://flashdata.dev/nl/docs/guides/yt-dlp-python-api/reference.md#first-call) — Installeer en maak een oproep
- [Vind het laatste bestand](https://flashdata.dev/nl/docs/guides/yt-dlp-python-api/reference.md#completion) — Na overdracht en verwerking
- [Ga de werknemer](https://flashdata.dev/nl/docs/guides/yt-dlp-python-api/reference.md#worker) — Download van .py
- [Een collectie verwerken](https://flashdata.dev/nl/docs/guides/yt-dlp-python-api/reference.md#batch) — Per-bron resultaten en herstel

<a id="setup"></a>

## Installeer de Python bibliotheek


**In uw Python 3.11+ omgeving**

```bash
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.

- [Installeren van externe afhankelijkheden](https://flashdata.dev/nl/docs/guides/how-to-use-yt-dlp/reference.md#install)
- [Upstream embedding referentie](https://github.com/yt-dlp/yt-dlp#embedding-yt-dlp)

<a id="first-call"></a>

## Download je eerste video


**Download een video**

```python
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.

> **Python-opties zijn geen mechanische vertalingen van vlaggen**
> --write-info-json kaarten om te schrijveninfojson; --no-playlist kaarten om noplaylist. Audio conversie maakt gebruik van een postprocessorlijst. Zoek de parametersdocumentatie van YoutubeDL of de upstream cli_to_api.py helper in plaats van de optie namen te getuigen.

<a id="metadata"></a>

## Metadata lezen zonder media


**Een kleine metadata-record uit te brengen**

```python
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.

<a id="options"></a>

## Python optie referentie


| Taak | Python optie | Detail |
| --- | --- | --- |
| 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": True | Keep volledige extractietaten naast de media. |
| Volledige ID checkpoint | "download_archive": "archive.txt" | Een archief per uitvoerbeleid; geen checksum inventaris. |
| Strikte fouten | "ignoreerrors": False | Laat 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**

```python
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.

- [Python parameter verwijzing](https://github.com/yt-dlp/yt-dlp/blob/master/yt_dlp/YoutubeDL.py)
- [Convert CLI opties naar Python opties](https://github.com/yt-dlp/yt-dlp/blob/master/devscripts/cli_to_api.py)

<a id="dataset"></a>

## 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**

```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 media | Wat de dataset-record nodig heeft |
| --- | --- |
| Bekijk de laatste MP4 met ffprobe | Video/audio codecs, duur, dimensies, bestand pad en byte tellen. |
| Check caption zijkantjes afzonderlijk | Taal, supplied/automatic track, timestamps en of de bestand echt bestaat. |
| Geen matching capties beschikbaar | Houd de media en merk tekst ontbreken; stuur audio naar uw transcriptie fase indien nodig. |
| De kapsels zijn getekend 429 | Retry 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.

- [CLI recept en dataset inventaris](https://flashdata.dev/nl/docs/guides/how-to-use-yt-dlp/reference.md#dataset)
- [Pace Python metadata en capties](https://flashdata.dev/nl/docs/guides/yt-dlp-429-too-many-requests/reference.md#python)

<a id="completion"></a>

## 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.

| Fase | Wat je weet | Aanvullingsstaat |
| --- | --- | --- |
| Downloaden | Sommige media bytes komen er aan. | Rennen |
| Transfer hook: klaar | Deze overdracht is afgerond; de verwerking kan nog steeds worden gevolgd. | verwerking |
| after_move Postprocessor | De bestand heeft de geconfigureerde post-verwerking en de uiteindelijke beweging overgenomen. | Locale bestanden klaar |
| Upload en integriteit check | Uw 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.

> **Een voltooide lokale download is geen voltooide cloudlevering**
> Als de volgende stap het bestand uploadt, houd een uploaden staat apart. Een download archief kan een bron op de volgende ronde overwinnen, zelfs wanneer de vorige uploaden mislukt.

<a id="worker"></a>

## 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 van download_video.py](https://flashdata.dev/examples/yt-dlp/download_video.py)

**download_video.py**

```python
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**

```bash
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.

<a id="batch"></a>

## 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 van download_batch.py](https://flashdata.dev/examples/yt-dlp/download_batch.py)

**download_batch.py**

```python
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**

```bash
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.

<a id="service"></a>

## 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.

<a id="diagnostics"></a>

## Ontwikkel de Python-werknemers


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

- [403 Diagnose werkstromen](https://flashdata.dev/nl/docs/guides/yt-dlp-403-forbidden/reference.md)
- [Sessie en bot-check workflow](https://flashdata.dev/nl/docs/guides/yt-dlp-sign-in-not-a-bot/reference.md)
- [429 herstel en Python pacing](https://flashdata.dev/nl/docs/guides/yt-dlp-429-too-many-requests/reference.md)
- [Bekijk de gered media](https://flashdata.dev/nl/docs/guides/how-to-use-yt-dlp/reference.md#verify)

<a id="managed-downloads"></a>

## 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.

- [Vergelijk de twee operationele modellen](https://flashdata.dev/nl/docs/guides/flashdata-vs-yt-dlp/reference.md)
- [YouTube-video’s in bulk downloaden](https://flashdata.dev/nl/products/youtube-download#bulk-downloads)
- [Probeer de download demo](https://flashdata.dev/nl/products/youtube-download#playground)
- [Download API verwijzing](https://flashdata.dev/nl/docs/sources/youtube_download/reference.md)
