Communitygithub.com

YouTube Downloader

Descarga videos de YouTube y transmisiones HLS (m3u8) desde plataformas como Mux, Vimeo, etc. usando yt-dlp y ffmpeg. Activa esta habilidad cuando los usuarios soliciten descargar videos, extraer audio, manejar contenido protegido con encabezados de autenticación, o solucionar problemas de descarga como fallos de extracción nsig, errores 403 o problemas de extracción de cookies.

¿Qué es YouTube Downloader?

Esta habilidad del agente ofrece un flujo de trabajo completo para descargar videos y audio de alta calidad desde YouTube (hasta 4K) y transmisiones HLS (m3u8) desde plataformas como Mux, Vimeo y otros servicios de streaming, utilizando las herramientas yt-dlp y ffmpeg. Es útil para desarrolladores y usuarios que necesitan descargas confiables, manejo de contenido protegido con encabezados de autenticación y resolución de problemas comunes como fallos de extracción nsig, errores 403 o formatos limitados. La habilidad soporta múltiples plataformas (macOS, Linux, Windows) y proporciona guías paso a paso para instalar proveedores de tokens PO (Proof of Origin) para acceso a formatos superiores a 1080p, así como métodos alternativos con cookies de navegador. Incluye referencias rápidas de solución de problemas, scripts empaquetados y tablas de expectativas de calidad. Para transmisiones HLS, se usa ffmpeg con encabezados HTTP personalizados para manejar la autenticación requerida por CDNs, e incluye técnicas para identificar, descargar y fusionar flujos de audio y video por separado.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/IGTA-Tech/claude-skills-research/tree/HEAD/claude-code-skills/youtube-downloader

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿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:

  1. Actualizar yt-dlp: brew upgrade yt-dlp
  2. Instalar el proveedor de tokens PO (ver Paso 1 arriba)
  3. 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:

  1. Actualizar yt-dlp a la última versión
  2. Instalar el proveedor de tokens PO
  3. 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ón360p720p1080p1440p4K
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:

  1. Abra las Herramientas de Desarrollo del navegador → pestaña Red
  2. Reproduzca el video
  3. Filtre por "m3u8" para encontrar las URL de las listas de reproducción
  4. 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:

  1. 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
  1. 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
  1. 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:

  1. Verifique que el encabezado Referer coincida con el sitio web de origen del video
  2. Compruebe si se necesitan encabezados adicionales (Origin, User-Agent)
  3. 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:

  1. Obtenga URL nuevas desde las Herramientas de Desarrollo del navegador
  2. Descargue inmediatamente después de obtener las URL
  3. 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

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

IGTA-Tech/claude-skills-research

Use when localizing apps, using String Catalogs, generating type-safe symbols (Xcode 26+), handling plurals, RTL layouts, locale-aware formatting, or migrating from .strings files - comprehensive i18n patterns for Xcode 15-26

IGTA-Tech/claude-skills-research

Use when implementing SwiftUI animations, understanding VectorArithmetic, using @Animatable macro, choosing between spring and timing curve animations, or debugging animation behavior - comprehensive animation reference from iOS 13 through iOS 26

IGTA-Tech/claude-skills-research

Use when CAAnimation completion handler doesn't fire, spring physics look wrong on device, animation duration mismatches actual time, gesture + animation interaction causes jank, or timing differs between simulator and real hardware - systematic CAAnimation diagnosis with CATransaction patterns, frame rate awareness, and device-specific behavior

IGTA-Tech/claude-skills-research

This skill should be used when comparing two videos to analyze compression results or quality differences. Generates interactive HTML reports with quality metrics (PSNR, SSIM) and frame-by-frame visual comparisons. Triggers when users mention "compare videos", "video quality", "compression analysis", "before/after compression", or request quality assessment of compressed videos.

IGTA-Tech/claude-skills-research

Write high-converting landing page copy using proven frameworks like PAS (Problem-Agitate-Solution), AIDA, and StoryBrand. Creates headlines, value propositions, CTAs, and full page sections optimized for conversion. Use when users need landing page copy, sales page content, or marketing website text.

IGTA-Tech/claude-skills-research

Downloads videos from YouTube and other platforms for offline viewing, editing, or archival. Handles various formats and quality options.

IGTA-Tech/claude-skills-research

Download YouTube video transcripts when user provides a YouTube URL or asks to download/get/fetch a transcript from YouTube. Also use when user wants to transcribe or get captions/subtitles from a YouTube video.

Skills relacionados