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:
- Verificar se o yt-dlp está instalado - instalar se necessário
- Listar legendas disponíveis - ver o que está realmente disponível
- Tentar legendas manuais primeiro (
--write-sub) - maior qualidade - Recorrer às automáticas (
--write-auto-sub) - geralmente disponíveis - Último recurso: transcrição com Whisper - se não houver legendas (requer confirmação do usuário)
- Confirmar o download e mostrar ao usuário onde o arquivo foi salvo
- 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 ESTEsmall- 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('&', '&').replace('>', '>').replace('<', '<')
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('&', '&').replace('>', '>').replace('<', '<')
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-subpara 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('&', '&').replace('>', '>').replace('<', '<')
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-subquanto--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-certificatese 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 enpara apenas inglês - Listar disponíveis com
--list-subsprimeiro
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