Parcourir la documentation
Guides
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
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
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"])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
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))
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âche | Python option | dé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": True | Il 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": False | Laissez 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. |
audio_options = {
"format": "ba",
"outtmpl": "audio/%(id)s.%(ext)s",
"postprocessors": [{
"key": "FFmpegExtractAudio",
"preferredcodec": "mp3",
"preferredquality": "192",
}],
}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.
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() 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 finissent | Ce que le fichier de données a besoin |
|---|---|
| Voir la fin MP4 avec ffprobe | Video/audio codecs, durée, dimensions, chemin de fichier et nombre de bytes. |
| Vérifier les coffres de côté séparément | Langage, supplied/automatic trace, timestamps et si le fichier existe réellement. |
| Pas de captions disponibles | Gardez les médias et marquez le texte manquant; envoyez l'audio à votre étape de transcription si nécessaire. |
| Les captions ont été frappées 429 | Retry 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.
| Étape | Ce que vous savez | État d'application |
|---|---|---|
| Téléchargement | Certains 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 pointe | Le 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éé.
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 downloadsLe 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.
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 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ème | Vérification |
|---|---|
| Les travaux dans le CLI, échouent dans Python | Comparez les options réelles. YoutubeDL ne charge pas automatiquement votre fichier de configuration CLI. |
| Le progrès dit fini, le fichier manquait | Utilisez le after_move et vérifiez les erreurs post-traitement. |
| Les sources répétées revient | Lire 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_timeout | Un 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 serveur | Mise à 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 / transcriptions | Pause 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.