Communitygithub.com

Downloader de Transcrições do YouTube

Baixa transcrições (legendagem/ocultação) de vídeos do YouTube quando o usuário fornece uma URL ou solicita a obtenção de legendas/transcrição.

O que é Downloader de Transcrições do YouTube?

Esta skill permite que agentes de IA baixem automaticamente transcrições de vídeos do YouTube usando a ferramenta `yt-dlp`. Ela é ativada quando um usuário fornece uma URL do YouTube ou pede para 'baixar transcrição', 'obter legendas' ou 'transcrever um vídeo'. A skill segue uma ordem de prioridade: primeiro verifica se `yt-dlp` está instalado, depois lista as legendas disponíveis, tenta baixar legendas manuais (melhor qualidade), recorre a legendas automáticas e, como último recurso, oferece ao usuário a opção de transcrever o áudio via Whisper (requer confirmação do usuário). Inclui etapas de pós-processamento para converter arquivos VTT em texto simples com desduplicação de linhas e limpeza de arquivos temporários. É compatível com qualquer sistema que tenha `yt-dlp` instalado (macOS via Homebrew, Linux via apt, ou pip em todos os sistemas).

Funciona com✓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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Downloader de Transcrições do YouTube faz?

Esta skill ajuda a baixar transcrições (legendas/ocultação) de vídeos do YouTube usando yt-dlp.

Quando Usar Esta Skill

Ative esta skill quando o usuário:

  • Fornecer uma URL do YouTube e quiser a transcrição
  • Pedir para "baixar transcrição do YouTube"
  • Quiser "obter legendas" ou "obter ocultação" de um vídeo
  • Pedir para "transcrever um vídeo do YouTube"
  • Precisar do conteúdo textual de um vídeo do YouTube

Como Funciona

Ordem de Prioridade:

  1. Verificar se o yt-dlp está instalado - instalar se necessário
  2. Listar legendas disponíveis - ver o que está realmente disponível
  3. Tentar legendas manuais primeiro (--write-sub) - maior qualidade
  4. Recorrer às automáticas (--write-auto-sub) - geralmente disponíveis
  5. Último recurso: transcrição com Whisper - se não houver legendas (requer confirmação do usuário)
  6. Confirmar o download e mostrar ao usuário onde o arquivo foi salvo
  7. Opcionalmente limpar o formato VTT se o usuário quiser texto simples

Verificação de Instalação

IMPORTANTE: Sempre verifique primeiro se o yt-dlp está instalado:

which yt-dlp || command -v yt-dlp

Se Não Estiver Instalado

Tente a instalação automática com base no sistema:

macOS (Homebrew):

brew install yt-dlp

Linux (apt/Debian/Ubuntu):

sudo apt update && sudo apt install -y yt-dlp

Alternativa (pip - funciona em todos os sistemas):

pip3 install yt-dlp
# ou
python3 -m pip install yt-dlp

Se a instalação falhar: Informe ao usuário que ele precisa instalar o yt-dlp manualmente e forneça as instruções de instalação em https://github.com/yt-dlp/yt-dlp#installation

Verificar Legendas Disponíveis

SEMPRE faça isso primeiro antes de tentar baixar:

yt-dlp --list-subs "YOUTUBE_URL"

Isso mostra quais tipos de legenda estão disponíveis sem baixar nada. Procure por:

  • Legendas manuais (melhor qualidade)
  • Legendas automáticas (geralmente disponíveis)
  • Idiomas disponíveis

Estratégia de Download

Opção 1: Legendas Manuais (Preferida)

Tente primeiro - maior qualidade, criadas por humanos:

yt-dlp --write-sub --skip-download --output "OUTPUT_NAME" "YOUTUBE_URL"

Opção 2: Legendas Automáticas (Alternativa)

Se as legendas manuais não estiverem disponíveis:

yt-dlp --write-auto-sub --skip-download --output "OUTPUT_NAME" "YOUTUBE_URL"

Ambos os comandos criam um arquivo .vtt (formato WebVTT).

Opção 3: Transcrição com Whisper (Último Recurso)

USE apenas se tanto as legendas manuais quanto as automáticas não estiverem disponíveis.

Passo 1: Mostrar Tamanho do Arquivo e Pedir Confirmação

# Obter estimativa de tamanho do arquivo de áudio
yt-dlp --print "%(filesize,filesize_approx)s" -f "bestaudio" "YOUTUBE_URL"

# Ou obter duração para estimar
yt-dlp --print "%(duration)s %(title)s" "YOUTUBE_URL"

IMPORTANTE: Mostre o tamanho do arquivo ao usuário e pergunte: "Nenhuma legenda disponível. Posso baixar o áudio (aproximadamente X MB) e transcrevê-lo usando Whisper. Deseja prosseguir?"

Aguarde a confirmação do usuário antes de continuar.

Passo 2: Verificar Instalação do Whisper

command -v whisper

Se não estiver instalado, pergunte ao usuário: "Whisper não está instalado. Instalar com pip install openai-whisper (requer ~1-3GB para modelos)? Esta é uma instalação única."

Aguarde a confirmação do usuário antes de instalar.

Instale se aprovado:

pip3 install openai-whisper

Passo 3: Baixar Apenas o Áudio

yt-dlp -x --audio-format mp3 --output "audio_%(id)s.%(ext)s" "YOUTUBE_URL"

Passo 4: Transcrever com Whisper

# Detecção automática de idioma (recomendado)
whisper audio_VIDEO_ID.mp3 --model base --output_format vtt

# Ou especifique o idioma se souber
whisper audio_VIDEO_ID.mp3 --model base --language en --output_format vtt

Opções de Modelo (use base por enquanto):

  • tiny - mais rápido, menos preciso (~1GB)
  • base - bom equilíbrio (~1GB) ← USE ESTE
  • small - melhor precisão (~2GB)
  • medium - muito bom (~5GB)
  • large - melhor precisão (~10GB)

Passo 5: Limpeza

Após a transcrição, pergunte ao usuário: "Transcrição concluída! Deseja que eu exclua o arquivo de áudio para economizar espaço?"

Se sim:

rm audio_VIDEO_ID.mp3

Obtendo Informações do Vídeo

Extrair Título do Vídeo (para o nome do arquivo)

yt-dlp --print "%(title)s" "YOUTUBE_URL"

Use isso para criar nomes de arquivos significativos com base no título do vídeo. Limpe o título para compatibilidade com o sistema de arquivos:

  • Substitua / por -
  • Substitua caracteres especiais que possam causar problemas
  • Considere usar versão sanitizada: $(yt-dlp --print "%(title)s" "URL" | tr '/' '-' | tr ':' '-')

Pós-Processamento

Converter para Texto Simples (Recomendado)

Os arquivos VTT gerados automaticamente pelo YouTube contêm linhas duplicadas porque as legendas são exibidas progressivamente com timestamps sobrepostos. Sempre remova duplicatas ao converter para texto simples, preservando a ordem original de fala.

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

Pós-Processamento Completo com Título do Vídeo

# Obter título do vídeo
VIDEO_TITLE=$(yt-dlp --print "%(title)s" "YOUTUBE_URL" | tr '/' '_' | tr ':' '-' | tr '?' '' | tr '"' '')

# Encontrar o arquivo VTT
VTT_FILE=$(ls *.vtt | head -n 1)

# Converter com desduplicação
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 "✓ Salvo em: ${VIDEO_TITLE}.txt"

# Limpar arquivo VTT
rm "$VTT_FILE"
echo "✓ Arquivo VTT temporário limpo"

Formatos de Saída

  • Formato VTT (.vtt): Inclui timestamps e formatação, bom para players de vídeo
  • Texto Simples (.txt): Apenas o conteúdo textual, bom para leitura ou análise

Dicas

  • O nome do arquivo será {output_name}.{language_code}.vtt (ex.: transcript.en.vtt)
  • A maioria dos vídeos do YouTube tem legendas automáticas em inglês
  • Alguns vídeos podem ter múltiplas opções de idioma
  • Se as legendas automáticas não estiverem disponíveis, tente --write-sub para legendas manuais

Exemplo de Fluxo de Trabalho Completo

VIDEO_URL="https://www.youtube.com/watch?v=dQw4w9WgXcQ"

# Obter título do vídeo para o nome do arquivo
VIDEO_TITLE=$(yt-dlp --print "%(title)s" "$VIDEO_URL" | tr '/' '_' | tr ':' '-' | tr '?' '' | tr '"' '')
OUTPUT_NAME="transcript_temp"

# ============================================
# PASSO 1: Verificar se o yt-dlp está instalado
# ============================================
if ! command -v yt-dlp &> /dev/null; then
    echo "yt-dlp não encontrado, tentando 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

# ============================================
# PASSO 2: Listar legendas disponíveis
# ============================================
echo "Verificando legendas disponíveis..."
yt-dlp --list-subs "$VIDEO_URL"

# ============================================
# PASSO 3: Tentar legendas manuais primeiro
# ============================================
echo "Tentando baixar legendas manuais..."
if yt-dlp --write-sub --skip-download --output "$OUTPUT_NAME" "$VIDEO_URL" 2>/dev/null; then
    echo "✓ Legendas manuais baixadas com sucesso!"
    ls -lh ${OUTPUT_NAME}.*
else
    # ============================================
    # PASSO 4: Recorrer às automáticas
    # ============================================
    echo "Legendas manuais não disponíveis. Tentando automáticas..."
    if yt-dlp --write-auto-sub --skip-download --output "$OUTPUT_NAME" "$VIDEO_URL" 2>/dev/null; then
        echo "✓ Legendas automáticas baixadas com sucesso!"
        ls -lh ${OUTPUT_NAME}.*
    else
        # ============================================
        # PASSO 5: Último recurso - Transcrição Whisper
        # ============================================
        echo "⚠ Nenhuma legenda disponível para este vídeo."

        # Obter tamanho do arquivo
        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 "Vídeo: $TITLE"
        echo "Duração: $((DURATION / 60)) minutos"
        echo "Tamanho do áudio: ~$((FILE_SIZE / 1024 / 1024)) MB"
        echo ""
        echo "Deseja baixar e transcrever com Whisper? (s/n)"
        read -r RESPONSE

        if [[ "$RESPONSE" =~ ^[Ss]$ ]]; then
            # Verificar Whisper
            if ! command -v whisper &> /dev/null; then
                echo "Whisper não instalado. Instalar agora? (requer ~1-3GB) (s/n)"
                read -r INSTALL_RESPONSE
                if [[ "$INSTALL_RESPONSE" =~ ^[Ss]$ ]]; then
                    pip3 install openai-whisper
                else
                    echo "Não é possível prosseguir sem Whisper. Saindo."
                    exit 1
                fi
            fi

            # Baixar áudio
            echo "Baixando áudio..."
            yt-dlp -x --audio-format mp3 --output "audio_%(id)s.%(ext)s" "$VIDEO_URL"

            # Obter o nome real do arquivo de áudio
            AUDIO_FILE=$(ls audio_*.mp3 | head -n 1)

            # Transcrever
            echo "Transcrevendo com Whisper (isso pode levar alguns minutos)..."
            whisper "$AUDIO_FILE" --model base --output_format vtt

            # Limpeza
            echo "Transcrição concluída! Excluir arquivo de áudio? (s/n)"
            read -r CLEANUP_RESPONSE
            if [[ "$CLEANUP_RESPONSE" =~ ^[Ss]$ ]]; then
                rm "$AUDIO_FILE"
                echo "Arquivo de áudio excluído."
            fi

            ls -lh *.vtt
        else
            echo "Transcrição cancelada."
            exit 0
        fi
    fi
fi

# ============================================
# PASSO 6: Converter para texto simples legível com desduplicação
# ============================================
VTT_FILE=$(ls ${OUTPUT_NAME}*.vtt 2>/dev/null || ls *.vtt | head -n 1)
if [ -f "$VTT_FILE" ]; then
    echo "Convertendo para formato legível e removendo duplicatas..."
    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 "✓ Salvo em: ${VIDEO_TITLE}.txt"

    # Limpar arquivo VTT temporário
    rm "$VTT_FILE"
    echo "✓ Arquivo VTT temporário limpo"
else
    echo "⚠ Nenhum arquivo VTT encontrado para converter"
fi

echo "✓ Completo!"

Nota: Este fluxo de trabalho completo lida com todos os cenários com verificação de erro adequada e prompts ao usuário em cada ponto de decisão.

Tratamento de Erros

Problemas Comuns e Soluções:

1. yt-dlp não instalado

  • Tentar instalação automática baseada no sistema (Homebrew/apt/pip)
  • Se a instalação falhar, fornecer link para instalação manual
  • Verificar a instalação antes de prosseguir

2. Nenhuma legenda disponível

  • Listar legendas disponíveis primeiro para confirmar
  • Tentar tanto --write-sub quanto --write-auto-sub
  • Se ambos falharem, oferecer opção de transcrição com Whisper
  • Mostrar tamanho do arquivo e pedir confirmação do usuário antes de baixar áudio

3. Vídeo inválido ou privado

  • Verificar se a URL está no formato correto: https://www.youtube.com/watch?v=VIDEO_ID
  • Alguns vídeos podem ser privados, com restrição de idade ou bloqueados geograficamente
  • Informar ao usuário o erro específico do yt-dlp

4. Instalação do Whisper falha

  • Pode exigir dependências do sistema (ffmpeg, rust)
  • Fornecer alternativa: "Instale manualmente com: pip3 install openai-whisper"
  • Verificar espaço em disco disponível (modelos exigem 1-10GB dependendo do tamanho)

5. Download interrompido ou falhou

  • Verificar conexão com a internet
  • Verificar espaço em disco suficiente
  • Tentar novamente com --no-check-certificate se ocorrerem problemas de SSL

6. Múltiplos idiomas de legenda

  • Por padrão, o yt-dlp baixa todos os idiomas disponíveis
  • Pode especificar com --sub-langs en para apenas inglês
  • Listar disponíveis com --list-subs primeiro

Melhores Práticas:

  • ✅ Sempre verificar o que está disponível antes de tentar o download (--list-subs)
  • ✅ Verificar sucesso em cada etapa antes de prosseguir
  • ✅ Perguntar ao usuário antes de downloads grandes (arquivos de áudio, modelos Whisper)
  • ✅ Limpar arquivos temporários após o processamento
  • ✅ Fornecer feedback claro sobre o que está acontecendo em cada etapa
  • ✅ Lidar com erros graciosamente com mensagens úteis

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.

Habilidades Relacionadas