danielhall/agent-skills

Descarga de video (yt-dlp)

Descarga video o audio desde YouTube y aproximadamente otros 1.800 sitios.

Descarga solo para uso propio del usuario. No ayudes a redistribuir material protegido por derechos de autor de otras personas.

Valores predeterminados

• Ubicación de guardado: ~/Movies para video y ~/Music para audio, a menos que el usuario indique otra carpeta. En Linux, usa ~/Videos.
• Formato: MP4 con video H.264 y audio AAC, a menos que se especifique lo contrario. QuickTime, Final Cut, Premiere e iOS lo reproducen sin necesidad de conversión. Los archivos AV1 y VP9 son mucho más pequeños, pero QuickTime Player a menudo no los abre.
• Resolución: 1080p cuando no se especifica ninguna.
• Extras: incrustar metadatos, miniatura y capítulos.

Verificación previa

yt-dlp --version             # una versión antigua es la causa más común de fallos en YouTube
ffmpeg -version | head -1    # debe ejecutarse realmente, no solo existir
ffprobe -version | head -1   # yt-dlp también lo necesita, y a menudo es el que falta

No verifiques con which ffmpeg. Solo reporta la primera coincidencia en PATH, que puede ser el binario incorrecto. En Macs con Apple Silicon, una compilación Intel residual en /usr/local/bin puede aparecer antes que la compilación de Homebrew en /opt/homebrew/bin. Luego yt-dlp descarga todo, falla en el paso de fusión con bad CPU type in executable o ffmpeg not found, y aún así sale con código de estado 0. Por lo tanto, verifica la salida en busca de ERROR en lugar de confiar en el código de salida.

En Apple Silicon, pasa la ruta correcta explícitamente:

yt-dlp --ffmpeg-location /opt/homebrew/bin ...

Si una fusión falla, los archivos de video y audio separados (.fNNN) quedan en el disco. Combínalos con ffmpeg como se describe en Fusionar archivos sobrantes, sin necesidad de descargar de nuevo.

Antes de comenzar, verifica lo que vas a descargar:

yt-dlp --print "%(title)s | %(duration_string)s | %(uploader)s" "URL"
yt-dlp -F "URL"              # todos los formatos disponibles
df -h ~/Movies | tail -1     # espacio libre

Informa al usuario el título, la duración y el tamaño aproximado antes de comenzar cualquier descarga de más de 1 GB aproximadamente.

El comando principal

cd ~/Movies && yt-dlp \
  -f "bv*[height<=1080][vcodec^=avc1]+ba[ext=m4a]/bv*[height<=1080]+ba/b[height<=1080]" \
  --merge-output-format mp4 \
  --embed-metadata --embed-thumbnail --embed-chapters \
  -o "%(title)s [%(id)s].%(ext)s" \
  --newline \
  "URL"

Agrega --ffmpeg-location /opt/homebrew/bin en Macs con Apple Silicon.

La cadena de formato es una lista de alternativas, probadas de izquierda a derecha:

1. bv*[height<=1080][vcodec^=avc1]+ba[ext=m4a]: el mejor video H.264 hasta 1080p más el mejor audio M4A. Esta es la opción más compatible.
2. bv*[height<=1080]+ba: cualquier códec, para sitios sin H.264 a esa altura.
3. b[height<=1080]: un solo archivo con video y audio ya combinados, para sitios que no los ofrecen por separado.

Cambia 1080 por 720, 1440 o 2160 para otras resoluciones, o elimina el filtro de altura para la mejor disponible.

--newline imprime cada actualización de progreso en su propia línea, lo que mantiene los registros legibles.

El [%(id)s] en el nombre del archivo evita que las subidas repetidas con el mismo título se sobrescriban y registra de dónde proviene el archivo. Agrega --restrict-filenames si las barras o emojis en los títulos causan problemas.

Descargas largas

Ejecuta cualquier cosa de más de unos pocos cientos de MB en segundo plano, e informa al usuario el título y el tamaño esperado en lugar de esperar.

No canalices una descarga en segundo plano a través de tail o head. Esto almacena en búfer la salida, por lo que el registro permanece vacío hasta que la descarga finalice. Para verificar el progreso, compara el archivo .part en crecimiento con el tamaño de -F:

ls -la ~/Movies/*.part

Para reanudar una descarga interrumpida, ejecuta el mismo comando nuevamente. yt-dlp continúa desde el archivo .part.

Variaciones

Solo audio (MP3):

cd ~/Music && yt-dlp -x --audio-format mp3 --audio-quality 0 \
  --embed-metadata --embed-thumbnail -o "%(title)s.%(ext)s" "URL"

Usa --audio-format m4a para mantener el audio AAC original de YouTube. Es más rápido y no pierde calidad por la recodificación.

Mejor calidad en cualquier códec:

yt-dlp -f "bv*+ba/b" --merge-output-format mkv "URL"

MKV admite cualquier combinación de códecs. Advierte al usuario que QuickTime puede no abrirlo.

Subtítulos:

yt-dlp --write-subs --write-auto-subs --sub-langs "en.*" --embed-subs "URL"

--write-auto-subs incluye los subtítulos automáticos de YouTube. Agrega --skip-download para obtener solo la transcripción.

Parte de un video:

yt-dlp --download-sections "*00:10:00-00:15:30" "URL"

Lista de reproducción o canal:

yt-dlp -o "%(playlist)s/%(playlist_index)03d - %(title)s.%(ext)s" "URL"

Agrega --playlist-items 1-10 para parte de una lista de reproducción. Agrega --download-archive archive.txt para que al ejecutarlo de nuevo se salte lo ya descargado, útil para cualquier cosa que vayas a actualizar después.

Simulación: --simulate calcula los formatos y nombres de archivo sin descargar nada.

Fusionar archivos sobrantes

Si el paso de fusión falló, combina los archivos separados sin descargar de nuevo:

ffmpeg -i "NAME.f137.mp4" -i "NAME.f140.m4a" -c copy -movflags +faststart "NAME.mp4"

-c copy une los flujos sin recodificar, por lo que es rápido y sin pérdida de calidad. +faststart mueve el índice al inicio del archivo para que pueda reproducirse antes de cargarse por completo. Elimina los archivos .fNNN una vez que el resultado se reproduzca correctamente.

Solución de problemas

Problema	Solución
Requested format is not available	Ejecuta -F y elige de la lista real. Es posible que el sitio no ofrezca esa resolución o códec.
HTTP 403, "unable to extract" o errores de firma	yt-dlp está desactualizado. Actualízalo (brew upgrade yt-dlp o pip install -U yt-dlp). Verifica esto primero ante cualquier fallo en YouTube.
"Sign in to confirm you're not a bot"	Agrega --cookies-from-browser chrome (o safari, firefox). Cierra el navegador primero, porque Chrome bloquea su base de datos de cookies.
ffmpeg not found después de una descarga completa	ffmpeg falta o es la arquitectura incorrecta. Consulta Verificación previa, luego fusiona los archivos sobrantes en lugar de descargar de nuevo.
bad CPU type in executable	Se está usando un binario Intel en lugar del de Apple Silicon. Pasa --ffmpeg-location /opt/homebrew/bin.
La fusión falla o no hay audio	ffmpeg es demasiado antiguo o falta ffprobe. Reinstala ffmpeg.
La descarga es muy lenta	Agrega --concurrent-fragments 4.
Video con restricción de edad o privado	Usa --cookies-from-browser con un navegador que haya iniciado sesión.