Communitygithub.com

Descargador de Transcripciones de YouTube

Descarga transcripciones de videos de YouTube cuando el usuario proporciona una URL de YouTube o solicita descargar/obtener/recuperar una transcripción. También se usa cuando el usuario quiere transcribir u obtener subtítulos de un video de YouTube.

¿Qué es Descargador de Transcripciones de YouTube?

Esta habilidad permite a un agente de IA descargar transcripciones (subtítulos) de videos de YouTube utilizando yt-dlp como herramienta principal. Está diseñada para agentes que ejecutan comandos en terminal (como Claude Code, Cursor o Codex). El flujo de trabajo prioriza la descarga de subtítulos manuales (mejor calidad), luego subtítulos generados automáticamente, y como último recurso, ofrece transcribir el audio con Whisper (OpenAI). Incluye comprobaciones de instalación de yt-dlp y Whisper, manejo de errores comunes (videos privados, regiones bloqueadas, falta de subtítulos), y post-procesamiento para convertir archivos VTT a texto plano con desduplicación de líneas. También permite limpiar archivos temporales y generar nombres de archivo significativos a partir del título del video. Es útil para extraer contenido textual de videos de YouTube para análisis, indexación o lectura sin ver el video.

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

Preguntar en tu IA favorita

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

Documentación

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

  1. Comprobar si yt-dlp está instalado - instalarlo si es necesario
  2. Listar subtítulos disponibles - ver qué hay realmente disponible
  3. Probar subtítulos manuales primero (--write-sub) - máxima calidad
  4. Fallback a subtítulos automáticos (--write-auto-sub) - generalmente disponibles
  5. Último recurso: Transcripción con Whisper - si no hay subtítulos (requiere confirmación del usuario)
  6. Confirmar la descarga y mostrar al usuario dónde se guardó el archivo
  7. 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 ESTE
  • small - 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('&amp;', '&').replace('&gt;', '>').replace('&lt;', '<')
            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('&amp;', '&').replace('&gt;', '>').replace('&lt;', '<')
            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-sub para 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('&amp;', '&').replace('&gt;', '>').replace('&lt;', '<')
            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-sub como --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-certificate si 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 en para solo inglés
  • Listar disponibles con --list-subs primero

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

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

Download YouTube videos and HLS streams (m3u8) from platforms like Mux, Vimeo, etc. using yt-dlp and ffmpeg. Use this skill when users request downloading videos, extracting audio, handling protected streams with authentication headers, or troubleshooting download issues like nsig extraction failures, 403 errors, or cookie extraction problems.

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.

Skills relacionados