Descargador de YouTube
Resumen
Permite descargas fiables de video y audio desde YouTube y plataformas de streaming 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 streams HLS con cabeceras de autenticación
- Manejo de contenido protegido y solución de problemas comunes de descarga
Experiencia de Usuario No Técnica (Por Defecto)
Asume que el usuario no es técnico. No le pidas que ejecute comandos. Ejecuta todo tú mismo e informa del progreso en lenguaje sencillo. Evita mencionar las herramientas a menos que el usuario lo pregunte.
Flujo por defecto:
- Pide la URL (si no se proporciona).
- 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 con «confirma que no eres un bot», recurre a YouTube oEmbed para título/subidor/miniatura (la duración puede ser desconocida).
- Ofrece opciones sencillas (video vs. solo audio, calidad, subtítulos, ubicación de guardado).
- Procede con valores predeterminados sensatos si el usuario no especifica:
- Descarga de video en la mejor calidad
- Salida fusionada en MP4
- Video individual solamente (sin listas de reproducción)
- Descarga e informa la ruta del archivo final, el tamaño del archivo y la resolución (si es video).
Ofrece opciones en términos amigables:
- «Descargar el video en la mejor calidad (por defecto)»
- «Descargar solo el audio (MP3)»
- «Elige una calidad: 1080p / 720p / 480p / 360p»
- «Incluir subtítulos (si están disponibles)»
- «Guardar en la carpeta Descargas (por defecto) o dime otra carpeta»
Renderiza siempre 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 extra:
- 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 número de cookies ni detalles de cookies en las respuestas al usuario. Di «usé tu sesión de inicio 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):
- Procede 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:
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? (Carpeta por defecto: Descargas)
Si el usuario dice «solo descarga»:
- Procede con los valores por defecto y confirma cuando finalice la descarga.
- Si está bloqueado por un error 403, configura automáticamente el ayudante de verificación y reintenta.
SOP de Descarga Fiable (Interno)
Sigue este SOP para evitar fallos y confusiones comunes:
- Cita las URLs en los comandos del shell (zsh trata
?como un glob). 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 tokens 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 de reproducción
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 acceder a YouTube a través del mismo proxy.
- Si obtienes «Solo hay imágenes disponibles» o «El formato solicitado no está disponible», trátalo como un fallo del token PO y reintenta después de arreglar el estado del proveedor/navegador.
- Si obtienes errores SSL EOF o de fragmento, trátalo 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(añade--cookies-from-browser chromesi se concede permiso) para obtener metadatos y miniatura. - Si fallan los metadatos de yt-dlp, confía en el fallback de oEmbed del script para título/subidor/miniatura y nota que la duración puede no estar disponible.
- Si hay una URL de miniatura, renderízala en la respuesta con sintaxis de imagen Markdown.
- Pregunta al usuario que elija video vs. solo audio y (opcionalmente) un ajuste de calidad.
- Usa una ubicación de guardado por defecto amigable (carpeta 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, tamaño y resolución (si es video) en lenguaje sencillo.
- Si la descarga falla con errores 403/de fragmento, reintenta una vez con formatos progresivos no m3u8.
- Si aparece «Inicia sesión para confirmar que no eres un bot», solicita acceso a cookies y reintenta con cookies +
web_safari. - Si aparece «Solo hay imágenes disponibles», trátalo como un fallo del token PO y reintenta después de arreglar el estado del proveedor/navegador.
- Inicia el proveedor de tokens PO antes de las descargas (
--auto-po-tokenpor defecto). 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 una ventana del navegador brevemente).
- 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 tokens PO agota el tiempo, 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 en las descargas de yt-dlp o disponibilidad limitada de formatos
- Necesiten ayuda con la selección de formatos o opciones de calidad
- Reporten que solo hay formatos de baja calidad (360p) disponibles
- Pregunten sobre descarga de contenido de YouTube en calidad específica (1080p, 4K, etc.)
- Necesiten convertir videos WebM descargados a formato MP4 para mayor compatibilidad
- Soliciten descargar streams HLS (m3u8) de plataformas como Mux, Vimeo u otros servicios de streaming
- Necesiten descargar streams protegidos que requieran cabeceras 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. Comprobar el Acceso de Calidad Actual (Ejecuta esto tú mismo)
Antes de descargar, comprueba los formatos disponibles:
yt-dlp -F "https://youtu.be/VIDEO_ID"
Si solo aparece el formato 18 (360p): Se necesita configurar un proveedor de tokens PO para acceso de alta calidad.
Flujo de Trabajo de Descarga de Alta Calidad
Paso 1: Instalar el Proveedor de Tokens PO (Configuración Única)
Para acceso a 1080p/1440p/4K, instala un plugin de proveedor de tokens PO en el entorno Python de yt-dlp:
# Encuentra la ruta de Python de yt-dlp (intérprete usado por yt-dlp)
head -1 $(which yt-dlp)
# Instala el plugin usando el intérprete de la línea anterior
<YTDLP_PYTHON> -m pip install bgutil-ytdlp-pot-provider
Verificación: Ejecuta yt-dlp -F "VIDEO_URL" de nuevo. Busca los formatos 137 (1080p), 271 (1440p) o 313 (4K).
Consulta references/po-token-setup.md para instrucciones detalladas de configuración y solución de problemas.
Paso 2: Descargar con la Mejor Calidad
Una vez instalado el proveedor de tokens PO:
# Descargar la mejor calidad hasta 1080p
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
# Descargar la mejor calidad disponible (4K si está disponible)
yt-dlp -f "bestvideo+bestaudio/best" "VIDEO_URL"
Paso 3: Verificar la Calidad de la Descarga
# Comprobar 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 tokens PO es problemática, usa cookies del navegador:
# Firefox
yt-dlp --cookies-from-browser firefox -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
# Chrome
yt-dlp --cookies-from-browser chrome -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
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)
Extrae audio como MP3:
yt-dlp -x --audio-format mp3 "VIDEO_URL"
Directorio de Salida Personalizado (Ejecuta esto tú mismo)
yt-dlp -P ~/Downloads/YouTube "VIDEO_URL"
Descargar con Subtítulos (Ejecuta esto tú mismo)
yt-dlp --write-subs --sub-lang en "VIDEO_URL"
Descargar Lista de Reproducción (Ejecuta esto tú mismo)
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "PLAYLIST_URL"
Convertir WebM a MP4 (Ejecuta esto tú mismo)
Las descargas de alta calidad de YouTube a menudo usan el formato WebM (códec VP9). Convierte a MP4 para mayor compatibilidad:
# Comprueba si ffmpeg está instalado
which ffmpeg || brew install ffmpeg # macOS
# Convierte WebM a MP4 con buenos ajustes 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 aproximadamente 6 veces mayor en hardware moderno.
Referencia Rápida de Solución de Problemas
Solo 360p Disponible (Formato 18)
Causa: Falta el proveedor de tokens PO o yt-dlp desactualizado.
Solución:
- Actualiza yt-dlp:
brew upgrade yt-dlp - Instala el proveedor de tokens 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 tokens PO esté ejecutándose antes de la descarga.
- Mantén la ventana del navegador abierta si usas WPC.
- Si se usan cookies, prefiere el cliente
web_safariy reintenta.
Fallo de Extracción nsig
Síntomas:
WARNING: [youtube] nsig extraction failed: Some formats may be missing
Solución:
- Actualiza yt-dlp a la última versión
- Instala el proveedor de tokens PO
- Si sigue fallando y los tokens PO están deshabilitados, usa el cliente Android:
yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"
Errores SSL EOF / de Fragmento
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 tokens 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 tiempo suficiente para la finalización
- yt-dlp reintenta automáticamente en fallos transitorios
Advertencia de Token PO (Inofensiva)
WARNING: android client https formats require a GVS PO Token
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 Scripts Incluidos
scripts/download_video.py
Usa este envoltorio de conveniencia para iniciar automáticamente un proveedor de tokens PO por defecto 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 "VIDEO_URL"
Argumentos:
url- URL del video de YouTube (requerido)-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- Ajuste preestablecido de calidad (best, 1080p, 720p, 480p, 360p, worst). Por defecto: 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, por defecto: 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 reproducción de YouTube específico (ej., web_safari)--auto-po-token- Iniciar automáticamente el proveedor de tokens PO (por defecto; 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 tokens PO--proxy- URL del proxy para yt-dlp y el proveedor de tokens 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 de fusión (ej., mp4, mkv). Por defecto: mp4--playlist- Permitir descargas de listas de reproducción (por defecto: solo video individual)--info- Imprimir título/subidor/duración/miniatura y salir--no-android-client- Deshabilitar el fallback 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 (por defecto) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Solo cliente Android | ✓ | ✗ | ✗ | ✗ | ✗ |
| Proveedor de tokens PO (manual) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Cookies del navegador | ✓ | ✓ | ✓ |