yt-channel-scraper/docs/GETTING-STARTED.md

Getting Started — máquina nueva desde cero

De un equipo vacío a la webapp corriendo y el primer scrape hecho. Una sección por OS; salta a la tuya. Todo lo demás (arquitectura, CLI completo, config) está en el README.

Regla transversal: todos los comandos se ejecutan desde la raíz del repo (yt-channel-scraper/), porque las rutas de config.yaml se resuelven relativas al directorio de trabajo.

Windows

1. Python

PowerShell:

winget install Python.Python.3.12
# cierra y reabre la terminal para que entre en PATH; verifica:
python --version

2. Obtener el código

git clone <URL-del-gitea> yt-channel-scraper
cd yt-channel-scraper

3. Entorno + dependencias

# Opción A: uv (recomendado; respeta uv.lock)
winget install astral-sh.uv
uv sync --all-extras

# Opción B: venv + pip
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev,web,analysis]"

Extras: dev (tests), web (webapp), analysis (gráficos). Puedes instalar solo los que uses.

4. ffmpeg y node (opcionales)

• ffmpeg: solo necesario para yt-scraper audio / job de audio → winget install Gyan.FFmpeg.
• node: yt-dlp lo usa para resolver challenges de YouTube → winget install OpenJS.NodeJS.LTS.

Reabre la terminal tras instalar y verifica con ffmpeg -version / node -v.

5. Configuración

copy config.example.yaml config.yaml
notepad config.yaml

Cambia al menos channel_url (URL /videos de tu canal). Referencia de todas las claves: CONFIG.md.

6. Cookies (recomendado)

Sin cookies funciona, pero con sesión de YouTube reduce los bot-checks y desbloquea vídeos de membresía. Resumen: exporta cookies.txt desde tu navegador con la extensión "Get cookies.txt LOCALLY" (logueado a youtube.com) y arrástralo a la webapp, o usa --cookies. Guía completa: COOKIES.md.

7. Primer scrape (sin descargar nada)

.venv\Scripts\activate            # si usaste venv; con uv: uv run yt-scraper ...
yt-scraper scrape --dry-run --limit 10
yt-scraper scrape --limit 3       # primeras 3 notas en data/markdown/<Canal>/

8. Arrancar la webapp

Doble clic en start-server.bat. La primera vez pasa por scripts/doctor.ps1, que instala lo que falte (Python 3.12 vía winget + pip install -e ".[web]") y delega en scripts/start-server.ps1: busca puerto libre (8000–8100), arranca uvicorn, registra el PID en .run/server.info, comprueba /healthz y abre el navegador. Para parar: stop-server.bat.

Manual (debug): python -m uvicorn yt_scraper.webapp.app:app --host 127.0.0.1 --port 8000.

macOS (Apple Silicon)

1. Homebrew + Python

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install [email protected] ffmpeg node

Todas las dependencias Python publican wheels arm64; no hay compilación.

2-3. Código y entorno

git clone <URL-del-gitea> yt-channel-scraper
cd yt-channel-scraper

# Opción A: uv
brew install astral-sh.uv && uv sync --all-extras

# Opción B: venv + pip
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,web,analysis]"

4. ffmpeg / node

Ya instalados en el paso 1 (si los saltaste: brew install ffmpeg node).

5-6. Config y cookies

cp config.example.yaml config.yaml
$EDITOR config.yaml     # cambia channel_url

Cookies: COOKIES.md.

7. Primer scrape

yt-scraper scrape --dry-run --limit 10
yt-scraper scrape --limit 3

8. Arrancar la webapp

make setup    # primera vez: scripts/bootstrap.sh prepara todo lo que falte
make serve    # arranca uvicorn y abre el navegador
make stop     # para el servidor

Equivalente sin Makefile: scripts/bootstrap.sh && scripts/start-server.sh / scripts/stop-server.sh.

Linux (Debian/Ubuntu)

sudo apt update
sudo apt install -y python3 python3-venv python3-pip git ffmpeg nodejs   # nodejs si el repo lo empaqueta; si no, usa nodesource

El resto es idéntico a macOS: git clone → uv sync --all-extras (o venv + pip install -e ".[dev,web,analysis]") → cp config.example.yaml config.yaml → yt-scraper scrape --dry-run → make serve. En distros sin make: scripts/bootstrap.sh + scripts/start-server.sh.

Si tu distro trae Python < 3.10, instala uno moderno (pyenv, deadsnakes PPA en Ubuntu, o brew en Linux) — el paquete exige >=3.10.

Verificación final

uv run python -m pytest -q       # debe pasar la suite completa (~240 tests, sin red)
yt-scraper channels list         # tras el primer scrape: tu canal con sus vídeos

Troubleshooting

Síntoma	Causa	Arreglo
ModuleNotFoundError: yt_scraper tras mover/renombrar el repo	La instalación editable apunta a la ruta vieja	pip install -e ".[dev,web,analysis]" otra vez (o recrea el venv: uv sync --all-extras)
yt-scraper: command not found	Venv sin activar, o instalaste sin -e	Activa el venv, o usa uv run yt-scraper ..., o python -m yt_scraper.cli
Los paths apuntan a sitios raros (data/ vacío en otro lado)	Comandos ejecutados fuera de la raíz del repo	cd a la raíz; las rutas son relativas al CWD
file cannot be loaded because running scripts is disabled al lanzar un .ps1	PowerShell ExecutionPolicy restringido	powershell -ExecutionPolicy Bypass -File scripts\start-server.ps1, o Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
"puerto ocupado" / el navegador abre otra app	Resto de un servidor anterior en el puerto	Borra .run/server.info (estado obsoleto) o usa stop-server.bat / make stop; el arranque busca puerto libre 8000–8100
uv: command not found o trampolines rotos tras actualizar uv/Python	Los shims del venv quedaron inconsistentes	Ejecuta vía módulo: uv run python -m pytest -q, python -m yt_scraper.cli
Tests de red fallan / scrape con muchos error seguidos	Rate-limit de YouTube (sin cookies es más frecuente)	Espera; revisa delay en CONFIG.md; añade cookies (COOKIES.md)
ffmpeg no encontrado en yt-scraper audio	ffmpeg no está en PATH	winget install Gyan.FFmpeg / brew install ffmpeg / apt install ffmpeg, y reabre la terminal