Explorar documentación
Guías
Ejemplos ejecutables de Python para descargas, metadatos, conjuntos de datos de IA y procesos que se pueden reanudar.
En esta página
Instalar la biblioteca de Python
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"Installa también Deno, FFmpeg y ffprobe. Estos ejemplos se ejecutan localmente en Linux, macOS o Windows y no necesitan la clave API.
Descarga tu primer 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"])Las configuraciones de CLI no son heredadas. Configura Deno, impersonización y pacing en las opciones de Python, incluso cuando su comando terminal ya los utiliza.
download() toma una lista de URLs y devolve un código de estado. extract_info(url, download=True) devolve información de extracción así como el desempeño de la descarga. Utilice un gerente de contexto para cerrar la instancia limpio, y crear una nueva instancia para un trabajo independiente en lugar de compartir estado mutable a través de las filas.
Leer metadatos sin medios
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))
Los campos extraídos pueden ser ausentes o nulos. Utilice get() para metadatos opcionales, y no supone que cada fuente tiene una duración, ID de canal o lista completa de formatos. Una lista de playlist plana también es diferente de un vídeo totalmente resolto. Para una respuesta pública, proyectar sólo los campos que pretende exponer.
Evite una extracción de metadatos inmediatamente seguida por una extracción de descarga idéntica para cada fuente, a menos que su aplicación necesite el paso adicional de planificación. duplican las solicitudes de fuente. Si necesita un trabajo duradero, almacenar la ID de fuente y la política de salida; una URL de medios firmada de los metadatos no es un sustituto duradero para la fuente original.
Python Opción de referencia
| Tareas | Opción Python | Detalle |
|---|---|---|
| Directorios de salida y filename | "outtmpl": "downloads/%(id)s.%(ext)s" | Mantenga el ID de fuente y la extensión dinámica. |
| Cuerpo de la Cuerpo 1080p | "format": "bv*[height<=1080]+ba/b[height<=1080]" | Permite codecos de fuente y fallan si no se ajusta al límite. |
| Metadatos de Sede | "writeinfojson": True | Se encuentra en el centro de los metadatos de extracción completa junto a los medios. |
| Punto de verificación de ID | "download_archive": "archive.txt" | Un archivo por política de salida; no un inventario de checksum. |
| Errores estrictos | "ignoreerrors": False | Deja que el llamador grabe fallos en lugar de tratar problemas post-procesamiento como éxito. |
| El tiempo de runtime | "js_runtimes": {"deno": {}} | Instalar Deno en el trabajador y hacer que su binario sea visible en PATH. |
| Impersonación de navegador | "impersonate": ImpersonateTarget() | Python equivalente de --impersonate=""; importar la clase objetivo y instalar curl-cffi. |
| Archivo de cookies existente | "cookiefile": "private/youtube-cookies.txt" | Utilice los credenciales de sesión privada sólo cuando sea necesario para acceder. |
audio_options = {
"format": "ba",
"outtmpl": "audio/%(id)s.%(ext)s",
"postprocessors": [{
"key": "FFmpegExtractAudio",
"preferredcodec": "mp3",
"preferredquality": "192",
}],
}Video + audio + capciones para un conjunto de datos de AI
Utilice esta política de salida cuando el objetivo es un conjunto de datos de formación en lugar de la colección de ejemplo del trabajador 1080p. requiere bestvideo y bestaudio, permite que FFmpeg los fusionen en MP4, y salva capciones y metadatos disponibles en inglés junto a los medios.
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() selecciona cualquier objetivo del navegador disponible, que se ajusta a --impersonate="". Pasar el objeto, no una cinta vacía copiada de la síntaxe CLI. curl-cffi debe ser instalado en este entorno de Python. Deno todavía realiza JavaScript solving; la impersonización no lo sustituye.
MP4 es el contenedor de salida; el vídeo seleccionado puede seguir siendo AV1 o VP9. Si su decoder de entrenamiento requiere H.264/AAC, aplique una política de codec explícita antes de fusionar o grabar un transcódigo separado FFmpeg. Los subtítulos disponibles se reciben, no generados por el discurso.
| Cuando los medios terminan | Lo que el registro de datos necesita |
|---|---|
| Ver el final MP4 con ffprobe | Video/audio codecs, duración, dimensiones, ruta de archivo y cuenta de bytes. |
| Control de las carcajas separadamente | Idioma, supplied/automatic pista, timestamps y si el archivo realmente existe. |
| No hay capciones de ajuste disponibles | Mantenga los medios y señale el texto desaparecido; envíe audio a su etapa de transcripción si es necesario. |
| El éxito de las capciones 429 | Retry caption retrieval después de un IP con un subtitulo pacing; no redescubre los medios completados. |
Para un conjunto, use un archivo separado para esta política de conjunto de datos y almacene un inventario para las páginas requeridas. No reutilizes un archivo anterior 1080p o media-solo: puede deshacerse de los videos antes de que se recogen sus capciones recientemente requeridas. Utilice after_move para la preparación de los medios, luego valida el texto y los metadatos antes de publicar un artículo completo de conjunto de datos.
Saber cuándo está listo el archivo final
Un progreso de la información de estado = finito significa que se ha terminado un traslado. FFmpeg puede que todavía necesite fusionar vídeo y audio, convertir un archivo de audio, o mover la salida. Un solo video- stream alcanzar 100% no es el evento de finalización que su aplicación debe publicar.
| Etapa | Lo que sabes | Estado de aplicación |
|---|---|---|
| Descargar | Algunos bajetas de medios están llegando. | Correr |
| Cortesía de la Cuerpo: Finalizado | Esta transferencia ha terminado; el procesamiento todavía puede seguir. | Procesamiento |
| after_move Procesador de la | El archivo ha pasado el paso de post-procesamiento configurado y final. | El archivo local está listo |
| Testimonios y verificación de integridad | Su destino tiene el objeto y verificación registrada. | entregados |
El ejemplo completo a continuación registra un PostProcessor personalizado en after_move y lee info["filepath"] allí. Verifica que el archivo existe y no está vacío. Esto evita la suposición de la extensión final con prepare_filename(), que puede referirse a un nombre de preconversión.
Scriptura completa: trabajador de vídeo único
Salve esto como download_video.py. Se acepta un ID de vídeo o watch/Shorts/live/embed URL y rechaza la entrada playlist/channel. Cada invitación utiliza una instancia de YoutubeDL, retrasas limitadas de descargadores y un archivo colectivo-local. Un reiterado devolución de fuente completada se desplaza en lugar de pretender que se creó un nuevo archivo.
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 downloadsEl registro completado contiene la URL de fuente canónica, ID de vídeo, ruta final y tamaño de byte. Un registro despedido significa que no hay nuevo archivo final de la llamada; reconciliarlo contra el archivo y el inventario existente si necesita la prueba del archivo está todavía presente. El archivo solo no verifica si un usuario más tarde eliminó o movió los medios.
Catch DownloadError for extractor/download/post-processing errores, ValueError for rejected input y OSError for local file system errores. Tratar estos como clases distintas en sus logs de solicitud. Los mensajes de error son diagnósticos útiles, pero su texto no es una taxonomía estructurada estable de cada fracaso de YouTube.
Scriptura completa: trabajador de batch recuentable
Y dejó download_batch.py junto a download_video.py. Crea un UTF-8 urls.txt con una URL de vídeo o ID por línea. Esto se realiza intencionalmente secuencialmente, por lo que un proceso es propiedad del archivo y de la directoría de salida. Escribe un resultado completado, escapado o fallado para cada intento de entrada y salida no cero cuando cualquier elemento fracasó.
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 después de cada registro para que una interrupción no deja todos los resultados bufferados hasta el final. Hay todavía una pequeña ventana entre la biblioteca que graba su archivo y su aplicación que escribe un registro de intento. Si un accidente se encuentra allí, la próxima ronda puede reportar despido. Para un servicio, reconciliar el filesystem/archive con una base de datos de trabajo duradera en lugar de pretender que este ejemplo de archivo de texto es transaccional.
Mantenga attempts.jsonl privado: los errores pueden incluir los detalles de fuente y solicitud. Reporta los volúmenes por estado, inspecta los elementos fallados y reproduce el mismo manifiesto después de resolver un problema de entorno compartido. No añade cada ID fallido al archivo de éxito.
Producción: cueva, plazos y almacenamiento
YoutubeDl es sincrónico. Ejecutarlo directamente dentro de un bloque de tráfico web asíntico que el círculo de eventos del tráfico; incluso un descargo de thread no hace que una solicitud de navegador sea una vida adecuada para un gran descargamiento. Aceptar el trabajo, persistir su source/options y dejar que un trabajador produzca un resultado final.
- Crea un ID de trabajo duradero antes de ejecutar. almacenar el ID de vídeo canónico, la política de salida, el número de intento y el destino.
- Utilice directorios de trabajo por trabajo y una piscina de trabajadores limitada. No comparte un ejemplo de YoutubeDL entre los trabajos concurrentes.
- Utilice un proceso separado cuando necesitas un plazo de tiempo duro o cancelación; socket_timeout limita las operaciones de red individuales, no todo el trabajo.
- Si expone la entrada del usuario sobre HTTP, acepta los identificadores de vídeo de YouTube apoyados en lugar de URL arbitrarios, caminos de salida, argumentos de extractor o snippets de shell.
- Recordar la preparación de archivo local y la completación de la cargada en la nube por separado; mantener lo suficiente para retomar una cargada sin descargar de nuevo.
- Mantenga FFmpeg, tiempo de trabajo, yt-dlp y versiones de plugin con su implementación. Ejercique una pequeña carga de trabajo conocida antes de reemplazar una imagen de trabajador.
Una simple piscina de trabajadores es un mejor punto de partida que las llamadas de asyncio.gather sin límites alrededor de muchas descargas. Coordinar el trabajo total a través de los procesos; las configuraciones de sueño de cada descargador no regulan el servicio entero. Mantenga un presupuesto de retiro separado para los intentos de trabajo para que las retrasas de solicitud no multipliquen el número de retrasos del descargador.
Desarrollo del trabajo de Python
| Problema | Verifica |
|---|---|
| Trabajos en el CLI, fallos en Python | Comparar las opciones reales. YoutubeDL no carga automáticamente su archivo de configuración CLI. |
| El progreso dice terminado, el archivo desaparece | Utilice el límite after_move y inspeccione los errores de post-procesamiento. |
| Repetido de la fuente de retorno descuidado | Leer el archivo de la colección; utilizar un archivo diferente al cambiar las políticas de salida. |
| El trabajador se agota más que socket_timeout | Un trabajo puede realizar muchos operations/retries. Añadir un plazo de nivel de proceso si es necesario. |
| 403 o bot verifica en el servidor | Actualizar por la noche, ver Deno, reducir la concurrencia y probar una salida IP de reemplazo cuando el itinerario permanece rechazado. |
| 429 en trabajos de metadatos / transcriptos | Pausa la IP afectada, pita las peticiones de ritmo extraction/subtitle y añade retrasos entre los metadatos-sólo trabajos. |
Cuando la producción pertenece a un tubo de nube
Si quieres poseer el descargador, los flujos de trabajo anteriormente te dan control sobre los archivos, formatos y procesamiento. Si su aplicación necesita medios completos entregados al almacenamiento, FlashData proporciona trabajos de descarga de YouTube rastreados, manejo de botes, rotación de proxy y retrasos. Su aplicación envía las configuraciones de fuente y salida, luego mantiene el ID de trabajo y el registro de entrega.