yt-zmp 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 1.1.0
+
+### Adicionado
+- Suporte a proxy HTTP/HTTPS (`proxy` por chamada, `setDefaultProxy` e `YOUTUBE_PROXY`) em todas as requisições: página, Player API, JavaScript do player e download do stream. Usa `undici` (dependência opcional).
+- Bridge para servidores com IP bloqueado: servidor `yt-zmp-bridge` e cliente `bridgeDownload` (`yt-zmp/bridge`).
+- Detecção de travamento no download (`stallTimeoutMs`, padrão 30 s): o stream que para de enviar dados é abortado e a tentativa é repetida, em vez de ficar pendurado.
+- Linha de comando `yt-zmp`.
+- Suíte de testes offline (`npm test`).
+
+### Corrigido
+- O extrator descarta respostas sem formatos utilizáveis (sem `streamingData`, só SABR ou sem `url`/`signatureCipher`) e passa para o próximo cliente, em vez de parar no primeiro que devolve `streamingData` vazio.
+- `itag`, `bitrate`, `width`, `height` e `fps` são normalizados para número, pois alguns retornos os trazem como texto e quebravam a comparação por `itag`.
+- Mensagens de erro mais claras: status de reprodução do cliente que falhou e causa do erro de conexão no bridge.
+
+### Alterado
+- Código-fonte movido para `src/`; o ponto de entrada continua sendo `import YouTube from 'yt-zmp'`.
+- Mínimo de Node.js: 18.17.
+- O pacote publica apenas `index.js`, `src/`, `bin/`, `README.md`, `LICENSE` e `CHANGELOG.md`.
+
+## 1.0.0
+
+Versão inicial.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yt-zmp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,132 +1,264 @@
-# YouTube Media Downloader (experimental)
+# yt-zmp
 
-Módulo Node.js em fase de testes para consultar vídeos do YouTube e baixar uma mídia a partir dos streams que o YouTube disponibilizar.
+Extração e download de áudio e vídeo do YouTube em Node.js, **sem yt-dlp**. Consulta os clientes internos do YouTube, decifra as URLs dos streams e baixa a mídia, com conversão para MP3 e junção de vídeo e áudio via FFmpeg.
 
-O download é implementado pelo próprio módulo, sem usar `yt-dlp`. O extrator tenta clientes internos do YouTube (`ANDROID`, `WEB`, `MWEB`, `IOS` e `TVHTML5`) e usa o perfil que retornar os streams. Os perfis Android e iOS usam versões e parâmetros de dispositivo compatíveis com os clientes atuais observados no código do yt-dlp.
+Recursos principais:
 
-Para áudio, o seletor prioriza `audio/mp4` (AAC, geralmente itag 140) antes de WebM/Opus, pois esse stream é mais compatível com download direto e conversão para MP3.
+- Cadeia de clientes (`WEB`, `MWEB`, `ANDROID`, `IOS`, `TVHTML5` e outros), usando o primeiro que devolver streams utilizáveis.
+- Áudio (`m4a` ou `mp3`), vídeo em qualidade escolhida (com junção de áudio) e streams muxados (ex.: itag 18).
+- **Proxy HTTP/HTTPS** por chamada, por variável de ambiente ou global.
+- **Bridge** para servidores cujo IP o YouTube bloqueia: o download é feito em outra máquina com IP residencial.
+- Cookies (formato Netscape) e GVS PO token opcionais.
+- Download com detecção de travamento: se o stream parar de enviar dados, a tentativa é abortada e repetida.
 
-Se um formato retornar 403, o módulo tenta os demais streams de áudio disponíveis e repete a requisição sem `Range` antes de renovar a extração. Os cookies de sessão continuam sendo usados somente nas requisições ao YouTube.
+> Projeto independente, sem relação com o YouTube ou o Google. O YouTube muda seus endpoints com frequência; se algo parar de funcionar, atualize o pacote. Use apenas em conteúdo que você tem autorização para baixar e respeite os termos de uso do serviço.
 
-Quando o YouTube entrega `signatureCipher`, o módulo carrega o JavaScript do player em um sandbox isolado e reutiliza a rotina de assinatura do próprio player antes de montar a URL do stream. Há também um decifrador heurístico de fallback para versões mais simples do player.
-
-Para baixar o vídeo, combinar vídeo e áudio com FFmpeg e entregar somente o áudio final, use `video-audio`:
+## Instalação
 
 ```bash
-node download-test.js "URL_DO_YOUTUBE" video-audio 720 mp3
+npm install yt-zmp
 ```
 
-Esse modo cria temporariamente um MP4 com vídeo e áudio, extrai o áudio com FFmpeg e remove o arquivo temporário. Use `m4a` para preservar o áudio AAC sem recodificação ou `mp3` para converter com LAME.
-
-## Sessão autenticada opcional
+- Node.js **18.17 ou superior**.
+- **FFmpeg** no `PATH` (ou informe `ffmpegPath`) para gerar MP3, combinar vídeo com áudio ou extrair áudio de um stream muxado. O formato `m4a` direto não precisa de FFmpeg.
+- O `undici` é instalado como dependência opcional e só é usado quando há proxy.
 
-Para vídeos que exigem uma conta autenticada, o módulo aceita um arquivo de cookies no formato Netscape. Use somente cookies da sua própria conta, mantenha o arquivo fora do repositório e nunca cole os valores em logs ou mensagens. O módulo usa os cookies e o `SAPISIDHASH` apenas nas requisições ao YouTube; eles não são enviados ao host `googlevideo.com`.
+O pacote é ESM. Em projetos CommonJS, use `import()` dinâmico:
 
-```bash
-YOUTUBE_COOKIE_FILE=/caminho/privado/youtube-cookies.txt \
-  node download-test.js "https://www.youtube.com/watch?v=VIDEO_ID" audio 0 mp3
+```js
+const { default: YouTube } = await import('yt-zmp');
 ```
 
-Pela API:
+## Uso rápido
 
 ```js
-await YouTube.downloadMedia(url, {
+import YouTube from 'yt-zmp';
+
+// Áudio em MP3
+const audio = await YouTube.downloadMedia('https://youtu.be/VIDEO_ID', {
   kind: 'audio',
-  audioFormat: 'm4a',
-  cookieFile: '/caminho/privado/youtube-cookies.txt'
+  audioFormat: 'mp3',
+  outputDir: './downloads'
 });
-```
+console.log(audio.path, audio.title, audio.size);
 
-O arquivo deve conter linhas Netscape com domínio, caminho, expiração, nome e valor. Cookies autenticados não garantem a superação de todos os desafios anti-bot, CAPTCHA ou exigências de verificação do YouTube; nesses casos, o módulo retorna o motivo informado pelo serviço.
+// Vídeo até 720p, com áudio combinado
+const video = await YouTube.downloadMedia('https://youtu.be/VIDEO_ID', {
+  kind: 'video',
+  height: 720
+});
 
-## GVS PO token
+// Só metadados e formatos, sem baixar
+const info = await YouTube.extract('https://youtu.be/VIDEO_ID');
+console.log(info.title, info.client.name, info.formats.length);
+```
 
-Versões recentes do YouTube podem exigir um **GVS PO token** para autorizar as URLs de mídia. O yt-zmp não tenta fabricar esse token nem usa o yt-dlp para obtê-lo. Quando você possui um token legítimo para a sessão/cliente, forneça-o por variável de ambiente; ele será acrescentado como `pot` às URLs de stream durante a extração:
+A linha de comando faz o mesmo:
 
 ```bash
-YOUTUBE_GVS_PO_TOKEN='TOKEN_BASE64URL' \
-YOUTUBE_COOKIE_FILE=/caminho/privado/youtube-cookies.txt \
-node download-test.js "https://www.youtube.com/watch?v=VIDEO_ID" video-audio 720 mp3
+npx yt-zmp "https://youtu.be/VIDEO_ID" audio 0 mp3
+npx yt-zmp "https://youtu.be/VIDEO_ID" video 720
+npx yt-zmp "https://youtu.be/VIDEO_ID" muxed
 ```
 
-Também é possível passar `poToken` diretamente em `extract`, `downloadMedia` ou `downloadAudioFromVideo`. O valor não deve ser salvo no repositório nem impresso em logs. Sem PO token, alguns formatos podem aparecer na extração, mas retornar HTTP 403 no host `googlevideo.com`; nesse caso trocar cabeçalhos ou repetir a mesma URL não resolve a autorização ausente.
+Uso: `yt-zmp URL [audio|video|video-audio|muxed] [altura] [m4a|mp3]`. Lê `YOUTUBE_COOKIE_FILE`, `YOUTUBE_GVS_PO_TOKEN` e `YOUTUBE_PROXY` do ambiente.
 
-Para testar a sessão sem baixar mídia:
+## API
 
-```bash
-YOUTUBE_COOKIE_FILE=/caminho/privado/youtube-cookies.txt \
-  npm run auth:test -- "https://www.youtube.com/watch?v=VIDEO_ID"
-```
+### `YouTube.downloadMedia(input, options)`
 
-O teste informa apenas se o arquivo foi lido, quantos cookies foram encontrados, se o `SAPISIDHASH` foi gerado e se o YouTube retornou metadados/formatos. Ele nunca imprime os valores dos cookies.
+`input` aceita link (`watch`, `youtu.be`, `shorts`, `embed`) ou o ID de 11 caracteres. Devolve `{ path, size, id, title, kind, audioFormat, format }`.
 
-## Uso rápido
+| Opção | Padrão | Descrição |
+| --- | --- | --- |
+| `kind` | `'muxed'` | `'audio'`, `'video'` ou `'muxed'` (vídeo com áudio no mesmo stream, em geral até 360p). |
+| `audioFormat` | `'m4a'` | Para `kind: 'audio'`: `'m4a'` ou `'mp3'`. |
+| `mp3Quality` | `'2'` | Qualidade LAME (0 melhor, 9 pior). |
+| `height` | — | Altura máxima para vídeo. Se não existir, usa a melhor abaixo do limite. |
+| `itag` | — | Força um itag específico. |
+| `mergeAudio` | `true` | Em `kind: 'video'`, baixa o melhor áudio e combina com FFmpeg. |
+| `outputDir` | `'./downloads'` | Pasta de saída. |
+| `outputPath` | — | Caminho final do arquivo (ignora `outputDir`). |
+| `retries` | `3` | Tentativas; a cada falha a extração é refeita com URL nova. |
+| `client` | — | Força um cliente (`WEB`, `MWEB`, `ANDROID`, `IOS`, `TVHTML5`...). Sem isso, tenta em cadeia. |
+| `proxy` | — | URL do proxy para esta chamada. Veja [Proxy](#proxy). |
+| `stallTimeoutMs` | `30000` | Aborta o stream se ficar esse tempo sem receber dados. `0` desativa. |
+| `cookieFile` | — | Arquivo de cookies Netscape. |
+| `poToken` | `YOUTUBE_GVS_PO_TOKEN` | GVS PO token. |
+| `headers` | — | Cabeçalhos extras. |
+| `ffmpegPath` | `'ffmpeg'` | Caminho do executável. |
 
-```bash
-npm run download:test -- "https://www.youtube.com/watch?v=VIDEO_ID" muxed 720
-```
+Quando o cliente só fornece um stream muxado (como o itag 18), `kind: 'audio'` baixa esse arquivo e o FFmpeg extrai o áudio, em vez de falhar por falta de áudio adaptativo.
 
-O terceiro argumento é opcional. Tipos disponíveis:
+### `YouTube.downloadAudioFromVideo(input, options)`
 
-- `muxed`: vídeo com áudio no mesmo stream, quando disponível;
-- `audio`: melhor stream de áudio disponível;
-- `video`: melhor stream de vídeo disponível, que pode não conter áudio.
+Baixa o vídeo com áudio, extrai só o áudio com FFmpeg e apaga o temporário. Aceita as mesmas opções de rede de `downloadMedia`.
 
-Para áudio, o formato padrão é `m4a`, baixado diretamente do stream AAC original. Para gerar MP3, o módulo baixa o stream de áudio e faz a conversão local com FFmpeg:
+### `YouTube.extract(input, options)`
 
-```bash
-node download-test.js "https://www.youtube.com/watch?v=VIDEO_ID" audio 0 mp3
+Devolve `{ id, title, author, channelId, duration, viewCount, thumbnail, formats, expiresInSeconds, client, poTokenApplied }`. Cada item de `formats` tem `itag`, `mimeType`, `quality`, `audioQuality`, `bitrate`, `width`, `height`, `fps`, `contentLength`, `url`, `hasUrl` e `sourceClient`.
+
+Opções: `client`, `webOnly`, `includePlayerJson` (anexa o JSON bruto do Player API em `playerJson`), `proxy`, `cookieFile`, `auth`, `poToken`, `headers` e `pageRetries`.
+
+### Seletores de formato
+
+`findAudio`, `findVideo`, `findMuxed`, `sortAudio`, `sortVideo` e `sortMuxed` ignoram formatos sem URL. `findAudio(formats, { mimeType: 'audio/mp4' })` prioriza AAC (itag 140), mais compatível com conversão para MP3.
+
+### Outras funções
+
+`extractVideoId`, `normalizeUrl`, `download`, `downloadWithRetry`, `convertToMp3`, `mergeVideoAudio`, `extractAudioFromVideo`, `loadYouTubeAuth`, `setDefaultProxy` e `bridgeDownload` também estão em `YouTube` e como exportações nomeadas.
+
+## Clientes do YouTube
+
+Por padrão o módulo tenta `WEB`, `MWEB`, `ANDROID`, `IOS`, `TVHTML5` e variantes embutidas, nessa ordem, e usa o primeiro que devolver ao menos um formato com URL (ou `signatureCipher`). Respostas sem formatos utilizáveis, como as que trazem só `serverAbrStreamingUrl` (SABR), são descartadas e o próximo cliente é tentado.
+
+```js
+// força um cliente; não há fallback para os outros
+await YouTube.downloadMedia(url, { kind: 'audio', client: 'ANDROID' });
+
+// só WEB, com o JSON bruto do Player API
+const data = await YouTube.extract(url, { webOnly: true, includePlayerJson: true });
 ```
 
-Ou pela API:
+Variáveis de ambiente equivalentes: `YOUTUBE_PLAYER_CLIENT=ANDROID` e `YOUTUBE_WEB_ONLY=1`.
+
+Cada cliente recebe respostas diferentes. Os clientes web costumam exigir PO token para os streams; o `ANDROID` costuma entregar URLs diretas, às vezes só no muxed itag 18. Para obter MP3 a partir de qualquer um deles basta ter FFmpeg.
+
+## Uso em servidor ou hospedagem
+
+O YouTube trata IPs de datacenter com mais desconfiança do que IPs residenciais. Em hospedagens, VPS e nuvem é comum receber "Faça login para confirmar que não é um bot", `UNPLAYABLE` sem `streamingData` ou `403` no `googlevideo.com`, mesmo com o mesmo código funcionando no seu computador ou celular. Um PO token ou cookies, sozinhos, não resolvem bloqueio por IP.
+
+As saídas, da mais automática para a menos:
+
+1. **Proxy residencial** com sessão fixa. Veja [Proxy](#proxy).
+2. **Bridge**: outra máquina com IP residencial faz o download e o servidor só recebe o arquivo. Veja [Bridge](#bridge).
+3. Rodar o código em uma máquina com IP residencial.
+
+## Proxy
+
+Todas as requisições (página, Player API, JavaScript do player e download do stream) podem sair por um proxy HTTP/HTTPS. Requer o pacote `undici`, instalado como dependência opcional.
 
 ```js
+// 1. por chamada
 await YouTube.downloadMedia(url, {
   kind: 'audio',
-  audioFormat: 'mp3',
-  mp3Quality: '2'
+  proxy: 'http://usuario:senha@host:porta'
 });
+
+// 2. padrão global do processo
+YouTube.setDefaultProxy('http://usuario:senha@host:porta');
+
+// 3. variável de ambiente
+// YOUTUBE_PROXY=http://usuario:senha@host:porta
 ```
 
-O formato `m4a` não exige FFmpeg. O formato `mp3` exige que o executável `ffmpeg` esteja instalado e disponível no PATH; também é possível informar `ffmpegPath` na API.
+Prioridade: opção `proxy` da chamada, depois `setDefaultProxy`, depois `YOUTUBE_PROXY`. Sem nenhum deles, o módulo usa o `fetch` normal e não precisa do `undici`.
+
+**Sessão fixa é obrigatória.** A URL do stream fica presa ao IP que fez a consulta. Se o proxy trocar de IP entre a consulta e o download, o resultado é `403`. Use a opção de sessão fixa (sticky) do seu provedor, em geral um identificador no usuário ou uma porta dedicada, conforme a documentação dele. Se o IP girar no meio de uma tentativa, `retries` refaz a extração com URL nova.
+
+Caracteres especiais na senha precisam estar codificados na URL (`encodeURIComponent`). O consumo de dados é o do vídeo: um MP4 de 360p de poucos minutos fica em torno de 10 MB; áudio gasta menos.
 
-Quando o cliente do YouTube fornecer somente um formato muxado, como o itag 18, o modo `audio` agora baixa esse arquivo e extrai o áudio com FFmpeg em vez de falhar por ausência de áudio adaptativo. O mesmo fallback é usado por `video-audio`. Na linha de comando, a altura pode ser informada como `720` ou `720p`.
+## Bridge
 
-## Vídeo em qualidade maior
+O bridge divide o trabalho em duas pontas:
 
-Streams muxados (`muxed`) costumam ficar limitados a 360p. Para obter uma resolução maior, use `kind: 'video'`: o módulo baixa o stream de vídeo adaptativo e o melhor áudio separadamente e combina os dois localmente com FFmpeg.
+- **Servidor** (`yt-zmp-bridge`), em uma máquina com IP que o YouTube aceita, como um PC ou celular com Termux. Faz a consulta e o download.
+- **Cliente** (`bridgeDownload`), na hospedagem. Pede o arquivo ao servidor e salva localmente.
+
+### Servidor
 
 ```bash
-node download-test.js "https://www.youtube.com/watch?v=VIDEO_ID" video 1080
+BRIDGE_TOKEN='uma-senha-longa-e-aleatoria' npx yt-zmp-bridge
 ```
 
-Pela API:
+| Variável | Padrão | Descrição |
+| --- | --- | --- |
+| `BRIDGE_TOKEN` | obrigatória | Mínimo de 12 caracteres. Enviada no cabeçalho `x-token`. |
+| `PORT` | `3000` | Porta. |
+| `BRIDGE_HOST` | `127.0.0.1` | Endereço de escuta. |
+| `BRIDGE_MAX_PARALLEL` | `2` | Downloads simultâneos; acima disso responde `429`. |
+| `YOUTUBE_PLAYER_CLIENT` | `ANDROID` | Cliente usado no servidor. |
+| `BRIDGE_COOKIE_FILE` | — | Cookies Netscape opcionais. |
+
+Para áudio, o servidor tenta o stream de áudio puro e, se falhar, cai para o muxed itag 18. Quem recebe converte para MP3 com FFmpeg.
+
+Para ser alcançado pela hospedagem sem abrir portas, use um túnel de saída, como `cloudflared tunnel --url http://localhost:3000`. Em túneis temporários a URL muda a cada reinício, e túneis gratuitos podem cortar respostas que demoram mais de cerca de 100 s sem enviar dados.
+
+### Cliente
 
 ```js
-await YouTube.downloadMedia(url, {
-  kind: 'video',
-  height: 1080,
-  mergeAudio: true
+import { bridgeDownload } from 'yt-zmp/bridge';
+
+const r = await bridgeDownload('https://youtu.be/VIDEO_ID', './downloads/musica', {
+  bridgeUrl: 'https://seu-tunel.exemplo.com', // ou BRIDGE_URL
+  token: process.env.BRIDGE_TOKEN,            // ou BRIDGE_TOKEN
+  kind: 'audio',                              // 'audio' | 'video' | 'muxed'
+  audioFormat: 'm4a'
 });
+// r.path => ./downloads/musica.m4a (a extensão vem do servidor)
 ```
 
-Se a resolução solicitada não existir, o módulo escolhe a melhor resolução disponível abaixo do limite informado. A combinação de vídeo de alta resolução exige FFmpeg; `mergeAudio: false` permite salvar apenas o stream de vídeo.
+Os erros dizem o que aconteceu: token diferente (`401`), túnel fora do ar (`530`), túnel cortou por demora (`524`), servidor ocupado (`429`) ou sem resposta no tempo limite (`timeoutMs`, padrão 10 min).
+
+**Segurança:** quem tiver a URL e o token consegue usar o servidor para baixar vídeos pela sua conexão. Use um token longo e aleatório e não o publique em repositório.
+
+## Cookies
 
-Os arquivos são salvos em `./downloads` por padrão. Também é possível usar a API:
+Para vídeos que exigem conta, aceita um arquivo de cookies Netscape. Use apenas cookies da sua própria conta e mantenha o arquivo fora do repositório.
 
 ```js
-import YouTube from './index.js';
+await YouTube.downloadMedia(url, { kind: 'audio', cookieFile: '/caminho/privado/cookies.txt' });
+```
 
-const result = await YouTube.downloadMedia(url, {
-  kind: 'audio',
-  outputDir: './downloads'
-});
+Os cookies e o `SAPISIDHASH` são enviados só ao YouTube, nunca ao `googlevideo.com`. Cookies não garantem a superação de CAPTCHA ou de bloqueio por IP. Para conferir a sessão sem baixar nada:
+
+```bash
+YOUTUBE_COOKIE_FILE=/caminho/privado/cookies.txt npm run auth:check -- "URL"
+```
+
+O comando informa quantos cookies foram lidos e se o YouTube respondeu, sem imprimir valores.
+
+## GVS PO token
+
+Algumas respostas exigem um GVS PO token nas URLs de mídia. O yt-zmp **não gera** esse token; se você tem um legítimo para a sessão e o cliente, informe-o e ele será anexado como `pot` às URLs:
+
+```js
+await YouTube.downloadMedia(url, { kind: 'video', poToken: process.env.YOUTUBE_GVS_PO_TOKEN });
 ```
 
-## Status experimental
+Sem o token, alguns formatos aparecem na extração mas dão `403` no download. Não imprima nem versione o valor.
+
+## Erros comuns
+
+| Sintoma | Causa provável |
+| --- | --- |
+| `sem formatos utilizáveis [UNPLAYABLE, sem streamingData]` | O YouTube recusou o cliente ou o IP. Tente outro `client`, um proxy residencial ou o bridge. |
+| `403` no stream | URL presa a outro IP (proxy sem sessão fixa, extração e download em redes diferentes), PO token ausente ou URL expirada (`expiresInSeconds`). |
+| `nenhuma URL pôde ser resolvida` | Falha ao decifrar a assinatura do player: o `cipher.js` precisa acompanhar uma mudança do YouTube. Atualize o pacote. |
+| `Download travado: sem dados por 30s` | O stream parou de enviar. A tentativa é repetida; ajuste `stallTimeoutMs` se a rede for lenta. |
+| `FFmpeg não encontrado` | Instale o FFmpeg ou informe `ffmpegPath`. |
+
+Não reutilize nem salve URLs do `googlevideo.com`: são assinadas, expiram rápido e podem ficar presas ao IP da extração. O `downloadMedia` extrai uma URL nova a cada tentativa.
+
+## Variáveis de ambiente
+
+| Variável | Uso |
+| --- | --- |
+| `YOUTUBE_PROXY` | Proxy padrão. |
+| `YOUTUBE_PLAYER_CLIENT` | Cliente forçado. |
+| `YOUTUBE_WEB_ONLY` | `1` para usar só o cliente WEB. |
+| `YOUTUBE_GVS_PO_TOKEN` | GVS PO token. |
+| `YOUTUBE_COOKIE_FILE` | Cookies, lidos pela linha de comando. |
+| `BRIDGE_URL`, `BRIDGE_TOKEN` | Padrões de `bridgeDownload`. |
+
+## Desenvolvimento
+
+```bash
+npm test
+```
 
-Este projeto ainda está em testes. As URLs de stream são temporárias, os formatos disponíveis variam por vídeo e o YouTube pode alterar seus endpoints ou exigir novos parâmetros. O módulo combina streams adaptativos de vídeo e áudio e converte áudio para MP3 localmente com FFmpeg. Use somente em conteúdos que você tem autorização para baixar e respeite os termos aplicáveis.
+Os testes rodam offline e cobrem links, seletores de formato, filtro de respostas, proxy, detecção de travamento no download e o cliente do bridge. Os scripts em `scripts/` fazem testes manuais contra o YouTube e não vão no pacote publicado.
 
-## Erro 403 em `googlevideo.com`
+## Licença
 
-Não reutilize nem salve a URL `googlevideo.com` retornada pelo YouTube. Ela é assinada, expira rapidamente e pode ficar vinculada ao IP que fez a extração. O fluxo `downloadMedia()` extrai uma URL nova a cada tentativa e baixa imediatamente, mas ainda pode falhar se a extração e o download forem executados em máquinas ou redes diferentes. Em caso de 403 persistente, verifique primeiro se o cliente exige GVS PO token, se a extração e o download ocorrem na mesma máquina/rede e se a URL ainda está dentro de `expiresInSeconds`. O downloader valida respostas parciais e tenta formatos alternativos, mas não consegue contornar uma política de autorização do servidor sem o token necessário. O projeto continua independente do yt-dlp; o código dele foi usado apenas como referência técnica.
+MIT.

package/bin/yt-zmp-bridge.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../src/bridge-server.js";

package/{download-test.js → bin/yt-zmp.js}

@@ -1,4 +1,5 @@
-import YouTube from './index.js';
+#!/usr/bin/env node
+import YouTube from '../index.js';
 
 const url = process.argv[2];
 const kind = process.argv[3] || 'muxed';
@@ -8,7 +9,7 @@ const height = process.argv[4]
 const audioFormat = process.argv[5] || 'm4a';
 
 if (!url) {
-  console.log('Uso: node download-test.js "URL_DO_YOUTUBE" [audio|video|video-audio|muxed] [altura] [m4a|mp3]');
+  console.log('Uso: yt-zmp "URL_DO_YOUTUBE" [audio|video|video-audio|muxed] [altura] [m4a|mp3]');
   process.exit(1);
 }
 
@@ -28,13 +29,14 @@ if (height !== undefined && !Number.isFinite(height)) {
 }
 
 try {
-  console.log('\n[EXPERIMENTAL] Consultando e baixando mídia do YouTube...\n');
+  console.log('\nConsultando e baixando mídia do YouTube...\n');
 
   const downloadOptions = {
     height,
     audioFormat,
     outputDir: './downloads',
     cookieFile: process.env.YOUTUBE_COOKIE_FILE,
+    proxy: process.env.YOUTUBE_PROXY,
     poToken: process.env.YOUTUBE_GVS_PO_TOKEN
   };
   const result = kind === 'video-audio'

package/index.js

@@ -1,37 +1,16 @@
+import { extractVideoId, normalizeUrl } from './src/parser.js';
+import { extract } from './src/extractor.js';
+import { download, downloadWithRetry } from './src/downloader.js';
+import { downloadMedia, downloadAudioFromVideo } from './src/media.js';
+import { loadYouTubeAuth } from './src/auth.js';
+import { convertToMp3, mergeVideoAudio, extractAudioFromVideo } from './src/transcoder.js';
+import { setDefaultProxy } from './src/proxy.js';
+import { bridgeDownload } from './src/bridge-client.js';
 import {
-  extractVideoId,
-  normalizeUrl
-} from './parser.js';
-
-import {
-  extract
-} from './extractor.js';
-
-import {
-  download,
-  downloadWithRetry
-} from './downloader.js';
-
-import {
-  downloadMedia,
-  downloadAudioFromVideo
-} from './media.js';
-import {
-  loadYouTubeAuth
-} from './auth.js';
-
-import {
-  createFormat,
-  isAudio,
-  isVideo,
-  isMuxed,
-  sortAudio,
-  sortVideo,
-  sortMuxed,
-  findAudio,
-  findVideo,
-  findMuxed
-} from './formats.js';
+  createFormat, isAudio, isVideo, isMuxed,
+  sortAudio, sortVideo, sortMuxed,
+  findAudio, findVideo, findMuxed
+} from './src/formats.js';
 
 export const YouTube = {
   extractVideoId,
@@ -44,23 +23,31 @@ export const YouTube = {
   loadYouTubeAuth,
 
   createFormat,
-
   isAudio,
   isVideo,
   isMuxed,
-
   sortAudio,
   sortVideo,
   sortMuxed,
-
   findAudio,
   findVideo,
   findMuxed,
 
   download,
-  downloadWithRetry
+  downloadWithRetry,
+
+  convertToMp3,
+  mergeVideoAudio,
+  extractAudioFromVideo,
+
+  setDefaultProxy,
+  bridgeDownload
 };
 
-export { loadYouTubeAuth };
+export {
+  loadYouTubeAuth,
+  setDefaultProxy,
+  bridgeDownload
+};
 
 export default YouTube;

package/package.json

@@ -1,36 +1,45 @@
 {
-"name": "yt-zmp",
-"version": "1.0.0",
-"type": "module",
-"description": "Biblioteca experimental para pesquisa, extração e download de mídias do YouTube, incluindo metadados, áudio e vídeo.",
-"main": "./index.js",
-"exports": {
-".": "./index.js"
-},
-"files": [
-"*.js",
-"src/",
-"README.md",
-"LICENSE"
-],
-"scripts": {
-"test": "node test.js",
-"download:test": "node download-test.js",
-"auth:test": "node cookie-test.js"
-},
-"engines": {
-"node": ">=18"
-},
-"keywords": [
-"yt-zmp",
-"youtube",
-"youtube-downloader",
-"youtube-search",
-"youtube-audio",
-"youtube-video",
-"media-downloader",
-"extractor"
-],
-"license": "MIT",
-"dependencies": {}
-}
+  "name": "yt-zmp",
+  "version": "1.1.0",
+  "description": "Extração e download de áudio e vídeo do YouTube em Node.js, sem yt-dlp. Suporta proxy, cookies, PO token e um bridge para servidores com IP bloqueado.",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js",
+    "./bridge": "./src/bridge-client.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "yt-zmp": "./bin/yt-zmp.js",
+    "yt-zmp-bridge": "./bin/yt-zmp-bridge.js"
+  },
+  "files": [
+    "index.js",
+    "src/",
+    "bin/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "auth:check": "node scripts/cookie-check.js"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "keywords": [
+    "youtube",
+    "youtube-downloader",
+    "youtube-audio",
+    "youtube-mp3",
+    "downloader",
+    "extractor",
+    "proxy",
+    "whatsapp-bot"
+  ],
+  "license": "MIT",
+  "optionalDependencies": {
+    "undici": "^6.21.0"
+  }
+}