yt-zmp 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,132 @@
-# Temporary Holding Version
+# YouTube Media Downloader (experimental)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+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.
+
+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.
+
+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.
+
+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`:
+
+```bash
+node download-test.js "URL_DO_YOUTUBE" video-audio 720 mp3
+```
+
+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
+
+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`.
+
+```bash
+YOUTUBE_COOKIE_FILE=/caminho/privado/youtube-cookies.txt \
+  node download-test.js "https://www.youtube.com/watch?v=VIDEO_ID" audio 0 mp3
+```
+
+Pela API:
+
+```js
+await YouTube.downloadMedia(url, {
+  kind: 'audio',
+  audioFormat: 'm4a',
+  cookieFile: '/caminho/privado/youtube-cookies.txt'
+});
+```
+
+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.
+
+## GVS PO token
+
+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:
+
+```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
+```
+
+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.
+
+Para testar a sessão sem baixar mídia:
+
+```bash
+YOUTUBE_COOKIE_FILE=/caminho/privado/youtube-cookies.txt \
+  npm run auth:test -- "https://www.youtube.com/watch?v=VIDEO_ID"
+```
+
+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.
+
+## Uso rápido
+
+```bash
+npm run download:test -- "https://www.youtube.com/watch?v=VIDEO_ID" muxed 720
+```
+
+O terceiro argumento é opcional. Tipos disponíveis:
+
+- `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.
+
+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:
+
+```bash
+node download-test.js "https://www.youtube.com/watch?v=VIDEO_ID" audio 0 mp3
+```
+
+Ou pela API:
+
+```js
+await YouTube.downloadMedia(url, {
+  kind: 'audio',
+  audioFormat: 'mp3',
+  mp3Quality: '2'
+});
+```
+
+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.
+
+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`.
+
+## Vídeo em qualidade maior
+
+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.
+
+```bash
+node download-test.js "https://www.youtube.com/watch?v=VIDEO_ID" video 1080
+```
+
+Pela API:
+
+```js
+await YouTube.downloadMedia(url, {
+  kind: 'video',
+  height: 1080,
+  mergeAudio: true
+});
+```
+
+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 arquivos são salvos em `./downloads` por padrão. Também é possível usar a API:
+
+```js
+import YouTube from './index.js';
+
+const result = await YouTube.downloadMedia(url, {
+  kind: 'audio',
+  outputDir: './downloads'
+});
+```
+
+## Status experimental
+
+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.
+
+## Erro 403 em `googlevideo.com`
+
+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.

package/auth.js

@@ -0,0 +1,63 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+
+function parseNetscapeCookies(filePath) {
+  const text = fs.readFileSync(filePath, 'utf8');
+  const now = Math.floor(Date.now() / 1000);
+  return text
+    .split(/\r?\n/)
+    .filter(line => line && (!line.startsWith('#') || line.startsWith('#HttpOnly_')))
+    .map(line => line.startsWith('#HttpOnly_') ? line.slice('#HttpOnly_'.length) : line)
+    .map(line => line.split('\t'))
+    .filter(parts => parts.length >= 7)
+    .filter(parts => !parts[4] || Number(parts[4]) === 0 || Number(parts[4]) > now)
+    .map(parts => ({
+      domain: parts[0].toLowerCase(),
+      path: parts[2] || '/',
+      secure: parts[3] === 'TRUE',
+      name: parts[5],
+      value: parts.slice(6).join('\t')
+    }));
+}
+
+function cookieHeader(cookies, hostname) {
+  const host = hostname.toLowerCase();
+  const selected = cookies.filter(cookie => {
+    const domain = cookie.domain
+      .replace(/^#HttpOnly_/, '')
+      .replace(/^\./, '');
+    return host === domain || host.endsWith(`.${domain}`);
+  });
+  return selected.map(cookie => `${cookie.name}=${cookie.value}`).join('; ');
+}
+
+export function loadYouTubeAuth(cookieFile, options = {}) {
+  if (!cookieFile) return null;
+  const cookies = parseNetscapeCookies(cookieFile);
+  const cookie = cookieHeader(cookies, 'youtube.com');
+  if (!cookie) {
+    throw new Error('O arquivo de cookies não contém cookies do YouTube.');
+  }
+
+  const sapisidCookie = cookies.find(item =>
+    ['SAPISID', '__Secure-3PAPISID', '__Secure-1PAPISID'].includes(item.name)
+  );
+  const headers = {
+    Cookie: cookie
+  };
+
+  if (sapisidCookie && options.sapisid !== false) {
+    const origin = options.origin || 'https://www.youtube.com';
+    const timestamp = Math.floor(Date.now() / 1000);
+    const digest = crypto
+      .createHash('sha1')
+      .update(`${timestamp} ${sapisidCookie.value} ${origin}`)
+      .digest('hex');
+    headers.Authorization = `SAPISIDHASH ${timestamp}_${digest}`;
+  }
+
+  return {
+    headers,
+    cookieCount: cookies.length
+  };
+}

package/cipher.js

@@ -0,0 +1,172 @@
+import vm from 'node:vm';
+
+function decodeEscapes(value) {
+  return value
+    .replace(/\\u0026/g, '&')
+    .replace(/\\u003d/g, '=')
+    .replace(/\\u0027/g, "'")
+    .replace(/\\u003c/g, '<')
+    .replace(/\\u003e/g, '>')
+    .replace(/\\u002f/g, '/');
+}
+
+function createPlayerContext() {
+  const context = {
+    console,
+    setTimeout,
+    clearTimeout,
+    setInterval,
+    clearInterval,
+    URL,
+    URLSearchParams,
+    TextDecoder,
+    TextEncoder
+  };
+  context.window = context;
+  context.self = context;
+  context.globalThis = context;
+  context.navigator = {
+    userAgent: 'Mozilla/5.0',
+    language: 'pt-BR',
+    languages: ['pt-BR']
+  };
+  context.location = {
+    href: 'https://m.youtube.com/',
+    origin: 'https://m.youtube.com',
+    host: 'm.youtube.com',
+    hostname: 'm.youtube.com',
+    protocol: 'https:'
+  };
+  context.document = {
+    cookie: '',
+    createElement() {
+      return {
+        style: {},
+        setAttribute() {},
+        appendChild() {}
+      };
+    },
+    documentElement: {},
+    body: {},
+    head: {},
+    addEventListener() {},
+    removeEventListener() {}
+  };
+  context.XMLHttpRequest = class {
+    open() {}
+    send() {}
+    setRequestHeader() {}
+    addEventListener() {}
+  };
+  return context;
+}
+
+function createRuntimeTools(source) {
+  const signatureCall = source.match(
+    /if\([^\n]{0,80}\.s\)[\s\S]{0,500}?([\w$]+)\((\d+),(\d+),([\w$]+)\((\d+),(\d+),[^)]*\.s\)\)/
+  );
+  const outer = signatureCall?.[1] || 'ca';
+  const outerA = signatureCall?.[2] || '15';
+  const outerB = signatureCall?.[3] || '5768';
+  const inner = signatureCall?.[4] || 'ic';
+  const innerA = signatureCall?.[5] || '3';
+  const innerB = signatureCall?.[6] || '3124';
+  const marker = `g.__ytzmpDecipher=function(s){return ${outer}(${outerA},${outerB},${inner}(${innerA},${innerB},s));};g.__ytzmpTransform=function(s){try{var u=new g.hc(s,!0),n=u.get("n");if(n){var v=new URL(s);v.searchParams.set("n",n);return v.toString();}}catch(e){}return s;};`;
+  const injected = source.replace(
+    /\}\)\(_yt_player\);\s*$/,
+    `${marker}})(_yt_player);`
+  );
+  if (injected === source) return null;
+
+  const context = createPlayerContext();
+  try {
+    vm.runInNewContext(injected, context, {
+      timeout: 15000,
+      codeGeneration: { strings: false, wasm: false }
+    });
+    const decipher = context._yt_player?.__ytzmpDecipher;
+    const transform = context._yt_player?.__ytzmpTransform;
+    if (typeof decipher !== 'function') return null;
+    return {
+      decipher: value => {
+        try {
+          return String(decipher(String(value)));
+        } catch {
+          return null;
+        }
+      },
+      transform: value => {
+        try {
+          return typeof transform === 'function'
+            ? String(transform(String(value)))
+            : value;
+        } catch {
+          return value;
+        }
+      }
+    };
+  } catch {
+    return null;
+  }
+}
+
+function applyOperation(value, operation, amount = 0) {
+  if (operation === 'reverse') value.reverse();
+  if (operation === 'splice') value.splice(0, amount);
+  if (operation === 'slice') value = value.slice(amount);
+  if (operation === 'swap') {
+    const index = amount % value.length;
+    [value[0], value[index]] = [value[index], value[0]];
+  }
+  return value;
+}
+
+function createHeuristicDecipher(source) {
+  const functionPattern = /(?:function\s+([\w$]+)|([\w$]+)\s*=\s*function)\s*\(([\w$]+)\)\s*\{([\s\S]{0,3000}?)\}/g;
+  let match;
+  while ((match = functionPattern.exec(source))) {
+    const argument = match[3];
+    const body = match[4];
+    if (!body.includes('.split(\"\")') || !body.includes('.join(\"\")')) continue;
+    const operations = [];
+    const statements = body.split(';').map(item => item.trim()).filter(Boolean);
+    for (const statement of statements) {
+      if (statement.includes(`${argument}.reverse()`)) operations.push(['reverse', 0]);
+      let operation = statement.match(new RegExp(`\\b${argument}\\.splice\\(0,(\\d+)\\)`));
+      if (operation) operations.push(['splice', Number(operation[1])]);
+      operation = statement.match(new RegExp(`\\b${argument}\\s*=\\s*${argument}\\.slice\\((\\d+)\\)`));
+      if (operation) operations.push(['slice', Number(operation[1])]);
+    }
+    if (!operations.length) continue;
+    return signature => {
+      let value = String(signature).split('');
+      for (const [operation, amount] of operations) value = applyOperation(value, operation, amount);
+      return value.join('');
+    };
+  }
+  return null;
+}
+
+export function createDecipher(playerJavaScript) {
+  return createRuntimeTools(playerJavaScript)?.decipher || createHeuristicDecipher(playerJavaScript);
+}
+
+export function createPlayerTools(playerJavaScript) {
+  return createRuntimeTools(playerJavaScript);
+}
+
+export function extractPlayerJavaScriptUrl(html) {
+  const matches = [
+    html.match(/"PLAYER_JS_URL":"([^"]+)"/),
+    html.match(/"jsUrl":"([^"]+)"/),
+    html.match(/\/s\/player\/[^"']+\/base\.js/)
+  ];
+  for (const match of matches) {
+    if (!match?.[1] && !match?.[0]) continue;
+    const raw = match[1] || match[0];
+    const decoded = decodeEscapes(raw);
+    if (decoded.startsWith('http')) return decoded;
+    if (decoded.startsWith('/')) return `https://www.youtube.com${decoded}`;
+  }
+  return null;
+}

package/client.js

@@ -0,0 +1,83 @@
+const DEFAULT_HEADERS = {
+  'User-Agent':
+    'Mozilla/5.0 (Linux; Android 13; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Mobile Safari/537.36',
+
+  'Accept-Language':
+    'pt-BR,pt;q=0.9,en-US;q=0.8,en;q=0.7',
+
+  'Accept':
+    '*/*'
+};
+
+export async function request(
+  url,
+  options = {}
+) {
+  const headers = {
+    ...DEFAULT_HEADERS,
+    ...(options.headers || {})
+  };
+
+  const response =
+    await fetch(url, {
+      ...options,
+
+      headers,
+
+      redirect: 'follow'
+    });
+
+  if (!response.ok) {
+    let body = '';
+
+    try {
+      body =
+        await response.text();
+    } catch {}
+
+    const retryAfter = response.headers.get('retry-after');
+    const suffix = response.status === 429
+      ? `; o YouTube limitou temporariamente esta rede${retryAfter ? `; Retry-After: ${retryAfter}s` : ''}`
+      : '';
+    const error =
+      new Error(
+        `HTTP ${response.status}: ${response.statusText}${suffix}`
+      );
+
+    error.status =
+      response.status;
+
+    error.body =
+      body.slice(0, 1000);
+
+    throw error;
+  }
+
+  return response;
+}
+
+export async function getText(
+  url,
+  options = {}
+) {
+  const response =
+    await request(
+      url,
+      options
+    );
+
+  return response.text();
+}
+
+export async function getJson(
+  url,
+  options = {}
+) {
+  const response =
+    await request(
+      url,
+      options
+    );
+
+  return response.json();
+}

package/cookie-test.js

@@ -0,0 +1,36 @@
+import YouTube, { loadYouTubeAuth } from './index.js';
+
+const cookieFile = process.env.YOUTUBE_COOKIE_FILE;
+const url = process.argv[2];
+
+if (!cookieFile) {
+  console.error('Defina YOUTUBE_COOKIE_FILE apontando para o arquivo Netscape.');
+  process.exit(1);
+}
+
+try {
+  const auth = loadYouTubeAuth(cookieFile);
+  console.log('Arquivo de cookies: OK');
+  console.log('Cookies lidos:', auth.cookieCount);
+  console.log('SAPISIDHASH gerado:', Boolean(auth.headers.Authorization));
+
+  if (!url) {
+    console.log('Sessão não testada contra o YouTube: informe uma URL para continuar.');
+    process.exit(0);
+  }
+
+  console.log('\nConsultando o YouTube com a sessão...');
+  const data = await YouTube.extract(url, {
+    headers: auth.headers
+  });
+
+  console.log('Sessão aceita para consulta: SIM');
+  console.log('Título:', data.title || '(não informado)');
+  console.log('Cliente:', data.client?.name || '(não informado)');
+  console.log('Formatos encontrados:', data.formats.length);
+  console.log('Áudios encontrados:', data.formats.filter(item => item.mimeType?.startsWith('audio/')).length);
+} catch (error) {
+  console.error('\nFalha no teste:', error.message);
+  console.error('Nenhum valor de cookie foi exibido.');
+  process.exit(1);
+}

package/direct-test.js

@@ -0,0 +1,73 @@
+const url = process.argv[2];
+
+if (!url) {
+  console.log(
+    'Uso: node direct-test.js "URL_DO_STREAM"'
+  );
+
+  process.exit(1);
+}
+
+try {
+  console.log('Testando URL diretamente...\n');
+
+  const response = await fetch(url, {
+    method: 'GET',
+    redirect: 'follow',
+    headers: {
+      'User-Agent':
+        'Mozilla/5.0 (Linux; Android 13; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Mobile Safari/537.36',
+
+      'Accept':
+        '*/*'
+    }
+  });
+
+  console.log(
+    'Status:',
+    response.status,
+    response.statusText
+  );
+
+  console.log(
+    'Content-Type:',
+    response.headers.get('content-type')
+  );
+
+  console.log(
+    'Content-Length:',
+    response.headers.get('content-length')
+  );
+
+  console.log(
+    'Location:',
+    response.headers.get('location')
+  );
+
+  if (!response.ok) {
+    const text =
+      await response.text();
+
+    console.log(
+      '\nResposta do servidor:\n'
+    );
+
+    console.log(
+      text.slice(0, 1000)
+    );
+
+    process.exit(1);
+  }
+
+  console.log(
+    '\nA URL foi aceita.'
+  );
+
+} catch (error) {
+  console.error(
+    '\nERRO:',
+    error.message
+  );
+
+  process.exit(1);
+}

package/download-test.js

@@ -0,0 +1,61 @@
+import YouTube from './index.js';
+
+const url = process.argv[2];
+const kind = process.argv[3] || 'muxed';
+const height = process.argv[4]
+  ? Number(String(process.argv[4]).replace(/p$/i, ''))
+  : undefined;
+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]');
+  process.exit(1);
+}
+
+if (!['audio', 'video', 'video-audio', 'muxed'].includes(kind)) {
+  console.error('Tipo inválido. Use audio, video, video-audio ou muxed.');
+  process.exit(1);
+}
+
+if (!['m4a', 'mp3'].includes(audioFormat)) {
+  console.error('Formato de áudio inválido. Use m4a ou mp3.');
+  process.exit(1);
+}
+
+if (height !== undefined && !Number.isFinite(height)) {
+  console.error('Altura inválida. Use, por exemplo, 360, 720 ou 720p.');
+  process.exit(1);
+}
+
+try {
+  console.log('\n[EXPERIMENTAL] Consultando e baixando mídia do YouTube...\n');
+
+  const downloadOptions = {
+    height,
+    audioFormat,
+    outputDir: './downloads',
+    cookieFile: process.env.YOUTUBE_COOKIE_FILE,
+    poToken: process.env.YOUTUBE_GVS_PO_TOKEN
+  };
+  const result = kind === 'video-audio'
+    ? await YouTube.downloadAudioFromVideo(url, downloadOptions)
+    : await YouTube.downloadMedia(url, { ...downloadOptions, kind });
+
+  console.log('\n=== DOWNLOAD OK ===');
+  console.log('Título:', result.title);
+  console.log('Tipo:', result.kind);
+  if (result.kind === 'video') console.log('Áudio combinado:', 'sim');
+  if (result.sourceKind === 'video') console.log('Fonte processada:', 'vídeo baixado e áudio extraído com FFmpeg');
+  if (result.audioFormat) console.log('Formato de áudio:', result.audioFormat);
+  console.log('Itag:', result.format.itag);
+  console.log('Formato original:', result.format.mimeType);
+  console.log('Qualidade:', result.format.quality || 'n/a');
+  console.log('Arquivo:', result.path);
+  console.log('Tamanho:', result.size, 'bytes');
+  if (result.format?.sourceClient) console.log('Cliente:', result.format.sourceClient);
+  console.log('PO token aplicado:', result.format?.poTokenApplied ? 'sim' : 'não');
+} catch (error) {
+  console.error('\nERRO:', error.message);
+  if (process.env.DEBUG) console.error(error.stack);
+  process.exit(1);
+}