Downloads básicos
Sem opção nenhuma, o yt-dlp escolhe a melhor combinação que consegue juntar e nomeia o arquivo pelo título. Surpreendentemente, muitas vezes esse é o comando certo.
yt-dlp URL
Antes de baixar algo grande, vale a pena ver o que realmente está disponível. Isto imprime a tabela de formatos e encerra sem baixar nada.
yt-dlp -F URL
A coluna da esquerda dessa tabela é o id do formato, que você pode então pedir diretamente. Dois ids unidos por + significam "baixe os dois e junte".
yt-dlp -f 137+140 URL
Qualidade e seleção de formato
Ids de formato fixos quebram assim que um site muda sua escada de codificação. Uma expressão seletora é a versão duradoura: peça as propriedades que você quer e deixe o yt-dlp achar a melhor correspondência.
yt-dlp -f "bv*[height<=1080]+ba/b[height<=1080]" URL
Leia assim: o melhor fluxo de vídeo com no máximo 1080 de altura mais o melhor áudio e, se esse par não existir, o melhor arquivo único com no máximo 1080 de altura. É esse recuo depois da barra que impede o comando de falhar em sites que só publicam fluxos progressivos.
Juntar dois fluxos produz um contêiner que o yt-dlp precisa escolher. MP4 toca em todo lugar; MKV aceita qualquer coisa, e isso importa assim que legendas e capítulos entram na história.
yt-dlp -f "bv*+ba" --merge-output-format mp4 URL
Para expressar uma preferência em vez de um limite rígido, ordene em vez de filtrar. Isto prefere 1080p e MP4 mas ainda baixa alguma coisa quando nenhum dos dois está disponível.
yt-dlp -S "res:1080,ext:mp4" URL
Áudio e MP3
Extrair áudio precisa do ffmpeg — é de longe o motivo mais comum para o comando abaixo falhar numa instalação recém-feita.
yt-dlp -x --audio-format mp3 URL
Acrescentar capa e tags custa mais duas flags e faz o resultado servir numa biblioteca de música, em vez de virar uma pasta de arquivos anônimos.
yt-dlp -x --audio-format mp3 --audio-quality 0 --embed-thumbnail --embed-metadata URL
--audio-quality 0 é taxa de bits variável no melhor ajuste, não "qualidade zero". Se você precisa de taxa fixa, informe: --audio-quality 320K.
Quando a fonte já é AAC ou Opus, converter para MP3 recodifica e perde qualidade à toa. Manter o original é mais rápido e melhor.
yt-dlp -x --audio-format best URL
Legendas
Legendas embutidas viajam junto com o arquivo; arquivos .srt separados são mais fáceis de editar e de passar adiante.
yt-dlp --embed-subs --sub-langs en URL yt-dlp --write-subs --sub-langs en,vi --convert-subs srt URL
Legendas automáticas são uma chave à parte. Sem ela, um vídeo sem legendas humanas não produz absolutamente nada, e nenhum erro.
yt-dlp --write-auto-subs --sub-langs en --convert-subs srt --skip-download URL
Playlists e canais
Uma URL do YouTube muitas vezes pertence ao mesmo tempo a um vídeo e a uma playlist, e o yt-dlp precisa adivinhar o que você quis dizer. Diga explicitamente.
yt-dlp --no-playlist URL yt-dlp --yes-playlist URL
Para qualquer coisa longa, o arquivo de histórico importa mais do que qualquer outra opção aqui: ele registra o que já foi baixado, de modo que reexecutar continua de onde parou em vez de começar do zero.
yt-dlp --yes-playlist -i \ --download-archive archive.txt \ -o "%(playlist_index)02d - %(title)s.%(ext)s" \ URL
Combinado com -i, um vídeo bloqueado por região ou apagado deixa de abortar os outros duzentos. Para pegar só um trecho, -I aceita intervalos e listas: -I 1:10, -I "1,3,7-10".
Trechos, capítulos e patrocínios
Você pode baixar parte de um vídeo em vez dele inteiro. O asterisco inicial marca um instante de tempo em vez do nome de um capítulo, e as aspas são obrigatórias — o bash expande um * solto contra os seus nomes de arquivo.
yt-dlp --download-sections "*00:01:30-00:03:00" URL
O SponsorBlock usa marcações enviadas pela comunidade para cortar trechos por completo, ou para deixá-los como capítulos que você mesmo pula.
yt-dlp --sponsorblock-remove default URL yt-dlp --sponsorblock-mark all --embed-chapters URL
Nomes de arquivo e pastas
O modelo de saída controla os dois. Uma barra cria um diretório, então um único modelo pode organizar um acervo inteiro.
yt-dlp -o "%(uploader)s/%(upload_date>%Y-%m-%d)s - %(title)s.%(ext)s" URL
Títulos costumam trazer caracteres que alguns sistemas de arquivos rejeitam. --restrict-filenames reduz tudo a ASCII simples, o que compensa para qualquer coisa que vá circular entre máquinas.
Num arquivo .bat do Windows cada % precisa ser duplicado — %%(title)s — ou o interpretador de lote come o modelo antes de o yt-dlp vê-lo. O gerador faz isso por você quando você baixa um .bat.
Erros que você realmente vai encontrar
ffmpeg not found
Tudo que junta, converte, embute ou corta precisa do ffmpeg no seu PATH. Instale e confirme com ffmpeg -version.
Sign in to confirm you are not a bot
Tente --impersonate chrome primeiro, depois --cookies-from-browser. Se os dois falharem, atualize o yt-dlp — essa verificação em particular muda com frequência e a correção costuma sair numa versão em poucos dias.
Unable to extract player response
Quase sempre é um yt-dlp desatualizado. Atualize antes de mexer em qualquer outra coisa: yt-dlp -U, ou o seu gerenciador de pacotes se foi assim que você instalou.
Requested format is not available
Seu seletor não casou com nada. Rode -F para ver o que existe, e prefira uma ordenação (-S) a um filtro rígido, para sempre haver um plano B.
HTTP Error 403
A URL foi assinada para outra sessão ou outra região. Rode de novo com cookies novos, acrescente --impersonate chrome ou tente --geo-bypass.
Manter o yt-dlp em dia
Mais bugs relatados são resolvidos por uma atualização do que por qualquer flag. Se você instalou o binário independente:
yt-dlp -U
Instalado por um gerenciador de pacotes, atualize do mesmo jeito que instalou — o -U vai recusar, e faz bem.