YouTube Downloader
Visão Geral
Permite downloads confiáveis de vídeo e áudio do YouTube e plataformas de streaming HLS (Mux, Vimeo, etc.) usando yt-dlp e ffmpeg. Esta skill fornece fluxos de trabalho para:
- Downloads do YouTube (até 4K) usando provedores de token PO ou cookies de 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
Experiência do Usuário Não Técnico (Padrão)
Presuma que o usuário não é técnico. Não peça a ele para executar comandos. Execute tudo você mesmo e relate o progresso em linguagem natural. Evite mencionar ferramentas, a menos que o usuário pergunte.
Fluxo padrão:
- Peça a URL (se não for fornecida).
- Obtenha os metadados do vídeo (título/criador/duração/miniatura) e confirme se correspondem à intenção do usuário.
- Se o yt-dlp for bloqueado com "confirme que você não é um robô", recorra ao YouTube oEmbed para título/criador/miniatura (a duração pode ser desconhecida).
- Ofereça opções simples (vídeo vs. só áudio, qualidade, legendas, local para salvar).
- Prossiga com padrões sensatos se o usuário não especificar:
- Download de vídeo na melhor qualidade
- Saída em MP4 mesclado
- Vídeo único apenas (sem playlists)
- Faça o download e informe o caminho do arquivo final, tamanho e resolução (se for vídeo).
Ofereça opções em termos amigáveis:
- "Baixar o vídeo na melhor qualidade (padrão)"
- "Baixar apenas o áudio (MP3)"
- "Escolher uma qualidade: 1080p / 720p / 480p / 360p"
- "Incluir legendas (se disponíveis)"
- "Salvar na pasta Downloads (padrão) ou me diga outra pasta"
Sempre renderize a miniatura quando disponível:
- Se os metadados incluírem uma URL de miniatura, inclua-a usando a sintaxe de imagem Markdown:
.
Pergunte antes de fazer trabalho extra:
- Confirme downloads de playlists (podem ser grandes).
- Confirme a instalação/atualização de dependências se estiverem faltando.
- Pergunte antes de extrair cookies do navegador.
- Se usar cookies, nunca mencione a quantidade de cookies ou detalhes brutos dos cookies nas respostas ao usuário. Diga "usei sua sessão de login do Chrome".
- Se a verificação for necessária, configure automaticamente um auxiliar de token PO local (nenhuma ação do usuário). Se o Docker estiver ausente ou falhar, não tente instalar o Docker — mude para o provedor de token PO baseado em navegador.
Lembrete legal/segurança (breve):
- Prossiga somente se o usuário tiver os direitos ou permissão para baixar o conteúdo.
Modelo de resposta (use linguagem natural, sem comandos):

Título: …
Canal: …
Duração: …
Posso ajudar você a:
1) Baixar o vídeo (melhor qualidade, MP4)
2) Baixar apenas o áudio (MP3)
3) Escolher uma qualidade específica (1080p/720p/480p/360p)
4) Incluir legendas (se disponíveis)
Onde devo salvar? (Padrão: pasta Downloads)
Se o usuário disser "apenas baixe":
- Prossiga com os padrões e confirme quando o download terminar.
- Se for bloqueado por um erro 403, configure automaticamente o auxiliar de verificação e tente novamente.
SOP de Download Confiável (Interno)
Siga este SOP para evitar falhas e confusões comuns:
- Coloque URLs entre aspas em comandos shell (o zsh trata
?como um glob). Exemplo:'https://www.youtube.com/watch?v=VIDEO_ID'. - Certifique-se de que o proxy esteja ativo tanto para o yt-dlp quanto para os provedores de token PO (HTTP_PROXY/HTTPS_PROXY/ALL_PROXY).
- Se você vir "Faça login para confirmar que você não é um robô", peça permissão e use cookies do navegador. Não prossiga sem cookies.
- Inicie um provedor de token PO antes de baixar (falhe rapidamente se não puder iniciar).
- Use o provedor Docker bgutil quando disponível.
- Se o Docker estiver ausente ou falhar, mude para o provedor WPC baseado em navegador.
- Se cookies estiverem em uso, prefira o cliente player
web_safari. Caso contrário, prefiramwebpara tokens PO. - Mantenha a janela do navegador aberta enquanto o WPC estiver gerando tokens. Certifique-se de que o Chrome possa acessar o YouTube através do mesmo proxy.
- Se você receber "Apenas imagens estão disponíveis" ou "O formato solicitado não está disponível", trate como uma falha de token PO e tente novamente após corrigir o estado do provedor/navegador.
- Se você receber erros de SSL EOF ou fragmento, trate como um problema de proxy/rede. Tente novamente com formatos progressivos e/ou um proxy melhor.
Lista de Verificação de Execução do Agente (Interno)
- Execute
scripts/download_video.py URL --info(adicione--cookies-from-browser chromese a permissão for concedida) para obter metadados e miniatura. - Se os metadados do yt-dlp falharem, use o fallback oEmbed do script para título/criador/miniatura e observe que a duração pode estar indisponível.
- Se uma URL de miniatura estiver presente, renderize-a na resposta com a sintaxe de imagem Markdown.
- Pergunte ao usuário se deseja vídeo ou apenas áudio e (opcionalmente) uma predefinição de qualidade.
- Use um local de salvamento padrão amigável (pasta Downloads), a menos que o usuário especifique uma pasta.
- Para legendas, execute com
--subtitlese o--sub-langsolicitado. - Após o download, informe o nome do arquivo, tamanho e resolução (se for vídeo) em linguagem natural.
- Se o download falhar com erros 403/fragmento, tente novamente uma vez com formatos progressivos não-m3u8.
- Se aparecer "Faça login para confirmar que você não é um robô", solicite acesso aos cookies e tente novamente com cookies +
web_safari. - Se aparecer "Apenas imagens estão disponíveis", trate como falha de token PO e tente novamente após corrigir o estado do provedor/navegador.
- Inicie o provedor de token PO antes dos downloads (
--auto-po-tokenpadrão). Falhe rapidamente se não puder iniciar. - Se o provedor baseado em Docker falhar (comum na China), caia automaticamente para o provedor WPC baseado em navegador (pode abrir brevemente uma janela do navegador).
- Se o provedor WPC for usado, mantenha a janela do navegador aberta até o download começar. Se o navegador não iniciar, defina o caminho do Chrome explicitamente.
- Se o provedor de token PO expirar, reinicie-o uma vez e tente novamente.
- Se um proxy de sistema estiver configurado, passe-o para o contêiner do provedor. Se o proxy apontar para 127.0.0.1/localhost, reescreva-o para
host.docker.internalpara o Docker.
Quando Usar Esta Skill
Esta skill 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 o 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 a Instalação do yt-dlp (Execute você mesmo)
which yt-dlp
yt-dlp --version
Se não estiver instalado ou estiver 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 o Acesso Atual à Qualidade (Execute você mesmo)
Antes de baixar, verifique os formatos disponíveis:
yt-dlp -F "https://youtu.be/VIDEO_ID"
Se apenas o formato 18 (360p) aparecer: A configuração do provedor de token PO é necessária para acesso de alta qualidade.
Fluxo de Trabalho de Download de Alta Qualidade
Etapa 1: Instalar o 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:
# Encontre o caminho do Python do yt-dlp (interpretador usado pelo yt-dlp)
head -1 $(which yt-dlp)
# Instale o plugin usando o interpretador da linha acima
<YTDLP_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.
Etapa 2: Baixar com a Melhor Qualidade
Depois que o provedor de token PO estiver instalado:
# Baixar a melhor qualidade até 1080p
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
# Baixar a melhor qualidade disponível (4K se disponível)
yt-dlp -f "bestvideo+bestaudio/best" "VIDEO_URL"
Etapa 3: Verificar a Qualidade do Download
# Verificar a 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. Requisitos:
- Deve estar logado no YouTube no navegador especificado.
- O navegador e o yt-dlp devem usar o mesmo IP/proxy.
- Não use o cliente Android com cookies (o cliente Android não suporta cookies).
Tarefas Comuns
Download Apenas de Áudio (Execute você mesmo)
Extraia o áudio como MP3:
yt-dlp -x --audio-format mp3 "VIDEO_URL"
Diretório de Saída Personalizado (Execute você mesmo)
yt-dlp -P ~/Downloads/YouTube "VIDEO_URL"
Baixar com Legendas (Execute você mesmo)
yt-dlp --write-subs --sub-lang en "VIDEO_URL"
Download de Playlist (Execute você mesmo)
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "PLAYLIST_URL"
Converter WebM para MP4 (Execute você mesmo)
Downloads de alta qualidade do YouTube geralmente usam o formato WebM (codec VP9). Converta para MP4 para maior compatibilidade:
# Verificar se o 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 o codec de vídeo H.264 (amplamente compatível)-preset medium: Equilíbrio entre velocidade de codificação e tamanho do arquivo-crf 23: Fator de taxa constante para qualidade (faixa 18-28, menor = melhor qualidade)-c:a aac: Usa o codec de áudio AAC-b:a 128k: Taxa de bits de áudio de 128 kbps
Dica: A conversão mantém a resolução de 1080p e fornece ~6x a 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 o yt-dlp:
brew upgrade yt-dlp - Instale o provedor de token PO (consulte a Etapa 1 acima)
- Ou use o método de cookies do navegador
Faça Login para Confirmar que Você Não é um Robô
Causa: O YouTube exige autenticação para prosseguir.
Solução:
- Solicite permissão e use cookies do navegador (
--cookies-from-browser chrome). - Certifique-se de que o navegador e o yt-dlp usem o mesmo IP/proxy.
- Tente novamente com o cliente
web_safarise necessário.
Apenas Imagens Disponíveis / Formato Solicitado Não Disponível
Causa: Tokens PO não aplicados ou falha na verificação do provedor/navegador.
Solução:
- Verifique se o provedor de token PO está em execução antes do download.
- Mantenha a janela do navegador aberta se estiver usando WPC.
- Se cookies estiverem em uso, prefira o cliente
web_safarie tente novamente.
Falha na Extração nsig
Sintomas:
WARNING: [youtube] nsig extraction failed: Some formats may be missing
Solução:
- Atualize o yt-dlp para a versão mais recente
- Instale o provedor de token PO
- Se ainda falhar e os tokens PO estiverem desabilitados, use o cliente Android:
yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"
Erros SSL EOF / Fragmento
Causa: Instabilidade de proxy ou rede.
Solução:
- Tente novamente com formatos progressivos (não-m3u8).
- Mude para um proxy/nó mais estável.
- Evite fechar a janela do navegador de token PO durante o download.
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 a conclusão
- O yt-dlp tenta novamente automaticamente em caso de 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 Scripts Inclusos
scripts/download_video.py
Use este wrapper de conveniência para iniciar automaticamente um provedor de token PO por padrão para downloads de alta qualidade. Use você mesmo e relate os resultados ao usuário sem pedir que ele execute comandos.
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--output-template- Modelo de nome de arquivo de saída (sintaxe yt-dlp)-f, --format- Especificação de formato-q, --quality- Predefinição de qualidade (best, 1080p, 720p, 480p, 360p, worst). Padrão: best (ignorado para--audio-only)-a, --audio-only- Extrair áudio como MP3--subtitles- Baixar legendas se disponíveis--sub-lang- Idiomas das legendas (separados por vírgula, padrão: en)--cookies-from-browser- Carregar cookies de um navegador (ex.: chrome, firefox)--cookies-file- Carregar cookies de um arquivo cookies.txt--player-client- Usar um cliente player específico do YouTube (ex.: web_safari)--auto-po-token- Iniciar automaticamente o provedor de token PO (padrão; usa Docker se disponível, caso contrário, muda para o provedor baseado em navegador)--no-auto-po-token- Desabilitar a configuração automática de token PO--proxy- URL do proxy para yt-dlp e o provedor de token PO (ex.: http://127.0.0.1:1082)--wpc-browser-path- Caminho do executável do navegador para o provedor WPC-F, --list-formats- Listar formatos disponíveis--merge-format- Contêiner de saída de mesclagem (ex.: mp4, mkv). Padrão: mp4--playlist- Permitir downloads de playlist (padrão: apenas vídeo único)--info- Imprimir título/criador/duração/miniatura e sair--no-android-client- Desabilitar fallback do cliente Android
Nota: Use o cliente Android apenas quando os tokens PO estiverem desabilitados. Mantenha os tokens PO habilitados para alta qualidade.
Expectativas de Qualidade
| Configuração | 360p | 720p | 1080p | 1440p | 4K |
|---|---|---|---|---|---|
| Token PO automático (padrão) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Apenas cliente Android | ✓ | ✗ | ✗ | ✗ | ✗ |
| Provedor de token PO (manual) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Cookies do navegador | ✓ | ✓ | ✓ | ✓ | ✓ |
...
[truncado para tradução]