Salta al contenuto
IT
Ottieni la chiave API
Sfoglia la documentazione

Guide

API Python di yt-dlp

Esempi Python eseguibili per download, metadati, dataset per l’IA e processi che possono essere ripresi.

In questa pagina

Installare la biblioteca Python

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

Installa anche Deno, FFmpeg e ffprobe. Questi esempi funzionano localmente su Linux, macOS o Windows e non hanno bisogno di una chiave API.

Scarica il tuo primo video

Scarica un 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"])
Questo scrive i media locali fino a 1080p e può fusione di flussi separati. il contenitore di uscita dipende dai formati di sorgente selezionati.

Le impostazioni CLI non sono ereditate. Imposta il Deno, la personificazione e il pacing nelle opzioni Python, anche quando il tuo comando terminale li utilizza già.

download() prende una lista di URL e restituisce un codice di stato. extract_info(url, download=True) restituisce le informazioni di estrazione nonché l'esecuzione del download. Utilizzare un contesto manager per chiudere l'esempio pulito, e creare un nuovo esempio per un lavoro indipendente piuttosto che condividere uno stato mutabile in tutta la linea.

Leggi i metadati senza media

Esportare un piccolo record di metadati
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 ancora esegue richieste di rete. sanitize_info rende il risultato JSON-compatibile; non redaction segreti o riduce il risultato a questi campi.

I campi extravi possono essere assenti o nulli. Utilizzare get() per metadati opzionali, e non presumere che ogni fonte abbia una durata, ID canale o una lista completa di formati. Un elenco di playlist piatto è anche diverso da un video completamente risoluto. Per una risposta pubblica, progettare solo i campi che intendi esponere.

Evitare un'estrazione dei metadati immediatamente seguita da un'estrazione di download identica per ogni fonte a meno che la tua applicazione non abbia bisogno del passo di pianificazione aggiuntivo. duplicata delle richieste di sorgente. Se hai bisogno di un lavoro duraturo, memorizza l'ID fonte e la politica di uscita; un URL di media firmato dai metadati non è un sostituto duraturo per la fonte originale.

Python Opzione di riferimento

CompitiOpzione PythonDettagli
Il nome e la directory di uscita"outtmpl": "downloads/%(id)s.%(ext)s"Mantenere l'ID di fonte e l'estensione dinamica.
Il tetto di Hard 1080p"format": "bv*[height<=1080]+ba/b[height<=1080]"Permette codec di sorgente e fallisce se nessuno corrisponde al limite.
Metadati di Sido"writeinfojson": TrueIl metadato di estrazione completa è inserito accanto ai media.
Il checkpoint di ID"download_archive": "archive.txt"Un archivio per politica di produzione; non un inventario di controllo.
errori rigorosi"ignoreerrors": FalseLascia che il chiamante registri i fallimenti invece di trattare i problemi post-processing come successo.
Il tempo di runtime"js_runtimes": {"deno": {}}Installare Deno nel lavoratore e rendere visibile il suo binario su PATH.
Impersonazione del browser"impersonate": ImpersonateTarget()Python equivalente di --impersonate=""; importare la classe target e installare curl-cffi.
Cookie esistenti"cookiefile": "private/youtube-cookies.txt"Utilizzare le credenziali sessioni private solo quando necessario per l'accesso.
MP3 Opzioni di conversione
audio_options = {
    "format": "ba",
    "outtmpl": "audio/%(id)s.%(ext)s",
    "postprocessors": [{
        "key": "FFmpegExtractAudio",
        "preferredcodec": "mp3",
        "preferredquality": "192",
    }],
}
Passare audio_options a YoutubeDL. Il post-processore FFmpeg si converte in una bitrate mirata di 192 kbps; non migliora la qualità originale della fonte.

Video + audio + capzioni per un database AI

Utilizzare questa politica di uscita quando l'obiettivo è un set di dati di formazione piuttosto che la raccolta dell'esempio del lavoratore 1080p. richiede bestvideo e bestaudio, permette FFmpeg di fusione in MP4, e salva le capture e i metadati disponibili in inglese accanto ai media.

Un elemento di set dati 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])
Require FFmpeg/ffprobe, Deno e l'installazione notturna [default,curl-cffi] Il parametro di formato preferito del remuxer è visualizzato in questo modo nell'API di yt-dlp.

ImpersonateTarget() seleziona qualsiasi target del browser disponibile, corrispondendo --impersonate="". Passare l'oggetto, non una riga vuota copiata dalla sintasi CLI. curl-cffi deve essere installato in questo ambiente Python. Deno continua a svolgere la risoluzione JavaScript; impersonazione non lo sostituisce.

MP4 è il contenitore di uscita; il video selezionato può ancora essere AV1 o VP9. Se il tuo decoder di formazione richiede H.264/AAC, applicare una politica esplicita di codec prima di unire o registrare un transcodio separato FFmpeg. I sottotitoli disponibili sono recuperati, non generati dal discorso.

Dopo che i media finisconoCosa ha bisogno il registro dei dati
Scopri il finale MP4 con ffprobeVideo/audio codec, durata, dimensioni, percorso di file e conte byte.
Controlla le carattere laterali separatamenteLingua, traccia supplied/automatic, timestamp e se il file esiste effettivamente.
Nessuna capienza di matching disponibileMantenere i media e segnalare il testo mancante; inviare l'audio alla fase di transcrizione se necessario.
Il cappello è stato colpito 429Retry caption retrieval dopo un IP cooldown con subtitle pacing; non ricaricare i media completati.

Per un pacchetto, utilizzare un archivio separato per questa politica del set di dati e conservare un inventario per le pagine richieste. Non riutilizzare un precedente 1080p o solo archivio media: può scappare i video prima che le loro capture di nuova richiesta siano raccolte. Utilizzare after_move per la disponibilità dei media, quindi valutare testo e metadati prima di pubblicare un elemento completo del set di dati.

Scopri quando il file finale è pronto

Un progresso hook reporting status=finished significa un trasferimento terminato. FFmpeg può ancora essere necessario mescolare video e audio, convertire un file audio, o spostare la produzione. Un video solo in streaming raggiungendo 100% non è l'evento di completamento che la tua domanda dovrebbe pubblicare.

FaseCosa saiStato di applicazione
ScaricaArrivano alcuni byte di media.Correndo
Trasferimento di HOK: finitoQuesto trasferimento è finito; il trattamento può ancora essere seguito.Il trattamento
after_move Il post-processoreIl file ha superato il post-processing configurato e il passo finale.Il file locale pronto
Caricamento e controllo dell'integritàIl tuo destinazione ha l'oggetto e la verifica registrata.consegnato

L'esempio completo qui sotto registra un PostProcessor personalizzato a after_move e legge info["filepath"] lì. Verifica che il file esiste e non è esente. Questo evita la ipotesi della estensione finale con prepare_filename(), che può riferirsi a un nome pre-conversione.

Sceneggiatura completa: singolo video lavoratore

Questo è il modo in cui download_video.py Accetta un ID video o watch/Shorts/live/embed URL e rifiuta l'ingresso playlist/channel. Ogni invocazione utilizza un’esempio YoutubeDL, ritorni di download limitati e un archivio locale. Un ripetuto ritorno di fonte completato è scappato invece di pretendere che un nuovo file sia stato creato.

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))
Il script completo è disponibile anche dal link di download sopra. ha solo la produzione locale; aggiungere controlli di decodifica e caricamento dei record nella fase successiva della tua applicazione.
Fai un lavoro
python download_video.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --output downloads

Il record completato contiene l'URL canonico della fonte, l'ID video, la strada finale e la dimensione del byte. Un record scappato significa che non c'è alcun nuovo file finale di ritorno; conciliarlo contro l'archivio e l'inventario esistente se si richiede la prova che il file è ancora presente. L’archivio non verifica se un utente ha cancellato o spostato i media in seguito.

Catch DownloadError per errori extractor/download/post-processing, ValueError per input rifiutati e OSError per errori del sistema di file locale. Tratta queste classi come classi distinte nei tuoi log di applicazione. I messaggi di errore sono diagnostiche utili, ma il loro testo non è una tassonomia stabile e strutturata di ogni fallimento di YouTube.

Sceneggiatura completa: ripetibile batch worker

Inserisci download_batch.py accanto a download_video.py. Crea un UTF-8 urls.txt con un URL video o ID per linea. Questo funziona intenzionalmente in modo sequenziale, quindi un processo è di proprietà dell'archivio e del directory di uscita. Esso scrive un risultato completato, scappato o fallito per ogni tentativo di input e outs non zero quando qualsiasi elemento fallisce.

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)
L'append-only attempts.jsonl mantiene le retrazioni come tentative separate. le linee duplicate all'interno di un manifesto vengono rimosse; il file di download mantiene i ID completati in tutto il corso.
Raggiungere o riprendere lo stesso batch
python download_batch.py urls.txt --output collection

Flush dopo ogni record in modo che una interruzione non lascia ogni risultato bufferato fino alla fine. C'è ancora una piccola finestra tra la biblioteca che registra il suo archivio e la tua applicazione che scrive un record di tentativo. Se un incidente si colloca lì, il prossimo giro può segnalare scappato. Per un servizio, conciliare il filesystem/archive con una base di lavoro duratura invece di affermare che questo esempio di file di testo è transazionale.

Mantenere attempts.jsonl privato: gli errori possono includere i dettagli di fonte e richiesta. Rapporti i totali per stato, verifica gli elementi falliti e riproduce lo stesso manifesto dopo aver risolto un problema ambientale condiviso. Non aggiungere ogni ID fallito all'archivio di successo.

Produzione: coda, scadenza e storage

Youtube è sincronizzato. Eseguire direttamente all'interno di un blocco di web trader async che il loop degli eventi del trader; anche un thread offload non rende una richiesta del browser una vita adeguata per un grande download. Accettate il lavoro, persistete source/options e lasciate che un lavoratore produca un risultato finale.

  • Crea un ID di lavoro duraturo prima di eseguire. memorizzare il canonico ID video, la politica di uscita, il numero di tentativo e la destinazione.
  • Utilizzare directories di lavoro per lavoro e una piscina lavoratrice limitata. Non condividere un esempio YoutubeDL su posti di lavoro concorrenti.
  • Utilizzare un processo separato quando si ha bisogno di un termine o cancellazione di un duro muro; socket_timeout limita le operazioni di rete individuali, non l'intero lavoro.
  • Se esponendo input utente sopra HTTP, accettare i video supportati YouTube identificatori piuttosto che URL arbitrari, percorsi di uscita, argomenti di estrattore o scatti di scatto.
  • Ricordare la disponibilità del file locale e la completione del cloud-upload separatamente; mantenere lo stato sufficiente per ritirare un upload senza scaricare di nuovo.
  • Mantenere FFmpeg, tempo di esecuzione, yt-dlp e versioni di plugin con il vostro implementazione. Esercitare una piccola carica di lavoro conosciuta prima di sostituire un'immagine del lavoratore.

Una semplice piscina di lavoratori è un punto di partenza migliore rispetto a un'asyncio.gather non limitata chiama intorno a molti download. Coordinare il lavoro totale in tutto il processo; le impostazioni del sonno di ciascun download non regolano l'intero servizio. Mantenere un budget di ritiro separato per tentativi di lavoro in modo che le retrazioni di applicazione non moltiplicino il numero di ritiro del download.

Risolvere il problema del lavoratore Python

ProblematicheControlla
Lavori in CLI, falliscono in PythonConfronta le opzioni efficaci. YoutubeDL non carica automaticamente il file di configurazione CLI.
Il progresso dice finito, file mancantiUtilizzare il limite after_move e controllare gli errori post-processing.
Ripetuto ritorno di fonte scappatoLeggi l'archivio della raccolta; utilizzare un archivio diverso quando si modifica la politica di uscita.
Il lavoratore si è impiccato più a lungo socket_timeoutUn lavoro può eseguire molti operations/retries. Aggiungi un termine di livello del processo se necessario.
403 o il bot verifica sul serverAggiornare di notte, controllare Deno, ridurre la concorrenza e testare un IP di uscita sostitutiva quando la rotta rimane rifiutata.
429 in metadati / lavori di trascrizioneParare l'IP colpito, le richieste di ritmo extraction/subtitle e aggiungere ritardamenti tra i metadati-solo lavori.

Quando la produzione appartiene a un tubo cloud

Se si desidera possedere il download, i flussi di lavoro sopra ti danno il controllo sui file, i formati e il trattamento. Se la tua applicazione ha bisogno di media completati forniti al storage, FlashData fornisce posti di lavoro di download YouTube tracciati, bot di gestione, routing proxy e ritrazioni. La tua domanda presenta le impostazioni di fonte e di uscita, quindi mantiene l'ID di lavoro e il registro di consegna.