yt-downloader

Biblioteca Node.js para baixar vídeos e áudios do YouTube em MP3/MP4, usando yt-dlp por trás dos panos via child_process.

Por que yt-dlp?

Libs JS puras como play-dl e @distube/ytdl-core (arquivada em ago/2025) não acompanham as proteções atuais do YouTube (SABR streaming, PO Tokens). O yt-dlp é o projeto mais ativamente mantido pra lidar com isso, então esta lib delega a extração pra ele e expõe uma API limpa em cima.

Requisitos

• Node.js 18+
• yt-dlp instalado no sistema (não é pacote npm):

  pip install -U yt-dlp

  ou baixe o binário direto: https://github.com/yt-dlp/yt-dlp/releases
• ffmpeg instalado no sistema (usado pelo yt-dlp pra converter/mixar):

  apt install ffmpeg        # Linux
  pkg install ffmpeg        # Termux

Instalação

npm install

Autenticação (cookies)

O YouTube exige sessão autenticada pra liberar certos formatos. Você precisa fornecer um cookies.txt exportado de um navegador logado no YouTube:

1. Instale a extensão "Get cookies.txt LOCALLY" no navegador
2. Faça login no YouTube
3. Exporte os cookies com a extensão
4. Salve o arquivo como cookies.txt na raiz do projeto

⚠️ Ambiente Termux/Android: a flag --cookies-from-browser do yt-dlp não funciona no Termux (cada app é sandboxed no Android e não é possível ler o banco de cookies de outros apps). O cookies.txt precisa ser exportado manualmente em outro navegador e transferido pro dispositivo.

⚠️ Cookies de sessão expiram periodicamente — se os downloads começarem a falhar, exporte um cookies.txt novo.

⚠️ Nunca compartilhe seu cookies.txt publicamente — ele pode conter credenciais de sessão.

Uso

const { baixarAudio, baixarVideo } = require('./ytdlp-download.js');

(async () => {
  // Baixar áudio em MP3
  await baixarAudio('https://youtu.be/XXXXXXX');

  // Baixar vídeo em MP4 (qualidade padrão: 1080p)
  await baixarVideo('https://youtu.be/XXXXXXX');

  // Baixar vídeo em qualidade específica
  await baixarVideo('https://youtu.be/XXXXXXX', './downloads', '720');
})();

API

baixarAudio(youtubeUrl, outputDir = './downloads')

Baixa o áudio do vídeo em MP3 (melhor qualidade disponível).

| Parâmetro | Tipo | Padrão | Descrição | |---|---|---|---| | youtubeUrl | string | — | URL do vídeo do YouTube | | outputDir | string | './downloads' | Pasta de destino |

Retorna: Promise<{ stdout: string, stderr: string }>

baixarVideo(youtubeUrl, outputDir = './downloads', qualidade = '1080')

Baixa o vídeo em MP4, mesclando a melhor faixa de vídeo e áudio disponíveis até a qualidade especificada.

| Parâmetro | Tipo | Padrão | Descrição | |---|---|---|---| | youtubeUrl | string | — | URL do vídeo do YouTube | | outputDir | string | './downloads' | Pasta de destino | | qualidade | string | '1080' | Altura máxima em pixels (ex: '720', '480') |

Retorna: Promise<{ stdout: string, stderr: string }>

Limitações conhecidas

• Depende do binário yt-dlp estar atualizado — o YouTube muda suas proteções com frequência, então mantenha o yt-dlp sempre na última versão (pip install -U yt-dlp).
• Sem cookies.txt válido, alguns formatos/vídeos podem falhar ou vir só com qualidade limitada.
• Nomes de arquivo seguem o título original do vídeo (%(title)s.%(ext)s) — títulos com caracteres especiais podem gerar nomes de arquivo estranhos dependendo do sistema de arquivos.

Licença

MIT