yt-channel-scraper/docs/COOKIES.md

Guía de cookies

Las cookies son tu sesión de YouTube. Este scraper las usa (vía yt-dlp) para presentarse con esa sesión en cada petición.

Por qué hacen falta

• Vídeos de membresía (subscriber_only): sin sesión es imposible descargarlos; con ella, si estás suscrito al canal, entran como cualquier otro.
• Menos bot-checks / rate-limit: una sesión autenticada aguanta bastante más tráfico que una anónima antes de toparse con el muro (~300 vídeos/hora en sesión de invitado según la wiki de yt-dlp).
• Challenges y PO tokens: parte de los retos anti-bot que YouTube sirve se suavizan cuando la petición viaja con cookies de una sesión real.

Sin cookies el scraper funciona igual; simplemente verás más error por throttling y los vídeos de membresía quedan bloqueados.

Qué es un cookies.txt (formato Netscape)

Un archivo de texto plano con una cookie por línea, tabulador-separado:

.youtube.com\tTRUE\t/\tTRUE\t1798761600\tSID\t"value"
.youtube.com\tTRUE\t/\tTRUE\t0\t__Secure-3PSID\t"value"

Detalles que importan aquí:

• Las líneas #HttpOnly_... son datos, no comentarios: las cookies de login (SID, HSID, ...) son HttpOnly y un export que las omita no sirve.
• Sesión válida (criterio que aplica el vault al importar): el archivo contiene las tres SID + HSID + SSID, o al menos LOGIN_INFO. Las que debe traer un export correcto: SID, HSID, SSID, SAPISID, LOGIN_INFO (y normalmente también APISID, __Secure-3PSID, ...).
• Un archivo con solo __Secure-3PSID (export parcial de algunas extensiones) no es una sesión: YouTube lo trata como anónimo y la membresía sigue bloqueada.

Cómo exportarlas (paso a paso)

1. Inicia sesión en youtube.com en tu navegador (Chrome, Brave o Firefox).
2. Instala la extensión "Get cookies.txt LOCALLY" (Chrome Web Store / Firefox Add-ons). La palabra LOCALLY importa: exporta en tu máquina sin mandar nada a un servidor.
3. Con youtube.com abierto, abre la extensión y exporta las cookies de youtube.com (formato Netscape por defecto).
4. Guarda el archivo (cookies.txt). Verifica que aparecen SID, HSID, SSID, SAPISID y LOGIN_INFO.

Cómo importarlas

Webapp (recomendado)

Sección Cookies de la UI:

• Arrastrar y soltar el cookies.txt (o selección manual). El vault lo copia a cookies/<uuid>.txt, analiza sesión/caducidad y lo registra con etiqueta.
• Importar desde navegador: lee las cookies directamente del navegador local (Brave por defecto). El navegador debe estar cerrado por completo — Chromium bloquea el archivo de cookies si el proceso vive, y el error que verás es "cookie store locked". Al importar así, la activación es automática.
• Si no hay ninguna activa, la primera que subas se activa sola.

CLI

yt-scraper --cookies ruta/a/cookies.txt scrape          # usar un archivo concreto
yt-scraper --cookies-from-browser brave scrape          # chrome|firefox|edge|brave

Además, al arrancar el CLI o la webapp, cualquier .txt suelto en cookies/ se adopta automáticamente al vault (auto_import_dir, idempotente).

Activación

Hay exactamente una cookie activa a la vez: CLI, webapp y watch usan esa si no se pasa --cookies. En la webapp puedes cambiar la activa (botón activate), probarla (test comprueba que la sesión sigue viva) y borrar las demás.

Rotación y caducidad

• Las cookies de login caducan (meses) o se invalidan si cierras sesión / cambias contraseña en ese navegador. Cuando el scrape vuelva a ver bloqueos de membresía o un chorreo de rate-limits, re-exporta y sube un archivo nuevo.
• El vault marca el estado expired según la fecha de expiración del propio archivo; el criterio has_session (SID+HSID+SSID o LOGIN_INFO) se comprueba en la importación y en el listado.
• No pasa nada por tener varias en el vault: solo la activa se usa.

Seguridad

• Son equivalentes a tu contraseña de Google para YouTube. Quien tenga el archivo puede usar tu sesión.
• cookies/ está en .gitignore — nunca las commitees, ni las pegues en un chat, ni las subas a ningún sitio.
• Si sospechas una fuga: cierra la sesión de YouTube en ese navegador (invalida las cookies) y re-exporta.