Communitygithub.com

Baixar Vídeos do YouTube e Streams HLS

Baixe vídeos do YouTube e streams HLS (m3u8) de plataformas como Mux, Vimeo, etc. usando yt-dlp e ffmpeg. Use esta habilidade quando os usuários solicitarem download de vídeos, extração de áudio, manipulação de conteúdo protegido com cabeçalhos de autenticação ou solução de problemas de download como falhas de extração nsig, erros 403 ou problemas de extração de cookies.

O que é Baixar Vídeos do YouTube e Streams HLS?

Esta habilidade fornece um fluxo de trabalho completo e confiável para download de vídeos do YouTube (até 4K) e streams HLS de plataformas como Mux e Vimeo, utilizando yt-dlp e ffmpeg. Ela aborda cenários comuns de falha, como disponibilidade limitada de formatos (apenas 360p) e erros de extração nsig, oferecendo soluções como a instalação de um provedor de token PO, uso de cookies do navegador ou fallback para o cliente Android. Para streams HLS protegidos, a habilidade instrui sobre como obter URLs de manifesto, identificar cabeçalhos de autenticação necessários (Referer, Origin, User-Agent) e fazer o download com ffmpeg usando o parâmetro `-headers`. Um script auxiliar `download_video.py` está incluído para simplificar o download básico do YouTube, e a documentação detalhada abrange conversão de WebM para MP4, download de playlists, legendas e solução de problemas de rede. A habilidade é compatível com macOS e sistemas Linux com yt-dlp e ffmpeg instalados.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/IGTA-Tech/claude-skills-research/tree/HEAD/claude-code-skills/youtube-downloader

Perguntar na sua IA favorita

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

Documentação

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:

  1. Atualize yt-dlp: brew upgrade yt-dlp
  2. Instale o provedor de token PO (veja Passo 1 acima)
  3. 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:

  1. Atualize yt-dlp para a versão mais recente
  2. Instale o provedor de token PO
  3. 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ção360p720p1080p1440p4K
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:

  1. Abra DevTools do navegador → Aba Network
  2. Reproduza o vídeo
  3. Filtre por "m3u8" para encontrar as URLs da lista de reprodução
  4. 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:

  1. 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
  1. 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
  1. 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:

  1. Verifique se o cabeçalho Referer corresponde ao site de origem do vídeo
  2. Verifique se cabeçalhos adicionais (Origin, User-Agent) são necessários
  3. 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:

  1. Obtenha URLs novas do DevTools do navegador
  2. Baixe imediatamente após obter as URLs
  3. 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

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

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.

IGTA-Tech/claude-skills-research

Download YouTube video transcripts when user provides a YouTube URL or asks to download/get/fetch a transcript from YouTube. Also use when user wants to transcribe or get captions/subtitles from a YouTube video.

Habilidades Relacionadas