Aller au contenu
FR
Obtenir une clé API
Parcourir la documentation

Guides

API Python de yt-dlp

Exemples Python exécutables pour télécharger des fichiers, récupérer les métadonnées, créer des jeux de données pour l’IA et reprendre des tâches.

Sur cette page

Installation de la bibliothèque Python

Dans votre environnement Python 3.11+
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"

Installez également Deno, FFmpeg et ffprobe. Ces exemples fonctionnent localement sur Linux, macOS ou Windows et ne nécessitent pas de clé API.

Téléchargez votre premier vidéo

Téléchargez un vidéo
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"])
Cela écrit les médias locaux jusqu'à 1080p et peut fusionner des courants séparés. le conteneur de sortie dépend des formats source sélectionnés.

Les paramètres CLI ne sont pas hérités. Sélectionnez Deno, personnalisation et pacing dans les options Python, même lorsque votre commande terminal les utilise déjà.

download() prend une liste d'URL et retourne un code de statut. extract_info(url, download=True) retourne les informations d'extraction ainsi que l'exécution du téléchargement. Utilisez un gestionnaire de contexte pour fermer l'instance de manière propre, et créer une nouvelle instance pour un travail indépendant plutôt que de partager un état mutable sur les filets.

Lire les méta-détails sans médias

Exporter un petit fichier de métadonnées
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 exécute encore les demandes réseau. sanitize_info rend le résultat JSON compatible; il ne rédige pas les secrets ou réduit le résultat à ces champs.

Les champs extraits peuvent être absents ou null. Utilisez Get() pour les métadonnées facultatives, et ne supposez pas que chaque source a une durée, un identifiant de canal ou une liste complète de format. Une liste de playlist plate est également différente d'un vidéo entièrement résolu. Pour une réponse publique, projettez uniquement les champs que vous prévoyez exposer.

Évitez une extraction de métadonnées immédiatement suivie d’une extraction de téléchargement identique pour chaque source, sauf si votre application a besoin de la étape de planification supplémentaire. Il duplique les demandes source. Si vous avez besoin d'un travail durable, stockez l'ID source et la politique de sortie; une URL médiatique signée des métadonnées n'est pas un remplacement durable de la source originale.

Python Option de référence

TâchePython optiondétails
Directory de sortie et filename"outtmpl": "downloads/%(id)s.%(ext)s"Gardez l’ID source et l’extension dynamique.
Le toit 1080p"format": "bv*[height<=1080]+ba/b[height<=1080]"Il permet des codecs source et échoue si aucun ne correspond au limit.
Méthodatifs sidecar"writeinfojson": TrueIl contient des metadata d'extraction complètes à côté des médias.
Point de contrôle complet"download_archive": "archive.txt"Un fichier par politique de sortie, pas un enregistrement de chèques.
Erreurs strictes"ignoreerrors": FalseLaissez le clergé enregistrer les échecs au lieu de traiter les problèmes post-processing comme un succès.
Le temps de runtime"js_runtimes": {"deno": {}}Installez Deno dans le processus et faites de son binaire visible sur PATH.
Impression de navigateur"impersonate": ImpersonateTarget()Python équivalent de --impersonate=""; importez la classe cible et installez curl-cffi.
fichier cookie existant"cookiefile": "private/youtube-cookies.txt"Utilisez les credentials de session privée uniquement lorsque cela est nécessaire pour l'accès.
MP3 Options de conversion
audio_options = {
    "format": "ba",
    "outtmpl": "audio/%(id)s.%(ext)s",
    "postprocessors": [{
        "key": "FFmpegExtractAudio",
        "preferredcodec": "mp3",
        "preferredquality": "192",
    }],
}
Passez audio_options à YoutubeDL. Le FFmpeg post-processeur convertit à une vitesse de bits cible de 192 kbps; il ne améliore pas la qualité originale de la source.

Vidéo + audio + captions pour un ensemble de données AI

Utilisez cette politique de sortie lorsque l'objectif est un ensemble de données de formation plutôt que la collection de l'exemple du processus 1080p. Il demande le bestvideo et le bestaudio, permet FFmpeg de les fusionner dans MP4, et sauvage les captions et les métadonnées anglaises disponibles à côté des médias.

Un élément de données en 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])
Il faut FFmpeg/ffprobe, Deno et l'installation nocturne [defaut,curl-cffi] Paramètre de format préféré du remucher est affiché de cette manière dans l'API de yt-dlp.

ImpersonateTarget() sélectionne n'importe quel cible de navigateur disponible, correspondant à --impersonate="". Passez l'objet, pas une ligne vide copiée de la syntaxe CLI. curl-cffi doit être installé dans cet environnement Python. Deno fonctionne toujours JavaScript solution; Impersonnalisation ne le remplace pas.

MP4 est le conteneur de sortie; la vidéo sélectionnée peut toujours être AV1 ou VP9. Si votre décoder de formation nécessite H.264/AAC, appliquez une politique explicite de codec avant de fusionner ou d'enregistrer un transcode FFmpeg distinct. Les sous-titres disponibles sont retirés, non générés par le discours.

Après que les médias finissentCe que le fichier de données a besoin
Voir la fin MP4 avec ffprobeVideo/audio codecs, durée, dimensions, chemin de fichier et nombre de bytes.
Vérifier les coffres de côté séparémentLangage, supplied/automatic trace, timestamps et si le fichier existe réellement.
Pas de captions disponiblesGardez les médias et marquez le texte manquant; envoyez l'audio à votre étape de transcription si nécessaire.
Les captions ont été frappées 429Retry caption retrieval après un IP cooldown avec sous-titre pacing; ne redécoutez pas les médias complets.

Pour un ensemble, utilisez un archive séparé pour cette politique de données et conservez un enregistrement pour les pages requises. Ne pas réutiliser un 1080p précédent ou un seul archive médiatique: il peut échapper aux vidéos avant que leurs captures nouvellement demandées ne soient collectées. Utilisez after_move pour la préparation des médias, puis validez le texte et les métadonnées avant de publier un élément de dataset complet.

Découvrez quand le fichier final est prêt

Un progrès au niveau de la déclaration de l'état = terminé signifie un transfert terminé. FFmpeg Il peut encore être nécessaire de fusionner vidéo et audio, de convertir un fichier audio ou de déplacer la sortie. Un seul flux vidéo atteignant 100% n'est pas l'événement de finition que votre application devrait publier.

ÉtapeCe que vous savezÉtat d'application
TéléchargementCertains bytes de médias sont arrivés.courir
Le transfert de la bouche : terminéCe transfert est terminé ; le traitement peut encore être suivi.Traitement
after_move Le processus de pointeLe fichier a passé le mouvement post-traitement et final configuré.Fiche locale prête
Télécharger et vérifier l'intégritéVotre destination a l'objet et la vérification enregistrée.livré

L'exemple complet ci-dessous enregistre un PostProcessor personnalisé à after_move et lit info["filepath"] là. Il vérifie que le fichier existe et est non-pourrissé. Cela évite de deviner l'extension finale avec prepare_filename(), qui peut se référer à un nom de pré-conversion.

Scénario complet : Un processus vidéo

Réservez ceci comme download_video.py. Il accepte un ID vidéo ou watch/Shorts/live/embed URL et rejette l'entrée playlist/channel. Chaque invocation utilise une seule instance YoutubeDL, des retraites de téléchargement limitées et un archive collectif-local. Un retour de source répétée complète a été échappé au lieu de prétendre qu'un nouveau fichier a été créé.

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))
Le script complet est également disponible à partir du lien de téléchargement ci-dessus. Il n'a que la sortie locale; ajoutez des vérifications de décodage et les enregistrements de téléchargement dans la prochaine étape de votre application.
Faire un travail
python download_video.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --output downloads

Le record complet contient l'URL de source canonique, l'ID vidéo, la voie finale et la taille du byte. Un fichier échappé signifie qu'aucun nouveau fichier final n'a été récupéré; reconcilier contre l'archive et l'inventaire existant si vous avez besoin de preuve que le fichier est toujours présent. L’archive seule ne vérifie pas si un utilisateur a plus tard supprimé ou déplacé les médias.

Catch DownloadError pour les erreurs extractor/download/post-processing, ValueError pour les entrées rejetées et OSError pour les erreurs du système de fichiers local. Traitez ces classes comme des classes distinctes dans vos logs d'application. Les messages d'erreur sont des diagnostics utiles, mais leur texte n'est pas une taxonomie stable et structurée de chaque échec YouTube.

Scénario complet : le processus de batch récurrente

Et puis, il y a download_batch.py à côté de download_video.py. Créez un UTF-8 urls.txt avec un URL vidéo ou un ID par ligne. Cela fonctionne intentionnellement séquentiellement, donc un processus possède l'archive et le catalogue de sortie. Il écrit un résultat complet, échoué ou échoué pour chaque entrée et sortie tentée nonzero quand un élément échoue.

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-on-on attempts.jsonl maintient les retours comme des tentatives séparées.Lines dupliquées dans un manifeste sont supprimées; l'archive de téléchargement gère les identifiants complets à travers les courses.
Rendez ou récupérez le même jeu
python download_batch.py urls.txt --output collection

Flush après chaque record afin qu'une interruption ne laisse pas tous les résultats buffert jusqu'à la fin. Il y a toujours une petite fenêtre entre la bibliothèque enregistrant son archive et votre application enregistrant un enregistrement d'essai. Si un accident se trouve là, la prochaine course peut signaler échappé. Pour un service, réconcilier filesystem/archive avec une base de données de travail durable au lieu de affirmer que cet exemple de fichier texte est transactionnel.

Gardez attempts.jsonl privé: les erreurs peuvent inclure les détails de source et de demande. rappeler les totalités par état, vérifier les éléments échoués, et reproduire le même manifeste après résoudre un problème environnemental partagé. Ne pas ajouter chaque identifiant échoué à l'archive de succès.

Production : coude, délais et stockage

Youtube est synchronique. En le fonctionnant directement à l'intérieur d'un bloc de web-processus async que le loop d'événements du trader; même un décharge de fil ne fait pas une demande de navigateur une durée de vie appropriée pour un grand téléchargement. Accepter le travail, persister son source/options, et laisser un processus produire un résultat final.

  • Créez un ID de travail durable avant l'exécution.Enregistrer le ID de vidéo canonique, la politique de sortie, le numéro d'essai et la destination.
  • Utilisez des directories de travail par emploi et un bassin de processus limité. Ne partagez pas un exemple YoutubeDL sur les emplois concurrents.
  • Utilisez un processus séparé lorsque vous avez besoin d'un délai de délai ou d'annulation de mur dur ; socket_timeout limite les opérations réseau individuelles, pas l'ensemble du travail.
  • Si vous exposez les entrées utilisateur au-dessus de HTTP, acceptez les identifiants vidéo YouTube soutenus plutôt que les URL arbitraires, les chemins de sortie, les arguments extraitors ou les snippets de shell.
  • Enregistrez la préparation de fichier local et la finition du téléchargement en nuage séparément; gardez suffisamment d'état pour retire un téléchargement sans le télécharger à nouveau.
  • Gardez FFmpeg, le temps de fonctionnement, yt-dlp et les versions de plugins avec votre déploiement. Exercer une petite charge de travail connue avant de remplacer une image du processus.

Un simple bassin de processus est un meilleur point de départ que les appels non limitées asyncio.gather autour de nombreux téléchargements. Coordinez le travail total partout dans les processus; les paramètres de sommeil de chaque téléchargateur ne régulent pas l'ensemble du service. Gardez un budget de retrait séparé pour les tentatives de travail afin que les retraites d'application ne multiplient pas le compte de retrait du téléchargateur.

Détecter le processus Python

ProblèmeVérification
Les travaux dans le CLI, échouent dans PythonComparez les options réelles. YoutubeDL ne charge pas automatiquement votre fichier de configuration CLI.
Le progrès dit fini, le fichier manquaitUtilisez le after_move et vérifiez les erreurs post-traitement.
Les sources répétées revientLire l’archive de la collection ; utiliser un autre archive lors de la modification des politiques de sortie.
Le processus s'enfonce plus longtemps que socket_timeoutUn travail peut effectuer plusieurs operations/retries. Ajouter un délai de niveau de processus si nécessaire.
403 ou les bots vérifier sur le serveurMise à jour de nuit, vérifier Deno, réduire la concurrence et tester une IP de sortie de remplacement lorsque la route reste rejetée.
429 dans les méta-détails / transcriptionsPause les IP affectés, les demandes de rythme extraction/subtitle et ajoute des retards entre les méta-data-uniquement les emplois.

Lorsque la production appartient à un pipeline cloud

Si vous voulez posséder le téléchargateur, les flux de travail ci-dessus vous donnent le contrôle sur les fichiers, les formats et le traitement. Si votre application a besoin de médias complets livrés à l'enregistrement, FlashData fournit des emplois de téléchargement YouTube traqués, le traitement des bot, la route proxy et les retours. Votre application soumet les paramètres source et sortie, puis maintient l'ID de travail et le registre de livraison.