¿Qué hace 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
Cuándo Usar Esta Habilidad
Esta habilidad debe invocarse cuando los usuarios:
- Solicitan descargar videos o listas de reproducción de YouTube
- Quieren extraer audio de videos de YouTube
- Experimentan fallos en la descarga con yt-dlp o disponibilidad limitada de formatos
- Necesitan ayuda con la selección de formato o opciones de calidad
- Reportan que solo están disponibles formatos de baja calidad (360p)
- Preguntan sobre descargar contenido de YouTube en una calidad específica (1080p, 4K, etc.)
- Necesitan convertir videos WebM descargados a formato MP4 para mayor compatibilidad
- Solicitan descargar transmisiones HLS (m3u8) desde plataformas como Mux, Vimeo u otros servicios de streaming
- Necesitan descargar transmisiones protegidas que requieren encabezados de autenticación
Prerrequisitos
1. Verificar la Instalación de yt-dlp
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 Actual a la Calidad
Antes de descargar, verifique 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 tokens PO para acceso de alta calidad.
Flujo de Trabajo para Descargas de Alta Calidad
Paso 1: Instalar el Proveedor de Tokens PO (Configuración Única)
Para acceso a 1080p/1440p/4K, instale un complemento de proveedor de tokens PO en el entorno Python de yt-dlp:
# Encuentre la ruta de Python de yt-dlp
head -1 $(which yt-dlp)
# Instale el complemento (ajuste la ruta para que coincida con la versión de yt-dlp)
/opt/homebrew/Cellar/yt-dlp/$(yt-dlp --version)/libexec/bin/python -m pip install bgutil-ytdlp-pot-provider
Verificación: Ejecute yt-dlp -F "VIDEO_URL" de nuevo. Busque los formatos 137 (1080p), 271 (1440p) o 313 (4K).
Consulte 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
# Verificar 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, use 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. Requisito: Debe haber iniciado sesión en YouTube en el navegador especificado.
Tareas Comunes
Descarga Solo de Audio
Extraer audio como MP3:
yt-dlp -x --audio-format mp3 "VIDEO_URL"
Directorio de Salida Personalizado
yt-dlp -P ~/Downloads/YouTube "VIDEO_URL"
Descargar con Subtítulos
yt-dlp --write-subs --sub-lang en "VIDEO_URL"
Descarga de Lista de Reproducción
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "PLAYLIST_URL"
Convertir WebM a MP4
Las descargas de alta calidad de YouTube a menudo usan formato WebM (códec VP9). Convierta a MP4 para mayor compatibilidad:
# Verificar si ffmpeg está instalado
which ffmpeg || brew install ffmpeg # macOS
# Convertir 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: Usar 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, más bajo = mejor calidad)-c:a aac: Usar 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 ~6x 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:
- Actualizar yt-dlp:
brew upgrade yt-dlp - Instalar el proveedor de tokens PO (ver Paso 1 arriba)
- O usar el método de cookies del navegador
Falló la Extracción nsig
Síntomas:
ADVERTENCIA: [youtube] Falló la extracción nsig: algunos formatos pueden faltar
Solución:
- Actualizar yt-dlp a la última versión
- Instalar el proveedor de tokens PO
- Si aún falla, usar el cliente Android:
yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"
Descargas Lentas o Errores de Red
Para usuarios en China o detrás de servidores proxy restrictivos:
- Las descargas pueden ser lentas debido a las condiciones de la red
- Permita suficiente tiempo para completar
- yt-dlp reintenta automáticamente en fallos transitorios
Advertencia de Token PO (Inofensivo)
ADVERTENCIA: Los formatos https del cliente Android requieren un token GVS PO
Acción: Ignore si la descarga es exitosa. Esto indica que el cliente Android tiene acceso limitado a formatos sin tokens PO.
Referencia de Scripts Empaquetados
scripts/download_video.py
Un envoltorio de conveniencia que aplica la solución alternativa del cliente Android por defecto:
Uso básico:
scripts/download_video.py "VIDEO_URL"
Argumentos:
url- URL del video de YouTube (obligatorio)-o, --output-dir- Directorio de salida-f, --format- Especificación de formato-a, --audio-only- Extraer audio como MP3-F, --list-formats- Listar formatos disponibles--no-android-client- Deshabilitar la solución alternativa del cliente Android
Nota: Este script usa el cliente Android (solo 360p sin tokens PO). Para alta calidad, use yt-dlp directamente con el proveedor de tokens PO.
Expectativas de Calidad
| Configuración | 360p | 720p | 1080p | 1440p | 4K |
|---|---|---|---|---|---|
| Sin configuración (predeterminado) | ✗ | ✗ | ✗ | ✗ | ✗ |
| Solo cliente Android | ✓ | ✗ | ✗ | ✗ | ✗ |
| Proveedor de tokens PO | ✓ | ✓ | ✓ | ✓ | ✓ |
| Cookies del navegador | ✓ | ✓ | ✓ | ✓ | ✓ |
Descargas de Transmisiones HLS (m3u8)
Para plataformas de streaming como Mux, Vimeo y otros servicios basados en HLS, use ffmpeg como herramienta principal. Estas transmisiones a menudo requieren encabezados de autenticación que yt-dlp puede no manejar correctamente.
Identificación de Transmisiones HLS
Las transmisiones HLS usan archivos de lista de reproducción .m3u8:
- Lista de reproducción maestra: Enumera múltiples opciones de calidad
- Lista de reproducción de rendition: Contiene las URL reales de los segmentos de video/audio
Flujo de Trabajo de Descarga
Paso 1: Obtener la URL de la Transmisión
Obtenga la URL m3u8 de la fuente de video. Para transmisiones protegidas:
- Abra las Herramientas de Desarrollo del navegador → pestaña Red
- Reproduzca el video
- Filtre por "m3u8" para encontrar las URL de las listas de reproducción
- Copie la URL de rendition (generalmente contiene información de calidad como "rendition.m3u8")
Paso 2: Identificar los Encabezados Requeridos
Muchos CDN requieren encabezados de autenticación:
- Referer: Sitio web de origen (por ejemplo,
https://maven.com/) - Origin: Igual que Referer para CORS
- User-Agent: Identificación del navegador
Verifique en la pestaña Red qué encabezados envía el navegador.
Paso 3: Descargar con ffmpeg
Use ffmpeg con el flag -headers para transmisiones protegidas:
ffmpeg -headers "Referer: https://example.com/" \
-protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
-i "https://cdn.example.com/path/rendition.m3u8?params" \
-c copy -bsf:a aac_adtstoasc \
output.mp4
Parámetros clave:
-headers: Establecer encabezados HTTP (crítico para autenticación)-protocol_whitelist: Habilitar protocolos requeridos para HLS-c copy: Copia de flujo (sin recodificar, más rápido)-bsf:a aac_adtstoasc: Corregir compatibilidad de audio AAC
Patrones de encabezados comunes:
# Encabezado único
-headers "Referer: https://example.com/"
# Múltiples encabezados
-headers "Referer: https://example.com/" \
-headers "User-Agent: Mozilla/5.0..."
# Sintaxis alternativa
-headers $'Referer: https://example.com/\r\nUser-Agent: Mozilla/5.0...'
Manejo de Flujos de Audio/Video Separados
Algunas plataformas (como Mux) entregan audio y video por separado:
- Descargar flujo de audio:
ffmpeg -headers "Referer: https://example.com/" \
-protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
-i "https://cdn.example.com/audio/rendition.m3u8" \
-c copy audio.m4a
- Descargar flujo de video:
ffmpeg -headers "Referer: https://example.com/" \
-protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
-i "https://cdn.example.com/video/rendition.m3u8" \
-c copy video.mp4
- Fusionar flujos:
ffmpeg -i video.mp4 -i audio.m4a -c copy merged.mp4
Solución de Problemas de Descargas HLS
Errores 403 Prohibido
Causa: Faltan encabezados de autenticación o son incorrectos.
Solución:
- Verifique que el encabezado Referer coincida con el sitio web de origen del video
- Compruebe si se necesitan encabezados adicionales (Origin, User-Agent)
- Asegúrese de que la URL m3u8 incluya todos los parámetros de consulta del navegador
yt-dlp Atascado en Extracción de Cookies
Síntoma: Extracting cookies from chrome se cuelga indefinidamente.
Solución: Use ffmpeg directamente en lugar de yt-dlp para transmisiones HLS.
Protocolo No Incluido en la Lista Blanca
Error: Protocol 'https' not on whitelist 'file,crypto,data'
Solución: Agregue -protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy
Segmentos Vacíos o Sin Flujos
Causa: Firmas caducadas en las URL m3u8.
Solución:
- Obtenga URL nuevas desde las Herramientas de Desarrollo del navegador
- Descargue inmediatamente después de obtener las URL
- Busque URL de rendition con parámetros de firma actualizados
Consejos de Rendimiento
- Las descargas HLS generalmente se ejecutan a 10-15x la velocidad en tiempo real
- Sin recodificación con
-c copy(más rápido) - Monitoree la descarga con la visualización de progreso en tiempo real
- Use rutas de salida absolutas para evitar confusión de directorios
Lecturas Adicionales
- Configuración de Tokens PO: Consulte
references/po-token-setup.mdpara instalación detallada y solución de problemas - Documentación de yt-dlp: https://github.com/yt-dlp/yt-dlp
- Guía de Selección de Formato: https://github.com/yt-dlp/yt-dlp#format-selection