YouTube Downloader
Visão Geral
Permite download confiável de vídeos e áudio do YouTube e plataformas de streaming HLS (Mux, Vimeo, etc.) usando yt-dlp e ffmpeg. Esta habilidade fornece fluxos de trabalho para:
- Downloads do YouTube (até 4K) usando provedores de token PO ou cookies do navegador
- Downloads de streams HLS com cabeçalhos de autenticação
- Manipulação de conteúdo protegido e solução de problemas comuns de download
Quando Usar Esta Habilidade
Esta habilidade deve ser invocada quando os usuários:
- Solicitarem download de vídeos ou playlists do YouTube
- Quiserem extrair áudio de vídeos do YouTube
- Enfrentarem falhas de download do yt-dlp ou disponibilidade limitada de formatos
- Precisarem de ajuda com seleção de formato ou opções de qualidade
- Relatarem apenas formatos de baixa qualidade (360p) disponíveis
- Perguntarem sobre download de conteúdo do YouTube em qualidade específica (1080p, 4K, etc.)
- Precisarem converter vídeos WebM baixados para formato MP4 para maior compatibilidade
- Solicitarem download de streams HLS (m3u8) de plataformas como Mux, Vimeo ou outros serviços de streaming
- Precisarem baixar streams protegidos que exigem cabeçalhos de autenticação
Pré-requisitos
1. Verificar instalação do yt-dlp
which yt-dlp
yt-dlp --version
Se não instalado ou desatualizado (< 2025.10.22):
brew upgrade yt-dlp # macOS
# ou
pip install --upgrade yt-dlp # Multiplataforma
Crítico: Versões desatualizadas do yt-dlp causam falhas de extração nsig e formatos ausentes.
2. Verificar Acesso de Qualidade Atual
Antes de baixar, verifique os formatos disponíveis:
yt-dlp -F "https://youtu.be/VIDEO_ID"
Se apenas o formato 18 (360p) aparecer: Configuração do provedor de token PO é necessária para acesso de alta qualidade.
Fluxo de Trabalho de Download de Alta Qualidade
Passo 1: Instalar Provedor de Token PO (Configuração Única)
Para acesso a 1080p/1440p/4K, instale um plugin provedor de token PO no ambiente Python do yt-dlp:
# Encontrar o caminho do Python do yt-dlp
head -1 $(which yt-dlp)
# Instalar plugin (ajuste o caminho para corresponder à versão do yt-dlp)
/opt/homebrew/Cellar/yt-dlp/$(yt-dlp --version)/libexec/bin/python -m pip install bgutil-ytdlp-pot-provider
Verificação: Execute yt-dlp -F "VIDEO_URL" novamente. Procure pelos formatos 137 (1080p), 271 (1440p) ou 313 (4K).
Consulte references/po-token-setup.md para instruções detalhadas de configuração e solução de problemas.
Passo 2: Baixar com Melhor Qualidade
Assim que o provedor de token PO estiver instalado:
# Baixar melhor qualidade até 1080p
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
# Baixar melhor qualidade disponível (4K se disponível)
yt-dlp -f "bestvideo+bestaudio/best" "VIDEO_URL"
Passo 3: Verificar Qualidade do Download
# Verificar resolução do vídeo
ffprobe -v error -select_streams v:0 -show_entries stream=width,height,codec_name -of default=noprint_wrappers=1 video.mp4
Saída esperada para 1080p:
codec_name=vp9
width=1920
height=1080
Alternativa: Método de Cookies do Navegador
Se a configuração do provedor de token PO for problemática, use cookies do navegador:
# Firefox
yt-dlp --cookies-from-browser firefox -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
# Chrome
yt-dlp --cookies-from-browser chrome -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
Benefícios: Acesso a conteúdo com restrição de idade e exclusivo para membros. Requisito: Deve estar logado no YouTube no navegador especificado.
Tarefas Comuns
Download Apenas de Áudio
Extrair áudio como MP3:
yt-dlp -x --audio-format mp3 "VIDEO_URL"
Diretório de Saída Personalizado
yt-dlp -P ~/Downloads/YouTube "VIDEO_URL"
Baixar com Legendas
yt-dlp --write-subs --sub-lang en "VIDEO_URL"
Download de Playlist
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "PLAYLIST_URL"
Converter WebM para MP4
Downloads de alta qualidade do YouTube geralmente usam o formato WebM (codec VP9). Converta para MP4 para maior compatibilidade:
# Verificar se ffmpeg está instalado
which ffmpeg || brew install ffmpeg # macOS
# Converter WebM para MP4 com boas configurações de qualidade
ffmpeg -i "video.webm" -c:v libx264 -preset medium -crf 23 -c:a aac -b:a 128k "video.mp4"
Parâmetros explicados:
-c:v libx264: Usa codec de vídeo H.264 (amplamente compatível)-preset medium: Equilíbrio entre velocidade de codificação e tamanho do arquivo-crf 23: Constant Rate Factor para qualidade (intervalo 18-28, menor = melhor qualidade)-c:a aac: Usa codec de áudio AAC-b:a 128k: Taxa de bits de áudio 128 kbps
Dica: A conversão mantém a resolução 1080p e fornece aproximadamente 6x de velocidade de codificação em hardware moderno.
Referência Rápida de Solução de Problemas
Apenas 360p Disponível (Formato 18)
Causa: Provedor de token PO ausente ou yt-dlp desatualizado.
Solução:
- Atualize yt-dlp:
brew upgrade yt-dlp - Instale o provedor de token PO (veja Passo 1 acima)
- Ou use o método de cookies do navegador
Falha na Extração nsig
Sintomas:
WARNING: [youtube] nsig extraction failed: Some formats may be missing
Solução:
- Atualize yt-dlp para a versão mais recente
- Instale o provedor de token PO
- Se ainda falhar, use o cliente Android:
yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"
Downloads Lentos ou Erros de Rede
Para usuários na China ou atrás de proxies restritivos:
- Os downloads podem ser lentos devido às condições de rede
- Permita tempo suficiente para conclusão
- yt-dlp tenta novamente automaticamente em falhas transitórias
Aviso de Token PO (Inofensivo)
WARNING: android client https formats require a GVS PO Token
Ação: Ignore se o download for bem-sucedido. Isso indica que o cliente Android tem acesso limitado a formatos sem tokens PO.
Referência de Script Incluso
scripts/download_video.py
Um wrapper de conveniência que aplica a solução alternativa do cliente Android por padrão:
Uso básico:
scripts/download_video.py "VIDEO_URL"
Argumentos:
url- URL do vídeo do YouTube (obrigatório)-o, --output-dir- Diretório de saída-f, --format- Especificação de formato-a, --audio-only- Extrair áudio como MP3-F, --list-formats- Listar formatos disponíveis--no-android-client- Desabilitar solução alternativa do cliente Android
Nota: Este script usa o cliente Android (apenas 360p sem tokens PO). Para alta qualidade, use yt-dlp diretamente com o provedor de token PO.
Expectativas de Qualidade
| Configuração | 360p | 720p | 1080p | 1440p | 4K |
|---|---|---|---|---|---|
| Sem configuração (padrão) | ✗ | ✗ | ✗ | ✗ | ✗ |
| Apenas cliente Android | ✓ | ✗ | ✗ | ✗ | ✗ |
| Provedor de token PO | ✓ | ✓ | ✓ | ✓ | ✓ |
| Cookies do navegador | ✓ | ✓ | ✓ | ✓ | ✓ |
Downloads de Streams HLS (m3u8)
Para plataformas de streaming como Mux, Vimeo e outros serviços baseados em HLS, use ffmpeg como ferramenta principal. Esses streams geralmente exigem cabeçalhos de autenticação que o yt-dlp pode não manipular corretamente.
Identificando Streams HLS
Streams HLS usam arquivos de lista de reprodução .m3u8:
- Lista de reprodução mestre: Lista múltiplas opções de qualidade
- Lista de reprodução de rendição: Contém URLs reais de segmentos de vídeo/áudio
Fluxo de Trabalho de Download
Passo 1: Obter a URL do Stream
Obtenha a URL m3u8 da fonte do vídeo. Para streams protegidos:
- Abra DevTools do navegador → Aba Network
- Reproduza o vídeo
- Filtre por "m3u8" para encontrar as URLs da lista de reprodução
- Copie a URL de rendição (geralmente contém informações de qualidade como "rendition.m3u8")
Passo 2: Identificar Cabeçalhos Necessários
Muitas CDNs exigem cabeçalhos de autenticação:
- Referer: Site de origem (por exemplo,
https://maven.com/) - Origin: Mesmo que Referer para CORS
- User-Agent: Identificação do navegador
Verifique na aba Network quais cabeçalhos o navegador envia.
Passo 3: Baixar com ffmpeg
Use ffmpeg com o sinalizador -headers para streams protegidos:
ffmpeg -headers "Referer: https://example.com/" \
-protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
-i "https://cdn.example.com/path/rendition.m3u8?params" \
-c copy -bsf:a aac_adtstoasc \
output.mp4
Parâmetros principais:
-headers: Definir cabeçalhos HTTP (crítico para autenticação)-protocol_whitelist: Habilitar protocolos necessários para HLS-c copy: Cópia de stream (sem re-codificação, mais rápido)-bsf:a aac_adtstoasc: Corrigir compatibilidade de áudio AAC
Padrões comuns de cabeçalho:
# Cabeçalho único
-headers "Referer: https://example.com/"
# Múltiplos cabeçalhos
-headers "Referer: https://example.com/" \
-headers "User-Agent: Mozilla/5.0..."
# Sintaxe alternativa
-headers $'Referer: https://example.com/\r\nUser-Agent: Mozilla/5.0...'
Manipulando Streams Separados de Áudio/Vídeo
Algumas plataformas (como Mux) entregam áudio e vídeo separadamente:
- Baixar stream de áudio:
ffmpeg -headers "Referer: https://example.com/" \
-protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
-i "https://cdn.example.com/audio/rendition.m3u8" \
-c copy audio.m4a
- Baixar stream de vídeo:
ffmpeg -headers "Referer: https://example.com/" \
-protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
-i "https://cdn.example.com/video/rendition.m3u8" \
-c copy video.mp4
- Mesclar streams:
ffmpeg -i video.mp4 -i audio.m4a -c copy merged.mp4
Solução de Problemas de Downloads HLS
Erros 403 Proibido
Causa: Cabeçalhos de autenticação ausentes ou incorretos.
Solução:
- Verifique se o cabeçalho Referer corresponde ao site de origem do vídeo
- Verifique se cabeçalhos adicionais (Origin, User-Agent) são necessários
- Certifique-se de que a URL m3u8 inclui todos os parâmetros de consulta do navegador
yt-dlp Travado na Extração de Cookies
Sintoma: Extracting cookies from chrome trava indefinidamente.
Solução: Use ffmpeg diretamente em vez de yt-dlp para streams HLS.
Protocolo Não na Lista de Permissões
Erro: Protocol 'https' not on whitelist 'file,crypto,data'
Solução: Adicione -protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy
Segmentos Vazios ou Nenhum Stream
Causa: Assinaturas expiradas nas URLs m3u8.
Solução:
- Obtenha URLs novas do DevTools do navegador
- Baixe imediatamente após obter as URLs
- Procure por URLs de rendição com parâmetros de assinatura atualizados
Dicas de Desempenho
- Os downloads HLS normalmente são executados a 10-15x a velocidade em tempo real
- Sem re-codificação com
-c copy(mais rápido) - Monitore o download com exibição de progresso em tempo real
- Use caminhos de saída absolutos para evitar confusão de diretórios
Leitura Adicional
- Configuração de Token PO: Consulte
references/po-token-setup.mdpara instalação detalhada e solução de problemas - Documentação do yt-dlp: https://github.com/yt-dlp/yt-dlp
- Guia de Seleção de Formato: https://github.com/yt-dlp/yt-dlp#format-selection