¿Qué hace Descargador de Transcripciones de YouTube?
Esta habilidad ayuda a descargar transcripciones (subtítulos) de videos de YouTube usando yt-dlp.
Cuándo Usar Esta Habilidad
Activa esta habilidad cuando el usuario:
- Proporciona una URL de YouTube y quiere la transcripción
- Pide "descargar transcripción de YouTube"
- Quiere "obtener subtítulos" de un video
- Pide "transcribir un video de YouTube"
- Necesita el contenido de texto de un video de YouTube
Cómo Funciona
Orden de Prioridad:
- Comprobar si yt-dlp está instalado - instalarlo si es necesario
- Listar subtítulos disponibles - ver qué hay realmente disponible
- Probar subtítulos manuales primero (
--write-sub) - máxima calidad - Fallback a subtítulos automáticos (
--write-auto-sub) - generalmente disponibles - Último recurso: Transcripción con Whisper - si no hay subtítulos (requiere confirmación del usuario)
- Confirmar la descarga y mostrar al usuario dónde se guardó el archivo
- Opcionalmente limpiar el formato VTT si el usuario quiere texto plano
Comprobación de Instalación
IMPORTANTE: Siempre comprobar primero si yt-dlp está instalado:
which yt-dlp || command -v yt-dlp
Si No Está Instalado
Intentar instalación automática según el sistema:
macOS (Homebrew):
brew install yt-dlp
Linux (apt/Debian/Ubuntu):
sudo apt update && sudo apt install -y yt-dlp
Alternativa (pip - funciona en todos los sistemas):
pip3 install yt-dlp
# o
python3 -m pip install yt-dlp
Si la instalación falla: Informar al usuario que necesita instalar yt-dlp manualmente y proporcionarle las instrucciones de instalación desde https://github.com/yt-dlp/yt-dlp#installation
Comprobar Subtítulos Disponibles
SIEMPRE hacer esto primero antes de intentar descargar:
y t-dlp --list-subs "YOUTUBE_URL"
Esto muestra qué tipos de subtítulos están disponibles sin descargar nada. Buscar:
- Subtítulos manuales (mejor calidad)
- Subtítulos generados automáticamente (generalmente disponibles)
- Idiomas disponibles
Estrategia de Descarga
Opción 1: Subtítulos Manuales (Preferida)
Intentar esto primero - máxima calidad, creados por humanos:
y t-dlp --write-sub --skip-download --output "NOMBRE_SALIDA" "YOUTUBE_URL"
Opción 2: Subtítulos Generados Automáticamente (Fallback)
Si los subtítulos manuales no están disponibles:
y t-dlp --write-auto-sub --skip-download --output "NOMBRE_SALIDA" "YOUTUBE_URL"
Ambos comandos crean un archivo .vtt (formato de subtítulos WebVTT).
Opción 3: Transcripción con Whisper (Último Recurso)
Usar SOLO si tanto los subtítulos manuales como los automáticos no están disponibles.
Paso 1: Mostrar el Tamaño del Archivo y Solicitar Confirmación
# Obtener estimación del tamaño del archivo de audio
y t-dlp --print "%(filesize,filesize_approx)s" -f "bestaudio" "YOUTUBE_URL"
# O obtener la duración para estimar
y t-dlp --print "%(duration)s %(title)s" "YOUTUBE_URL"
IMPORTANTE: Mostrar el tamaño del archivo al usuario y preguntar: "No hay subtítulos disponibles. Puedo descargar el audio (aproximadamente X MB) y transcribirlo usando Whisper. ¿Deseas continuar?"
Esperar la confirmación del usuario antes de continuar.
Paso 2: Comprobar la Instalación de Whisper
command -v whisper
Si no está instalado, preguntar al usuario: "Whisper no está instalado. ¿Instalarlo con pip install openai-whisper (requiere ~1-3GB para modelos)? Esta es una instalación única."
Esperar la confirmación del usuario antes de instalar.
Instalar si está aprobado:
pip3 install openai-whisper
Paso 3: Descargar Solo el Audio
y t-dlp -x --audio-format mp3 --output "audio_%(id)s.%(ext)s" "YOUTUBE_URL"
Paso 4: Transcribir con Whisper
# Detección automática de idioma (recomendada)
whisper audio_VIDEO_ID.mp3 --model base --output_format vtt
# O especificar el idioma si se conoce
whisper audio_VIDEO_ID.mp3 --model base --language es --output_format vtt
Opciones de Modelo (ceñirse a base por ahora):
tiny- más rápido, menos preciso (~1GB)base- buen equilibrio (~1GB) ← USAR ESTEsmall- mejor precisión (~2GB)medium- muy bueno (~5GB)large- máxima precisión (~10GB)
Paso 5: Limpieza
Después de que la transcripción se complete, preguntar al usuario: "¡Transcripción completa! ¿Quieres que elimine el archivo de audio para ahorrar espacio?"
Si sí:
rm audio_VIDEO_ID.mp3
Obtener Información del Video
Extraer Título del Video (para el nombre de archivo)
y t-dlp --print "%(title)s" "YOUTUBE_URL"
Usar esto para crear nombres de archivo significativos basados en el título del video. Limpiar el título para la compatibilidad con el sistema de archivos:
- Reemplazar
/con- - Reemplazar caracteres especiales que puedan causar problemas
- Considerar usar una versión saneada:
$(yt-dlp --print "%(title)s" "URL" | tr '/' '-' | tr ':' '-')
Post-Procesamiento
Convertir a Texto Plano (Recomendado)
Los archivos VTT generados automáticamente por YouTube contienen líneas duplicadas porque los subtítulos se muestran progresivamente con marcas de tiempo superpuestas. Siempre deduplicar al convertir a texto plano preservando el orden de habla original.
python3 -c "
import sys, re
seen = set()
with open('transcript.en.vtt', 'r') as f:
for line in f:
line = line.strip()
if line and not line.startswith('WEBVTT') and not line.startswith('Kind:') and not line.startswith('Language:') and '-->' not in line:
clean = re.sub('<[^>]*>', '', line)
clean = clean.replace('&', '&').replace('>', '>').replace('<', '<')
if clean and clean not in seen:
print(clean)
seen.add(clean)
" > transcript.txt
Post-Procesamiento Completo con Título del Video
# Obtener título del video
VIDEO_TITLE=$(yt-dlp --print "%(title)s" "YOUTUBE_URL" | tr '/' '_' | tr ':' '-' | tr '?' '' | tr '"' '')
# Encontrar el archivo VTT
VTT_FILE=$(ls *.vtt | head -n 1)
# Convertir con deduplicación
python3 -c "
import sys, re
seen = set()
with open('$VTT_FILE', 'r') as f:
for line in f:
line = line.strip()
if line and not line.startswith('WEBVTT') and not line.startswith('Kind:') and not line.startswith('Language:') and '-->' not in line:
clean = re.sub('<[^>]*>', '', line)
clean = clean.replace('&', '&').replace('>', '>').replace('<', '<')
if clean and clean not in seen:
print(clean)
seen.add(clean)
" > \"${VIDEO_TITLE}.txt\"
echo "✓ Guardado en: ${VIDEO_TITLE}.txt"
# Limpiar archivo VTT
rm \"$VTT_FILE\"
echo "✓ Archivo VTT temporal limpiado"
Formatos de Salida
- Formato VTT (
.vtt): Incluye marcas de tiempo y formato, bueno para reproductores de video - Texto plano (
.txt): Solo el contenido de texto, bueno para lectura o análisis
Consejos
- El nombre de archivo será
{nombre_salida}.{código_idioma}.vtt(ej.,transcript.en.vtt) - La mayoría de los videos de YouTube tienen subtítulos automáticos en español/inglés
- Algunos videos pueden tener múltiples opciones de idioma
- Si los subtítulos automáticos no están disponibles, probar
--write-subpara subtítulos manuales
Ejemplo de Flujo de Trabajo Completo
VIDEO_URL="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
# Obtener título del video para el nombre de archivo
VIDEO_TITLE=$(yt-dlp --print "%(title)s" "$VIDEO_URL" | tr '/' '_' | tr ':' '-' | tr '?' '' | tr '"' '')
OUTPUT_NAME="transcript_temp"
# ============================================
# PASO 1: Comprobar si yt-dlp está instalado
# ============================================
if ! command -v yt-dlp &> /dev/null; then
echo "yt-dlp no encontrado, intentando instalar..."
if command -v brew &> /dev/null; then
brew install yt-dlp
elif command -v apt &> /dev/null; then
sudo apt update && sudo apt install -y yt-dlp
else
pip3 install yt-dlp
fi
fi
# ============================================
# PASO 2: Listar subtítulos disponibles
# ============================================
echo "Comprobando subtítulos disponibles..."
yt-dlp --list-subs "$VIDEO_URL"
# ============================================
# PASO 3: Probar subtítulos manuales primero
# ============================================
echo "Intentando descargar subtítulos manuales..."
if yt-dlp --write-sub --skip-download --output "$OUTPUT_NAME" "$VIDEO_URL" 2>/dev/null; then
echo "✓ ¡Subtítulos manuales descargados correctamente!"
ls -lh ${OUTPUT_NAME}.*
else
# ============================================
# PASO 4: Fallback a subtítulos automáticos
# ============================================
echo "Subtítulos manuales no disponibles. Probando automáticos..."
if yt-dlp --write-auto-sub --skip-download --output "$OUTPUT_NAME" "$VIDEO_URL" 2>/dev/null; then
echo "✓ ¡Subtítulos automáticos descargados correctamente!"
ls -lh ${OUTPUT_NAME}.*
else
# ============================================
# PASO 5: Último recurso - Transcripción con Whisper
# ============================================
echo "⚠ No hay subtítulos disponibles para este video."
# Obtener tamaño del archivo
FILE_SIZE=$(yt-dlp --print "%(filesize_approx)s" -f "bestaudio" "$VIDEO_URL")
DURATION=$(yt-dlp --print "%(duration)s" "$VIDEO_URL")
TITLE=$(yt-dlp --print "%(title)s" "$VIDEO_URL")
echo "Video: $TITLE"
echo "Duración: $((DURATION / 60)) minutos"
echo "Tamaño de audio: ~$((FILE_SIZE / 1024 / 1024)) MB"
echo ""
echo "¿Quieres descargar y transcribir con Whisper? (s/n)"
read -r RESPONSE
if [[ "$RESPONSE" =~ ^[Ss]$ ]]; then
# Comprobar Whisper
if ! command -v whisper &> /dev/null; then
echo "Whisper no instalado. ¿Instalarlo ahora? (requiere ~1-3GB) (s/n)"
read -r INSTALL_RESPONSE
if [[ "$INSTALL_RESPONSE" =~ ^[Ss]$ ]]; then
pip3 install openai-whisper
else
echo "No se puede continuar sin Whisper. Saliendo."
exit 1
fi
fi
# Descargar audio
echo "Descargando audio..."
yt-dlp -x --audio-format mp3 --output "audio_%(id)s.%(ext)s" "$VIDEO_URL"
# Obtener el nombre real del archivo de audio
AUDIO_FILE=$(ls audio_*.mp3 | head -n 1)
# Transcribir
echo "Transcribiendo con Whisper (esto puede tomar unos minutos)..."
whisper "$AUDIO_FILE" --model base --output_format vtt
# Limpiar
echo "¡Transcripción completa! ¿Eliminar archivo de audio? (s/n)"
read -r CLEANUP_RESPONSE
if [[ "$CLEANUP_RESPONSE" =~ ^[Ss]$ ]]; then
rm "$AUDIO_FILE"
echo "Archivo de audio eliminado."
fi
ls -lh *.vtt
else
echo "Transcripción cancelada."
exit 0
fi
fi
fi
# ============================================
# PASO 6: Convertir a texto plano legible con deduplicación
# ============================================
VTT_FILE=$(ls ${OUTPUT_NAME}*.vtt 2>/dev/null || ls *.vtt | head -n 1)
if [ -f "$VTT_FILE" ]; then
echo "Convirtiendo a formato legible y eliminando duplicados..."
python3 -c "
import sys, re
seen = set()
with open('$VTT_FILE', 'r') as f:
for line in f:
line = line.strip()
if line and not line.startswith('WEBVTT') and not line.startswith('Kind:') and not line.startswith('Language:') and '-->' not in line:
clean = re.sub('<[^>]*>', '', line)
clean = clean.replace('&', '&').replace('>', '>').replace('<', '<')
if clean and clean not in seen:
print(clean)
seen.add(clean)
" > \"${VIDEO_TITLE}.txt\"
echo "✓ Guardado en: ${VIDEO_TITLE}.txt"
# Limpiar archivo VTT temporal
rm \"$VTT_FILE\"
echo "✓ Archivo VTT temporal limpiado"
else
echo "⚠ No se encontró archivo VTT para convertir"
fi
echo "✓ ¡Completo!"
Nota: Este flujo de trabajo completo maneja todos los escenarios con comprobaciones de errores adecuadas y solicitudes al usuario en cada punto de decisión.
Manejo de Errores
Problemas Comunes y Soluciones:
1. yt-dlp no instalado
- Intentar instalación automática según el sistema (Homebrew/apt/pip)
- Si la instalación falla, proporcionar enlace de instalación manual
- Verificar la instalación antes de continuar
2. No hay subtítulos disponibles
- Listar subtítulos disponibles primero para confirmar
- Probar tanto
--write-subcomo--write-auto-sub - Si ambos fallan, ofrecer la opción de transcripción con Whisper
- Mostrar el tamaño del archivo y solicitar confirmación del usuario antes de descargar audio
3. Video inválido o privado
- Comprobar si la URL tiene el formato correcto:
https://www.youtube.com/watch?v=VIDEO_ID - Algunos videos pueden ser privados, restringidos por edad o bloqueados geográficamente
- Informar al usuario del error específico de yt-dlp
4. La instalación de Whisper falla
- Puede requerir dependencias del sistema (ffmpeg, rust)
- Proporcionar fallback: "Instalar manualmente con:
pip3 install openai-whisper" - Comprobar el espacio disponible en disco (los modelos requieren 1-10GB según el tamaño)
5. Descarga interrumpida o fallida
- Comprobar la conexión a internet
- Verificar suficiente espacio en disco
- Intentar de nuevo con
--no-check-certificatesi ocurren problemas de SSL
6. Múltiples idiomas de subtítulos
- Por defecto, yt-dlp descarga todos los idiomas disponibles
- Se puede especificar con
--sub-langs enpara solo inglés - Listar disponibles con
--list-subsprimero
Mejores Prácticas:
- ✅ Siempre comprobar qué está disponible antes de intentar descargar (
--list-subs) - ✅ Verificar el éxito en cada paso antes de continuar al siguiente
- ✅ Preguntar al usuario antes de descargas grandes (archivos de audio, modelos de Whisper)
- ✅ Limpiar archivos temporales después del procesamiento
- ✅ Proporcionar retroalimentación clara sobre lo que está sucediendo en cada etapa
- ✅ Manejar errores con gracia y mensajes útiles