Explorar documentação
Guias
Guia de downloads com foco em Linux, incluindo a instalação nightly, formatos, legendas, conjuntos de dados e coletas que podem ser retomadas.
Nesta página
Instale a base de uso diário
Início com nocturno + Deno + FFmpeg. Use um ambiente virtual de projeto e habilite a personificação do navegador com --impersonate="". A configuração Linux abaixo instala as ferramentas; as alternativas do macOS e do Windows estão nas tabelas.
Ubuntu / Debian exemplo com Python 3.11+. Instalar as ferramentas do sistema, criar um ambiente virtual de projeto, depois instalar o nocturno atual e seus extras.
sudo apt-get update
sudo apt-get install -y python3 python3-venv ffmpeg aria2 curl unzip
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
curl -fsSL https://deno.land/install.sh -o /tmp/install-deno.sh
sh /tmp/install-deno.sh
export PATH="$HOME/.deno/bin:$PATH"
deno --version
python -m yt_dlp --versionCom Homebrew instalado, use-o para Python, Deno, FFmpeg e aria2. Mantenha yt-dlp em seu ambiente de projeto para que o comando de atualização noturna seja o mesmo que no Linux.
brew install python deno ffmpeg aria2
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
deno --version
python -m yt_dlp --versionInstale Python 3.11+, Deno e os executáveis FFmpeg, e abra um novo terminal. Use o intérprete do ambiente diretamente se o PowerShell bloquear a ativação. aria2 é opcional; instale-o separadamente se você usar a receita de download externo.
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -U --pre "yt-dlp[default,curl-cffi]"
deno --version
ffmpeg -version
.\.venv\Scripts\python.exe -m yt_dlp --version| Ferramenta | O que faz | verificação |
|---|---|---|
| Python 3.11+ | Exerce o pacote Python e exemplos nesta série. | python --version |
| Última yt-dlp nocturna + padrão,curl-cffi extras | Extractor do YouTube atual, compatível com o solvente EJS e suporte para a impersonização do navegador. | python -m yt_dlp --version |
| FFmpeg e ffprobe | Mergulhe as correntes, converte áudio, corte clipes e inspeccione os meios de comunicação salvos. | ffmpeg -version / ffprobe -version |
| Deno 2.3+ (necessário neste fluxo de trabalho) | Instale-o em todos os trabalhadores, não apenas sua máquina de desenvolvimento. | deno --version |
Instalar os executables também. [default] fornece os scripts EJS; Deno é separado. FFmpeg e ffprobe também deve estar no PATH do trabalhador.
deno --version
ffmpeg -version
ffprobe -version
python -m pip show yt-dlp yt-dlp-ejs curl-cffi
python -m yt_dlp --list-impersonate-targetspython -m yt_dlp --ignore-config --js-runtimes deno --impersonate="" --verbose \
--simulate "https://www.youtube.com/watch?v=jNQXAC9IVRw"A linha de base de funcionamento do FlashData inclui --impersonate=": permite que curl-cffi escolha uma impressão de impressão do navegador disponível. Isso muda a impressão de impressão da solicitação; não fornece cookies de login, resolve os desafios do JavaScript ou altera o IP de saída. Se esta opção retarda uma rota de trabalho ou introduza erros, repita o mesmo teste de vídeo sem ele e mantenha a configuração de trabalho.
Verifique a libertação antes de colocá-la em um trabalhador
Obtenha executáveis da página de lançamento do projeto oficial, ou instale o pacote Python da sua fonte de pacote publicada. Se você descarregar um binário independente, compare seu SHA-256 com o nome de filename correspondente no SHA2-256SUMS desse lançamento. Recordar a libertação e o checksum com a imagem do seu trabalhador para que você possa identificar exatamente o que foi.
sha256sum yt-dlpshasum -a 256 yt-dlp_macosGet-FileHash -Algorithm SHA256 .\yt-dlp.exeUma comparação de checksum é útil apenas quando o valor esperado vem da versão confiável, não o mesmo espelho desconhecido como o executável. Se o software de segurança flagrar um arquivo, investigue a sua fonte e relate antes de fazer uma exceção. A disponibilidade de código aberto não é uma evidência de que todos os plugins binários ou terceiros baixados são seguros.
Tratar os arquivos de configuração compartilhados como código para revisar: opções como --exec podem lançar comandos, e plugins adicionar código ao processo de download. Mantenha cookies do navegador, credenciais de proxy e URLs assinados fora dos exemplos de configuração e relatórios de diagnóstico.
Download um vídeo
Utiliza primeiro um vídeo curto. Cita o URL, adicione --no-playlist e nomee o arquivo por ID de vídeo.
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -P downloads \
-o "%(id)s.%(ext)s" --print after_move:filepath \
"https://www.youtube.com/watch?v=jNQXAC9IVRw"Sem um formato de sobre-rida, yt-dlp escolhe seus fluxos disponíveis preferidos. Fontes de alta qualidade muitas vezes têm streaming de vídeo e áudio separados, então duas transferências seguidas por uma fusão FFmpeg são normais. Os arquivos intermediários e um arquivo .part podem aparecer enquanto o trabalho está em andamento.
Escolha qualidade e codecs
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
-F "https://www.youtube.com/watch?v=jNQXAC9IVRw"Eleja uma política, não um ID de formato copiado. Verifique resolução, codecs e traços separados audio/video.
| Seletor ou Opção | O que quer dizer? | Quando usar |
|---|---|---|
| BV + BV | Escolha um vídeo-somente e um áudio-somente; FFmpeg combina-os. | Você precisa de ambas as trilhas e pode se misturar localmente. |
| A/B | Tente o selector A, em seguida, B se A não estiver disponível. | Define um declínio explícito em vez de assumir que cada fonte tem os mesmos formatos. |
| [height<=1080] | Exclude os fluxos acima 1080 pixels altos. | Um forte limite superior é um requisito. |
| -S res:1080 | Preferir resolução até 1080; pode selecionar uma maior quando nenhum abaixo está disponível. | 1080p é uma preferência em vez de um telhado duro. |
| --merge-output-format mp4 | Escolha o recipiente quando se mistura fluxos separados. | Você já selecionou fluxos compatíveis. não transcoda codecs. |
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
-f "bv*[height<=1080]+ba/b[height<=1080]" -P downloads \
"https://www.youtube.com/watch?v=jNQXAC9IVRw"Para um editor ou stack de reprodução que especificamente requer H.264 vídeo e AAC áudio, filtrar esses codecs e fusão para MP4. MP4 é um contêiner: um fluxo em um contêiner MP4 ainda pode conter um codec que a sua aplicação não pode decodificar.
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
-f "bv[vcodec^=avc1][height<=1080]+ba[acodec^=mp4a]/b[vcodec^=avc1][acodec^=mp4a][height<=1080]" \
--merge-output-format mp4 -P downloads "https://www.youtube.com/watch?v=jNQXAC9IVRw"Remuxing reembolsas correntes sem re-encodá-los. Transcoding altera codecs e consome CPU enquanto potencialmente muda qualidade. Use --remux-video quando os fluxos já se encaixam no recipiente alvo; use uma conversão deliberada FFmpeg quando um decodificador de fluxo inferior requer codecs diferentes.
Reserve o áudio ou MP3
Se o seu tubo de transcrição aceita o codec de áudio fonte, baixe esse streaming diretamente. Isso evita uma conversão desnecessária de perdas. MP3 é útil quando um consumidor especificamente o requer; um alto MP3 bitrate não pode restaurar detalhes já perdidos na fonte.
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -f ba -P audio \
-o "%(id)s.%(ext)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -f ba -x \
--audio-format mp3 --audio-quality 0 -P audio -o "%(id)s.%(ext)s" \
"https://www.youtube.com/watch?v=jNQXAC9IVRw"Salve capções e metadados
Uma coleção útil precisa mais do que filenames. Mantenha IDs de vídeo, URLs de fonte, títulos, duradas e capções disponíveis para que você possa pesquisar a coleção e rastrear um ativo de volta à sua fonte. Começar com a lista de traços de anotação; solicitar en não significa que cada vídeo tem uma pista em inglês.
python -m yt_dlp --list-subs "https://www.youtube.com/watch?v=jNQXAC9IVRw"
python -m yt_dlp --skip-download --write-subs --write-auto-subs --sub-langs "en.*" \
--sub-format "vtt/best" -P captions -o "%(id)s.%(ext)s" \
"https://www.youtube.com/watch?v=jNQXAC9IVRw"python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist --write-info-json \
--write-thumbnail -P downloads -o "%(id)s.%(ext)s" \
"https://www.youtube.com/watch?v=jNQXAC9IVRw"O .info.json arquivo é metadados operacionais detalhados, não uma resposta pública API limpa. Pode incluir URLs de mídia expirando e campos relacionados com solicitação. Mantenha o lado completo com a coleção, e exportar apenas os campos que o seu sistema de baixo fluxo precisa. Se você precisa SRT em vez de VTT, adicione --convert-subs srt e certifique-se FFmpeg está disponível.
Construa um item de dados AI
Para uma coleção de treinamento, decidir os meios de comunicação e os resultados de texto juntos. Um requisito comum é o melhor vídeo e áudio disponíveis, combinado em MP4, com capções e metadados de extração temporários mantidos sob o mesmo ID de vídeo. Um telhado de resolução útil para as previsões é geralmente o padrão errado para um conjunto de dados de qualidade fonte.
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
-f "bestvideo+bestaudio/best" \
--merge-output-format mp4 --remux-video mp4 \
--write-info-json --write-subs --write-auto-subs \
--sub-langs "en" --sub-format "vtt/best" \
--sleep-subtitles 5 --concurrent-fragments 1 \
-P dataset -o "%(id)s/%(id)s.%(ext)s" \
--print after_move:filepath "https://www.youtube.com/watch?v=jNQXAC9IVRw"Comece com um idioma de nota exato. Em nosso check ao vivo, en.* selecionou en, en-en e en-de; a terceira pista retornou 429 antes de o download de mídia começar. Um erro de nota pode parar o item nessa fase. Após um cooldown, retire apenas a pista necessária, ou dividir mídia e postos de trabalho se a sua coleção tem que manter a ingestão de mídia em movimento.
O /best fallback permite um fluxo combinado video/audio quando as pistas separadas não estão disponíveis. Remova esse falso se o seu contrato de coleta requer fontes separadas de bestvideo e bestaudio. MP4 não significa H.264: esta receita mantém os codecs de origem selecionados. Use o selector H.264/AAC rigoroso acima se o seu decoder de treinamento requer esses codecs, ou transcodes como um passo separado, gravado.
dataset/VIDEO_ID/
VIDEO_ID.mp4
VIDEO_ID.info.json
VIDEO_ID.en.vtt| Requisição | Decisão de coleção |
|---|---|
| Qualidade de fonte mais alta disponível | Use bestvideo+bestaudio, mantenha codecs de fonte e verifica os fluxos combinados com ffprobe. |
| Texto horário | Mantenha os segmentos VTT/SRT e a linguagem ao lado do ID de vídeo.O texto em movimento descartará o tempo necessário para a alinhamento do clipe. |
| Legendas ausentes | Recorde texto ausente explicitamente. direcionar o áudio salvo para a etapa de transcrição se o texto for obrigatório. |
| Capções para muitas línguas | Solicite apenas as línguas necessárias. Cada pista adicional adiciona pedidos e pode encontrar 429 independentemente dos meios de comunicação. |
| Mídia Resumível + Entrega de texto | Use um arquivo de conjunto de dados separado e um inventário com estatutos de mídia, metadados e anotações. Uma entrada de arquivo não prova que todos os painéis de página necessários existem. |
Não reutilize um arquivo criado por um mídia anterior que só está sendo executado para esta nova política: vídeos arquivados podem ser excluídos antes de suas capturas perdidas serem coletadas. Ou execute a política de conjunto de dados com seu próprio arquivo ou agendar um passaporte separado de correção de anotações para IDs de texto perdido. Armazenar capções originais; se o seu modelo precisa de texto transcriptado limpo, derive-o em uma etapa de processamento versada.
Melhorar a passagem de transferência sem sobrecarregar um IP
aria2c pode ajudar quando uma única conexão submetia um link não confiável ou de alta latência. Não pode reparar uma solicitação de jogador rejeitada ou um IP de saída flagrado. Primeiro, faça o downloadador nativo trabalhar em uma fonte; em seguida, compare o tempo de transferência e os erros com um pequeno número de conexões aria2.
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
--downloader aria2c --downloader "dash,m3u8:native" \
--downloader-args "aria2c:-x 2 -s 2 -j 1" \
--concurrent-fragments 1 \
-P downloads -o "%(id)s.%(ext)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"| Controle | O que limita |
|---|---|
| aria2c -x 2 | Conectar-se a um servidor para uma descarga. |
| aria2c -s 2 | Divisões solicitadas para um arquivo; dividir também depende do tamanho do arquivo e do suporte ao servidor. |
| aria2c -j 1 | Os elementos concorrentes dentro desta aria2 invocação, não outros yt-dlp trabalhadores. |
| --concurrent-fragments 1 | O download de fragmento é feito dentro do download nativo DASH/HLS. |
| Seu trabalho queue | Os vídeos ativos compartilhados com o mesmo host ou IP de saída proxy. |
curl-cffi a impersonização pertence às próprias solicitações de yt-dlp; não configura a impressão de impressão TLS de aria2. Se o download nativo funciona, mas aria2 recebe 403, volte para o nativo antes de alterar as configurações do extractor não relacionados. Mantenha a extração e a transferência externa na mesma sessão de proxy.
No funcionamento do FlashData, aumentar a concorrência de forma agressiva pode fazer com que uma rota de trabalho começa a retornar 403 imediatamente. Se isso acontecer, pare os outros trabalhos, volte a um trabalhador e uma conexão, depois reteste. Não compensa, adicionando mais aria2 divisões ou retirando o mesmo fluxo negado em paralelo. Se esse IP permanecer rejeitado em baixo carregamento, use o fluxo de trabalho de substituição 403 IP.
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
--downloader native --concurrent-fragments 1 --limit-rate 2M \
--sleep-requests 2 --sleep-interval 5 --max-sleep-interval 10 \
-P diagnostics "https://www.youtube.com/watch?v=jNQXAC9IVRw"Preparar uma coleção
Para um pequeno conjunto conhecido, crie um UTF-8 urls.txt com um URL de relógio por linha. Para uma lista de reprodução do YouTube, primeiro enumere seus IDs em um manifesto. A extracção plana inspeciona a lista de reprodução sem fazer uma extracção completa para cada vídeo; é útil para a revisão de âmbito, mas as suas entradas podem faltar a duração, os formatos e os detalhes de disponibilidade.
python -m yt_dlp --flat-playlist --print "https://www.youtube.com/watch?v=%(id)s" \
"https://www.youtube.com/playlist?list=YOUR_PLAYLIST_ID" > urls.txtPara tentar uma coleção, selecione algumas entradas da lista de reprodução com --playlist-items 1:5. A tabela /videos de um canal é um ponto de partida mais claro para vídeos carregados do que uma página inicial ambígua do canal. Não tratar a ordem da playlist como identidade: itens podem ser inseridos, reordenados ou removidos.
| Filtros | Usando | Consequências |
|---|---|---|
| --playlist-items 1:5 | As primeiras cinco entradas na lista atual. | Utilidade para um pequeno teste, não um ponto de verificação duradouro. |
| --dateafter 20260101 | Mantenha as entradas datadas em ou após janeiro 1, 2026. | Filtração de data ainda pode exigir extração por vídeo. |
| --match-filters "!is_live & duration <= 1800" | Requer um item não vivo com uma duração conhecida em mais 30 minutos. | As entradas com duração desconhecida não correspondem a este filtro rigoroso. |
| --download-archive archive.txt | Skip IDs de origem já registados por downloads anteriores. | Trabalha em títulos e posições de playlist alterados. |
Resumo de uma coleção com segurança
Salve o seguinte como yt-dlp-work.conf na pasta de coleção, além urls.txt. Defina a política de produção uma vez, dá à coleção seu próprio arquivo e limita as retras. Mantenha os arquivos de saída e este arquivo juntos: um arquivo registra o sucesso pelo extractor e ID, não pelo checksum ou localização do arquivo atual.
# YouTube worker baseline
--js-runtimes deno
--impersonate=""
--concurrent-fragments 1
# Output policy
--no-playlist
-f "bv*[height<=1080]+ba/b[height<=1080]"
-P downloads
-o "%(channel_id)s/%(id)s.%(ext)s"
--write-info-json
# Resume and remember completed media
--continue
--download-archive archive.txt
--no-abort-on-error
# Bound each attempt and spread out work
--retries 5
--fragment-retries 5
--socket-timeout 30
--sleep-requests 1
--sleep-interval 5
--max-sleep-interval 10
# Append paths only after the final move
--print-to-file after_move:filepath completed-paths.txtpython -m yt_dlp --ignore-config --config-locations yt-dlp-work.conf --batch-file urls.txtRepare o mesmo comando após uma interrupção. Os IDs completos são excluídos e transferências parciais recém-recompensáveis continuam onde suportados. Os erros de extração podem ser revertidos na próxima rodada. Os arquivos .part padrão são de estado útil; não os apagar como uma etapa de retiro rotina.
--no-abort-on-error continua passando entradas não disponíveis, mas um curso ainda pode sair não zero e erros pós-processamento precisam de atenção. Evite adicionar --ignore-errors apenas para obter um emprego verde: ele pode tratar falhas pós-processamento como downloads bem sucedidos. Revise o log e as saídas completas antes de declarar a coleção completa.
Verifique os arquivos terminados
O arquivo completed-paths.txt é um inventário de início útil. Teste a saída final real em vez de um vídeo temporário apenas em streaming. ffprobe lê o contagem e o fluxo de metadados; um pass de decodificação separado capta problemas que um cabeçalho somente leível vai perder.
ffprobe -v error -show_entries format=duration,size:stream=codec_type,codec_name,width,height -of json "downloads/CHANNEL_ID/VIDEO_ID.mp4"ffmpeg -v error -i "downloads/CHANNEL_ID/VIDEO_ID.mp4" -f null -| Encontrar | O que fazer |
|---|---|
| Só um .part ou arquivo de fluxo separado permanece | Verifique o erro transfer/merge e reenvia o trabalho original; não etique o arquivo intermediário completo. |
| Vídeo sem som | Verifique o formato selecionado e ffprobe as correntes. um formato de vídeo só precisa de uma seleção de áudio e fusão. |
| MP4 não será aberto em seu editor | Inspire os codecs, não apenas a extensão; selecione fluxos compatíveis ou transcodes explicitamente. |
| ID arquivado mas não arquivo local | Verifique se o arquivo foi moved/deleted. Reconcilia o inventário antes de alterar as entradas do arquivo. |
9 Mover um comando comprovado para um trabalho planejado
Execute o comando completo com sucesso por mão antes de programá-lo. Um calendário geralmente começa com um PATH diferente e diretório de trabalho. Dê-lhe o caminho completo Python do ambiente virtual, o caminho completo de configuração e um directorio de trabalho explícito; também faça FFmpeg e o tempo de execução do JavaScript disponíveis para esse processo.
- Use um único trabalhador para um collection/archive. Não deixe que a corrida de ontem sobrepare a corrida de hoje contra as mesmas saída.
- No Linux, use uma entrada timer/service ou cron com um directorio de trabalho e um bloqueio como um flock. Mantenha os logs fora da pasta de mídia e rotá-los.
- No macOS, use o lanche com pistas de execução e diretório de trabalho absolutas.
- No Windows Task Scheduler, confira o Programa para o ambiente python.exe, Argumentos para -m yt_dlp e as opções de configuração e batch, e Inicie para a pasta de coleção.
- Record start/end tempo, versão executável, fonte manifesto, estado de saída e completed/failed contam. um zero batch out não implica cada item falhar.
- Mantenha os arquivos de cookies e as credenciais de destino fora do repositorio de configuração compartilhado.Dê um trabalho apenas as credenciais que precisa.
As opções de sono no config agem dentro de um processo. Dez trabalhadores que usam as mesmas configurações ainda produzem dez fluxos de pedidos. Aumentar --concurrent-fragments altera a concorrência de fragmentos dentro de uma descarga, não o número de vídeos em sua barra de trabalho.
Escolha o guia de erro certo
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
python -m yt_dlp --versionQuando uma fonte de trabalho anterior se rompe, atualize para a última noite primeiro, incluindo os extras de correspondência. Para o uso binário de forma independente yt-dlp --update-to à noite; -U só permanece no canal atual. Execute um pequeno canário após cada atualização, depois reconstrua os trabalhadores e grava a revisão para que a frota não misture silenciosamente as publicações.
| Sintoma | Comece aqui |
|---|---|
Requested format is not available | Lista os formatos e inspeccione seus filtros rigorosos antes de mudar retras. |
ffmpeg not found / ffprobe and ffmpeg not found | Verifique o PATH da conta do trabalhador ou do calendário. |
| JavaScript desafio / falta de tempo de execução alerta | Verifique a detecção do tempo de execução e o pacote EJS correspondente. |
| HTTP 403 durante a transferência | Identificar o anfitrião e a fase recusados; extração separada da transferência de mídia. |
| HTTP 429 | Parar o IP afetado, permitir um cooldown e menor extraction/caption frequência de pedido. |
Sign in to confirm you’re not a bot | Parar o pacote e diagnosticar uma fonte, sessão e rede. |
Quando a produção pertence a um tubo de nuvem
Se você quiser possuir o download, os fluxos de trabalho acima lhe dão controle sobre arquivos, formatos e processamento. Se o seu aplicativo precisa de mídia concluída entregue para armazenamento, o FlashData fornece empregos de download do YouTube rastreados, manutenção de bot, roteamento de proxy e retras. Sua aplicação apresenta as configurações de fonte e de saída, e depois mantém o ID de trabalho e o registro de entrega.
Material de Referência
A referência de opções de upstream é a fonte da verdade para a versão instalada. Use estas seções quando você muda uma política de coleta ou atualizar uma imagem de trabalhadores.