YouTube Downloader
Descripción general
Permite descargas confiables de video y audio desde YouTube y plataformas de transmisión HLS (Mux, Vimeo, etc.) usando yt-dlp y ffmpeg. Esta habilidad proporciona flujos de trabajo para:
- Descargas de YouTube (hasta 4K) usando proveedores de tokens PO o cookies del navegador
- Descargas de transmisiones HLS con encabezados de autenticación
- Manejo de contenido protegido y solución de problemas comunes de descarga
Experiencia de usuario no técnico (predeterminado)
Asume que el usuario no es técnico. No le pidas que ejecute comandos. Ejecuta todo tú mismo e informa el progreso en lenguaje sencillo. Evita mencionar herramientas a menos que el usuario lo pregunte.
Flujo predeterminado:
- Pide la URL (si no se proporcionó).
- Obtén los metadatos del video (título/subidor/duración/miniatura) y confirma que coinciden con la intención del usuario.
- Si yt-dlp está bloqueado por "confirma que no eres un bot", recurre a YouTube oEmbed para título/subidor/miniatura (la duración puede ser desconocida).
- Ofrece opciones simples (video solo o solo audio, calidad, subtítulos, ubicación de guardado).
- Continúa con valores predeterminados sensatos si el usuario no especifica:
- Descarga de video en la mejor calidad
- Salida MP4 combinada
- Video individual solamente (sin listas de reproducción)
- Descarga e informa la ruta final del archivo, el tamaño del archivo y la resolución (si es video).
Ofrece opciones en términos amigables para el usuario:
- "Descargar el video en la mejor calidad (predeterminado)"
- "Descargar solo el audio (MP3)"
- "Elegir una calidad: 1080p / 720p / 480p / 360p"
- "Incluir subtítulos (si están disponibles)"
- "Guardar en la carpeta de Descargas (predeterminado) o dime otra carpeta"
Siempre muestra la miniatura cuando esté disponible:
- Si los metadatos incluyen una URL de miniatura, inclúyela usando la sintaxis de imagen Markdown:
.
Pregunta antes de hacer trabajo adicional:
- Confirma las descargas de listas de reproducción (pueden ser grandes).
- Confirma la instalación/actualización de dependencias si faltan.
- Pregunta antes de extraer cookies del navegador.
- Si se usan cookies, nunca menciones el recuento de cookies ni los detalles de cookies sin procesar en las respuestas al usuario. Di "usé tu sesión de inicio de sesión de Chrome".
- Si se requiere verificación, configura automáticamente un ayudante de token PO local (sin acciones del usuario). Si Docker falta o falla, no intentes instalar Docker; cambia al proveedor de token PO basado en navegador.
Recordatorio legal/seguridad (breve):
- Continúa solo si el usuario tiene los derechos o permiso para descargar el contenido.
Plantilla de respuesta (usa lenguaje sencillo, sin comandos):

Título: …
Canal: …
Duración: …
Puedo ayudarte a:
1) Descargar el video (mejor calidad, MP4)
2) Descargar solo el audio (MP3)
3) Elegir una calidad específica (1080p/720p/480p/360p)
4) Incluir subtítulos (si están disponibles)
¿Dónde debería guardarlo? (Predeterminado: carpeta de Descargas)
Si el usuario dice "solo descarga":
- Continúa con los valores predeterminados y confirma cuando finalice la descarga.
- Si está bloqueado por un 403, configura automáticamente el ayudante de verificación y reintenta.
SOP de descarga confiable (Interno)
Sigue este SOP para evitar errores y confusiones comunes:
- Pon entre comillas las URL en los comandos de shell (zsh trata
?como un comodín). Ejemplo:'https://www.youtube.com/watch?v=VIDEO_ID'. - Asegúrate de que el proxy esté activo tanto para yt-dlp como para los proveedores de tokens PO (HTTP_PROXY/HTTPS_PROXY/ALL_PROXY).
- Si ves "Inicia sesión para confirmar que no eres un bot", solicita permiso y usa cookies del navegador. No continúes sin cookies.
- Inicia un proveedor de token PO antes de descargar (falla rápido si no puede iniciarse).
- Usa el proveedor Docker bgutil cuando esté disponible.
- Si Docker falta o falla, cambia al proveedor WPC basado en navegador.
- Si se usan cookies, prefiere el cliente
web_safari. De lo contrario, prefieremwebpara tokens PO. - Mantén la ventana del navegador abierta mientras WPC genera tokens. Asegúrate de que Chrome pueda llegar a YouTube a través del mismo proxy.
- Si obtienes "Solo imágenes disponibles" o "El formato solicitado no está disponible", trátalo como un fallo de token PO y reintenta después de corregir el estado del proveedor/navegador.
- Si obtienes errores SSL EOF o de fragmentos, trátalos como un problema de proxy/red. Reintenta con formatos progresivos y/o un mejor proxy.
Lista de verificación de ejecución del agente (Interno)
- Ejecuta
scripts/download_video.py URL --info(agrega--cookies-from-browser chromesi se concede permiso) para obtener metadatos y miniatura. - Si los metadatos de yt-dlp fallan, confía en la alternativa oEmbed del script para título/subidor/miniatura y ten en cuenta que la duración puede no estar disponible.
- Si hay una URL de miniatura, muéstrala en la respuesta con sintaxis de imagen Markdown.
- Pide al usuario que elija entre video y solo audio y (opcionalmente) un preajuste de calidad.
- Usa una ubicación de guardado predeterminada amigable (carpeta de Descargas) a menos que el usuario especifique una carpeta.
- Para subtítulos, ejecuta con
--subtitlesy el--sub-langsolicitado. - Después de la descarga, informa el nombre del archivo, el tamaño y la resolución (si es video) en lenguaje sencillo.
- Si la descarga falla con errores 403/de fragmentos, reintenta una vez con formatos progresivos no m3u8.
- Si aparece "Inicia sesión para confirmar que no eres un bot", solicita acceso a las cookies y reintenta con cookies +
web_safari. - Si aparece "Solo imágenes disponibles", trátalo como un fallo de token PO y reintenta después de corregir el estado del proveedor/navegador.
- Inicia el proveedor de token PO antes de las descargas (
--auto-po-tokenpredeterminado). Falla rápido si no puede iniciarse. - Si el proveedor basado en Docker falla (común en China), recurre automáticamente al proveedor WPC basado en navegador (puede abrir brevemente una ventana del navegador).
- Si se usa el proveedor WPC, mantén la ventana del navegador abierta hasta que comience la descarga. Si el navegador no se inicia, establece la ruta de Chrome explícitamente.
- Si el proveedor de token PO se agota, reinícialo una vez y reintenta.
- Si hay un proxy de sistema configurado, pásalo al contenedor del proveedor. Si el proxy apunta a 127.0.0.1/localhost, reescríbelo a
host.docker.internalpara Docker.
Cuándo usar esta habilidad
Esta habilidad debe invocarse cuando los usuarios:
- Soliciten descargar videos o listas de reproducción de YouTube
- Quieran extraer audio de videos de YouTube
- Experimenten fallos de descarga de yt-dlp o disponibilidad limitada de formatos
- Necesiten ayuda con la selección de formato o opciones de calidad
- Reporten que solo hay formatos de baja calidad (360p) disponibles
- Pregunten sobre cómo descargar contenido de YouTube en una calidad específica (1080p, 4K, etc.)
- Necesiten convertir videos WebM descargados a formato MP4 para una mayor compatibilidad
- Soliciten descargar transmisiones HLS (m3u8) de plataformas como Mux, Vimeo u otros servicios de transmisión
- Necesiten descargar transmisiones protegidas que requieran encabezados de autenticación
Prerrequisitos
1. Verificar la instalación de yt-dlp (Ejecuta esto tú mismo)
which yt-dlp
yt-dlp --version
Si no está instalado o está desactualizado (< 2025.10.22):
brew upgrade yt-dlp # macOS
# o
pip install --upgrade yt-dlp # Multiplataforma
Crítico: Las versiones desactualizadas de yt-dlp causan fallos de extracción nsig y formatos faltantes.
2. Verificar el acceso de calidad actual (Ejecuta esto tú mismo)
Antes de descargar, verifica los formatos disponibles:
yt-dlp -F "https://youtu.be/VIDEO_ID"
Si solo aparece el formato 18 (360p): Se necesita la configuración del proveedor de token PO para acceso de alta calidad.
Flujo de trabajo de descarga de alta calidad
Paso 1: Instalar el proveedor de token PO (Configuración única)
Para acceso a 1080p/1440p/4K, instala un complemento de proveedor de token PO en el entorno Python de yt-dlp:
# Encuentra la ruta de Python de yt-dlp (intérprete utilizado por yt-dlp)
head -1 $(which yt-dlp)
# Instala el complemento usando el intérprete de la línea anterior
<YTDLP_PYTHON> -m pip install bgutil-ytdlp-pot-provider
Verificación: Ejecuta yt-dlp -F "URL_VIDEO" nuevamente. Busca los formatos 137 (1080p), 271 (1440p) o 313 (4K).
Consulta references/po-token-setup.md para obtener instrucciones detalladas de configuración y solución de problemas.
Paso 2: Descargar con la mejor calidad
Una vez instalado el proveedor de token PO:
# Descargar la mejor calidad hasta 1080p
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "URL_VIDEO"
# Descargar la mejor calidad disponible (4K si está disponible)
yt-dlp -f "bestvideo+bestaudio/best" "URL_VIDEO"
Paso 3: Verificar la calidad de la descarga
# Verificar la resolución del video
ffprobe -v error -select_streams v:0 -show_entries stream=width,height,codec_name -of default=noprint_wrappers=1 video.mp4
Salida esperada para 1080p:
codec_name=vp9
width=1920
height=1080
Alternativa: Método de cookies del navegador
Si la configuración del proveedor de token PO es problemática, usa cookies del navegador:
# Firefox
yt-dlp --cookies-from-browser firefox -f "bestvideo[height<=1080]+bestaudio/best" "URL_VIDEO"
# Chrome
yt-dlp --cookies-from-browser chrome -f "bestvideo[height<=1080]+bestaudio/best" "URL_VIDEO"
Beneficios: Acceso a contenido restringido por edad y solo para miembros. Requisitos:
- Debes haber iniciado sesión en YouTube en el navegador especificado.
- El navegador y yt-dlp deben usar la misma IP/proxy.
- No uses el cliente Android con cookies (el cliente Android no admite cookies).
Tareas comunes
Descarga solo de audio (Ejecuta esto tú mismo)
Extraer audio como MP3:
yt-dlp -x --audio-format mp3 "URL_VIDEO"
Directorio de salida personalizado (Ejecuta esto tú mismo)
yt-dlp -P ~/Downloads/YouTube "URL_VIDEO"
Descarga con subtítulos (Ejecuta esto tú mismo)
yt-dlp --write-subs --sub-lang en "URL_VIDEO"
Descarga de lista de reproducción (Ejecuta esto tú mismo)
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "URL_PLAYLIST"
Convertir WebM a MP4 (Ejecuta esto tú mismo)
Las descargas de alta calidad de YouTube a menudo usan formato WebM (códec VP9). Conviértelo a MP4 para una mayor compatibilidad:
# Verificar si ffmpeg está instalado
which ffmpeg || brew install ffmpeg # macOS
# Convertir WebM a MP4 con buena configuración de calidad
ffmpeg -i "video.webm" -c:v libx264 -preset medium -crf 23 -c:a aac -b:a 128k "video.mp4"
Parámetros explicados:
-c:v libx264: Usa el códec de video H.264 (ampliamente compatible)-preset medium: Equilibrio entre velocidad de codificación y tamaño de archivo-crf 23: Factor de tasa constante para calidad (rango 18-28, menor = mejor calidad)-c:a aac: Usa el códec de audio AAC-b:a 128k: Tasa de bits de audio 128 kbps
Consejo: La conversión mantiene la resolución 1080p y proporciona una velocidad de codificación ~6 veces mayor en hardware moderno.
Referencia rápida de solución de problemas
Solo disponible 360p (Formato 18)
Causa: Falta el proveedor de token PO o yt-dlp desactualizado.
Solución:
- Actualiza yt-dlp:
brew upgrade yt-dlp - Instala el proveedor de token PO (ver Paso 1 arriba)
- O usa el método de cookies del navegador
Inicia sesión para confirmar que no eres un bot
Causa: YouTube requiere autenticación para continuar.
Solución:
- Solicita permiso y usa cookies del navegador (
--cookies-from-browser chrome). - Asegúrate de que el navegador y yt-dlp usen la misma IP/proxy.
- Reintenta con el cliente
web_safarisi es necesario.
Solo imágenes disponibles / El formato solicitado no está disponible
Causa: Los tokens PO no se aplicaron o falló la verificación del proveedor/navegador.
Solución:
- Verifica que el proveedor de token PO se esté ejecutando antes de la descarga.
- Mantén la ventana del navegador abierta si se usa WPC.
- Si se usan cookies, prefiere el cliente
web_safariy reintenta.
Fallo de extracción nsig
Síntomas:
ADVERTENCIA: [youtube] falló la extracción nsig: algunos formatos pueden faltar
Solución:
- Actualiza yt-dlp a la última versión
- Instala el proveedor de token PO
- Si aún falla y los tokens PO están deshabilitados, usa el cliente Android:
yt-dlp --extractor-args "youtube:player_client=android" "URL_VIDEO"
Errores SSL EOF / de fragmentos
Causa: Inestabilidad del proxy o la red.
Solución:
- Reintenta con formatos progresivos (no m3u8).
- Cambia a un proxy/nodo más estable.
- Evita cerrar la ventana del navegador de token PO durante la descarga.
Descargas lentas o errores de red
Para usuarios en China o detrás de proxies restrictivos:
- Las descargas pueden ser lentas debido a las condiciones de la red
- Permite suficiente tiempo para completar
- yt-dlp reintenta automáticamente en fallos transitorios
Advertencia de token PO (Inofensiva)
ADVERTENCIA: los formatos https del cliente Android requieren un token PO GVS
Acción: Ignórala si la descarga se realiza correctamente. Esto indica que el cliente Android tiene acceso limitado a formatos sin tokens PO.
Referencia de script incluido
scripts/download_video.py
Usa este envoltorio conveniente para iniciar automáticamente un proveedor de token PO de forma predeterminada para descargas de alta calidad. Úsalo tú mismo e informa los resultados al usuario sin pedirle que ejecute comandos.
Uso básico:
scripts/download_video.py "URL_VIDEO"
Argumentos:
url- URL del video de YouTube (obligatorio)-o, --output-dir- Directorio de salida--output-template- Plantilla de nombre de archivo de salida (sintaxis de yt-dlp)-f, --format- Especificación de formato-q, --quality- Preajuste de calidad (best, 1080p, 720p, 480p, 360p, worst). Predeterminado: best (omitido para--audio-only)-a, --audio-only- Extraer audio como MP3--subtitles- Descargar subtítulos si están disponibles--sub-lang- Idiomas de subtítulos (separados por comas, predeterminado: en)--cookies-from-browser- Cargar cookies desde un navegador (ej., chrome, firefox)--cookies-file- Cargar cookies desde un archivo cookies.txt--player-client- Usar un cliente de reproductor de YouTube específico (ej., web_safari)--auto-po-token- Iniciar automáticamente el proveedor de token PO (predeterminado; usa Docker si está disponible, de lo contrario cambia al proveedor basado en navegador)--no-auto-po-token- Deshabilitar la configuración automática de token PO--proxy- URL del proxy para yt-dlp y el proveedor de token PO (ej., http://127.0.0.1:1082)--wpc-browser-path- Ruta del ejecutable del navegador para el proveedor WPC-F, --list-formats- Listar formatos disponibles--merge-format- Contenedor de salida combinado (ej., mp4, mkv). Predeterminado: mp4--playlist- Permitir descargas de listas de reproducción (predeterminado: solo video individual)--info- Imprimir título/subidor/duración/miniatura y salir--no-android-client- Deshabilitar la alternativa del cliente Android
Nota: Usa el cliente Android solo cuando los tokens PO estén deshabilitados. Mantén los tokens PO habilitados para alta calidad.
Expectativas de calidad
| Configuración | 360p | 720p | 1080p | 1440p | 4K |
|---|---|---|---|---|---|
| Token PO automático (predeterminado) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Solo cliente Android | ✓ | ✗ | ✗ | ✗ | ✗ |
| Proveedor de token PO (manual) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Cookies del navegador | ✓ | ✓ | ✓ | ✓ | ✓ |