Saltar al contenido
ES
Obtener clave API
Explorar documentación

Guías

API de Python para yt-dlp

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

En su Python 3.11+ ambiente
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

Descargar 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"])
Esto escribe los medios locales hasta 1080p y puede fusionar corrientes separadas. el contenedor de salida depende de los formatos de fuente seleccionados.

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

Exporta un pequeño registro de metadatos
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 todavía realiza solicitudes de red. sanitize_info hace que el resultado JSON-compatible; no redactan secretos ni reduce el resultado a estos campos.

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

TareasOpción PythonDetalle
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": TrueSe 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": FalseDeja 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.
MP3 Opciones de conversión
audio_options = {
    "format": "ba",
    "outtmpl": "audio/%(id)s.%(ext)s",
    "postprocessors": [{
        "key": "FFmpegExtractAudio",
        "preferredcodec": "mp3",
        "preferredquality": "192",
    }],
}
Pasar audio_options a YoutubeDL. El FFmpeg post-procesador se convierte a una velocidad de bit meta de 192 kbps; no mejora la calidad original de la fuente.

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.

Un elemento de conjunto de datos 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])
Requiere FFmpeg/ffprobe, Deno y la instalación nocturna [default,curl-cffi] El parámetro de formato preferido del remuxer se muestra de esa manera en la API de yt-dlp.

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 terminanLo que el registro de datos necesita
Ver el final MP4 con ffprobeVideo/audio codecs, duración, dimensiones, ruta de archivo y cuenta de bytes.
Control de las carcajas separadamenteIdioma, supplied/automatic pista, timestamps y si el archivo realmente existe.
No hay capciones de ajuste disponiblesMantenga 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 429Retry 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.

EtapaLo que sabesEstado de aplicación
DescargarAlgunos bajetas de medios están llegando.Correr
Cortesía de la Cuerpo: FinalizadoEsta transferencia ha terminado; el procesamiento todavía puede seguir.Procesamiento
after_move Procesador de laEl archivo ha pasado el paso de post-procesamiento configurado y final.El archivo local está listo
Testimonios y verificación de integridadSu 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.

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))
El script completo también está disponible desde el enlace de descarga arriba. sólo posee salida local; añade cheques de decodificación y cargue registros en la siguiente etapa de su aplicación.
Ejecutar un trabajo
python download_video.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --output downloads

El 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ó.

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)
El apéndice attempts.jsonl mantiene retrasas como intentos separados.Las líneas duplicadas dentro de un manifiesto se eliminan; el archivo de descarga maneja los ID completados a lo largo de las rutas.
RUER o reanudar el mismo batch
python download_batch.py urls.txt --output collection

Flush 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

ProblemaVerifica
Trabajos en el CLI, fallos en PythonComparar las opciones reales. YoutubeDL no carga automáticamente su archivo de configuración CLI.
El progreso dice terminado, el archivo desapareceUtilice el límite after_move y inspeccione los errores de post-procesamiento.
Repetido de la fuente de retorno descuidadoLeer 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_timeoutUn trabajo puede realizar muchos operations/retries. Añadir un plazo de nivel de proceso si es necesario.
403 o bot verifica en el servidorActualizar 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 / transcriptosPausa 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.