Files

T

urieljareth 450aee216d docs: documentacion completa para humanos y agentes IA

- README reescrito: ejemplos CLI corregidos (flags van en el subcomando scrape),
  webapp+doctor documentados, requisitos por OS, cookies, datos generados, migracion de maquina
- CLAUDE.md actualizado: conteo de tests, refs de linea reparadas, scripts nuevos,
  checklist de actualizacion de docs
- AGENTS.md nuevo: entrada estandar para cualquier agente de codigo (mapa de modulos,
  comandos, reglas de oro, punteros a docs)
- docs/GETTING-STARTED.md: de cero a webapp por OS con troubleshooting
- docs/CONFIG.md: referencia completa de las ~25 claves de config
- docs/COOKIES.md: adquisicion, import (web/navegador/CLI), rotacion y seguridad
- docs/backlog.md reemplaza OPPORTUNITIES.md (distilado: shipped vs pendiente)
- auditorias movidas a docs/audits/ y CLIPPER-COMPARISON-AUDIT.md versionado

2026-09-10 00:32:32 -06:00

4.2 KiB

Raw Permalink Blame History

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)

Inicia sesión en youtube.com en tu navegador (Chrome, Brave o Firefox).
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.
Con youtube.com abierto, abre la extensión y exporta las cookies de youtube.com (formato Netscape por defecto).
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.

4.2 KiB Raw Permalink Blame History