# YouTube Subtitle Download - Setup & Usage

## Overview

Script pentru descărcarea subtitrărilor YouTube cu protecție rate limit și retry progresiv.

## Cerințe

1. **yt-dlp** - instalat global
2. **Deno** - pentru JavaScript challenges (`~/.deno/bin/deno`)
3. **Cookies** - din cont YouTube secundar (`credentials/youtube-cookies.txt`)

## Setup Cookies (o singură dată)

### Opțiunea 1: Extensie Browser (Recomandat)

1. Creează/folosește un cont Google secundar (pentru securitate)
2. Loghează-te pe youtube.com cu acel cont
3. Instalează extensia [Get cookies.txt LOCALLY](https://chromewebstore.google.com/detail/get-cookiestxt-locally/cclelndahbckbenkjhflpdbgdldlbecc)
4. Click pe extensie → Export
5. Pune fișierul în `credentials/youtube-cookies.txt`

### Opțiunea 2: yt-dlp direct (dacă ai browser local)

```bash
yt-dlp --cookies-from-browser firefox --cookies credentials/youtube-cookies.txt "https://youtube.com"
```

## Utilizare

### Download manual

```bash
# Un video
python3 tools/yt_download.py "https://youtu.be/VIDEO_ID"

# Mai multe video-uri (cu pauze automate)
python3 tools/yt_download.py URL1 URL2 URL3

# Verifică status rate limit
python3 tools/yt_download.py
```

### Exit codes

| Code | Semnificație |
|------|--------------|
| 0 | Success - toate video-urile procesate |
| 1 | Erori parțiale - unele video-uri au eșuat |
| 2 | Rate limited (429) - s-a oprit, retry mai târziu |
| 3 | În cooldown - așteaptă timpul de retry |

## Rate Limit Protection

### Prevenire

- **Cookies obligatorii** - fără cookies, rate limit vine rapid
- **Sleep 20s** între video-uri
- **Max 30 video-uri** per sesiune

### Progressive Retry

Când primim 429:

```
Prima dată  → Retry în 2 ore
A doua oară → Retry în 4 ore
A treia oară → Retry în 24 ore
Success → Reset counter
```

### State File

Rate limit state salvat în `memory/youtube-rate-limit.json`:

```json
{
  "last_429": "2026-02-03T07:00:00",
  "retry_count": 1,
  "blocked_until": "2026-02-03T09:00:00"
}
```

## Integrare în Jobs

### night-execute (23:00 București)
- Verifică rate limit înainte de a începe
- Procesează max 30 video-uri din `approved-tasks.md`
- Creează note în `memory/kb/youtube/`

### night-execute-late (03:00 București)
- Continuă cu restul video-urilor
- Mută task-uri pentru noaptea următoare

## Troubleshooting

### "Signature solving failed"
- Verifică că deno e instalat: `~/.deno/bin/deno --version`
- Scriptul folosește `--remote-components ejs:github` pentru a descărca solver-ul

### "429 Too Many Requests"
- Verifică `memory/youtube-rate-limit.json` pentru când e retry
- Asigură-te că folosești cookies valide
- Nu rula manual când job-urile rulează

### Cookies expirate
- Cookies expiră după câteva săptămâni
- Re-exportă din browser când nu mai funcționează

## Securitate

- **Folosește cont secundar** pentru cookies
- Fișierul cookies NU e în git (`.gitignore`)
- Nu partaja `credentials/youtube-cookies.txt`

## Fișiere

| Fișier | Scop |
|--------|------|
| `tools/yt_download.py` | Script principal |
| `credentials/youtube-cookies.txt` | Cookies YouTube |
| `memory/youtube-rate-limit.json` | State rate limit |
| `~/.deno/bin/deno` | JavaScript runtime |