ReelGrabber — TODO

# ReelGrabber — TODO

## Done (MVP shipped)

### Auth & browser
- [x] `--login` wizard: opens browser visible, user logs in to Instagram, session saved
- [x] Login detection: if not logged in during `--collect`, prints clear `--login` instruction
- [x] Auto-import system cookies (browser-cookie3: Firefox only)
- [x] Cookie export: Playwright session → `config/instagram_cookies.txt` (Netscape format for yt-dlp)
- [x] yt-dlp uses exported cookie file first
- [x] Stale cookie detection: auto-refresh if >24h old
- [x] Consent banner auto-dismiss (cookie dialog, age verification, consent pages)
- [x] OS-specific error messages: PermissionError on Firefox

### Edge cases & robustness
- [x] yt-dlp missing: clear error + OS-aware install hint (apt/brew/pip/winget)
- [x] ffmpeg missing: clear error + OS-aware install hint (apt/brew/choco)
- [x] Browser not found: OS-aware hint for Firefox
- [x] yt-dlp download failure detection: check returncode, detect auth errors, show re-login tip
- [x] Cookie resolution moved outside download loop (performance)
- [x] Shared `deps.py` module for all dependency checks (platform-aware)

### Core features
- [x] CLI: collect, download, build-podcast, split, update, export csv, --all
- [x] FREE limits: 15 reels (last), 1 creator, no --update
- [x] PRO gate via `REELGRABBER_PRO=1`
- [x] Video-only flow (`--download` without build-podcast)

### Audio & metadata
- [x] Split/album mode: individual tagged MP3s per reel (`--split`, PRO only)
- [x] FREE users get medley only — individual MP3s deleted after merge
- [x] Podcast medley: merge all MP3s into one file (FREE & PRO)
- [x] Auto cover: profile pic upscaled to 500×500 min + ReelGrabber pill badge top-right (Apple Music style)
- [x] Cover embedded as `attached_pic` stream with explicit disposition → works in Lollypop, VLC, Apple Music
- [x] `album_artist` tag set → prevents cover bleed between artists in Lollypop/iTunes
- [x] Genre = Podcast on medley
- [x] Track number tag (`1/N`) on individual MP3s
- [x] Apple Music-style filenames: `username - Reel 01.mp3`, `Reel 02.mp3`, etc.
- [x] Custom cover: `--cover path/to/img` (PRO), badge always applied
- [x] Custom badge: place `assets/badge.png`
- [x] Clean auto metadata for ALL users: artist=creator name, album=creator Reels, title per track
- [x] Every individual MP3 tagged with ID3: artist, album, title, cover art embedded
- [x] Medley tagged with ID3: artist, album, title, cover art embedded
- [x] Custom metadata: `--title`, `--artist`, `--album` (PRO only)
- [x] FREE users who pass custom metadata get a clear message + auto fallback

### CI/CD & Delivery
- [x] Packaging Python officiel via `pyproject.toml` (installation `pip install .`)
- [x] Versionnement : Flag `--version` dans le CLI
- [x] Optimisation Git : fichier `.gitignore` robuste pour `venv`, caches et dossiers de `data/`
- [x] Intégration Continue (CI) : Test automatisé avec `pytest` et `ffmpeg` sur chaque Push GitHub (`ci.yml`)
- [x] Déploiement Continu (CD) : Création automatique de GitHub Releases lors des tags (`release.yml`)

### UX & polish
- [x] FREE upgrade messages: consistent, include `export REELGRABBER_PRO=1`
- [x] All messages in English
- [x] Auto-open videos folder after `--download` (Linux xdg-open, macOS open, Windows explorer)
- [x] Auto-open output folder after `--build-podcast`
- [x] Unit tests: 16 passing (downloader limits, branding, FREE/PRO metadata, split/medley, export) ✅

---

## To do (pre-launch)

- [ ] Demo video: 30s showing `--collect -> --build-podcast -> Apple Music/Lollypop`
- [ ] Reddit launch posts (r/selfhosted, r/productivity, r/marketing, r/automation)
- [ ] Direct outreach: Reply to the r/automation "Excel links" thread with ReelGrabber solution

### Marketing & Copywriting (next)
- [ ] Gumroad checkout page — description produit, bullet points, FAQ
- [ ] Email post-achat Gumroad — instructions activation + onboarding PRO
- [ ] Email de bienvenue FREE → nurture vers PRO
- [ ] Copy landing page — revoir hero headline, pricing CTA

### Analytics & tracking (PostHog)

#### Web (done)
- [x] `instrumentation-client.ts` — PostHog init (pageview + pageleave auto-captured)
- [x] `page_viewed` with source detection (utm_source, ref, referrer: reddit/hn/google)
- [x] `section_viewed` via IntersectionObserver (hero, problem, features, pricing, faq)
- [x] `pricing_viewed` when pricing section enters viewport
- [x] `hero_cta_clicked` on Try Free + Star GitHub + Get PRO buttons
- [x] `github_clicked` on all GitHub links
- [x] `gumroad_clicked` with location (pricing, cta_final)

#### CLI (done)
- [x] `src/reelgrabber/telemetry.py` — fire-and-forget PostHog wrapper, fails silently
- [x] Persistent `user_id` UUID in `~/.reelgrabber/config.json` (cross-session CLI identity)
- [x] `cli_collect_started` in grabber.py (tier, creator)
- [x] `cli_free_limit_hit` in grabber.py + downloader.py (reason: creator_limit | reel_limit)
- [x] `cli_podcast_built` in podcast.py (tier, mode: medley|split, reels_count)
- [x] `telemetry.identify(email)` ready for Gumroad email bridge (future)

### PRO activation flow

#### Code (done)
- [x] `src/reelgrabber/license.py` — Gumroad API verification + local storage
- [x] `is_pro()` — remplace `REELGRABBER_PRO=1` dans grabber, downloader, podcast (env var reste override dev)
- [x] `activate(license_key)` — vérifie via `https://api.gumroad.com/v2/licenses/verify`, stocke dans `~/.reelgrabber/config.json`
- [x] `./reelgrabber --activate <key>` — commande d'activation utilisateur
- [x] `./reelgrabber --status` — affiche le tier actuel
- [x] PostHog `identify(email)` appelé automatiquement à l'activation → bridge web→CLI

#### À faire (manuel)
- [x] **Créer le produit Gumroad** — https://reelgrabber.gumroad.com/l/reelgrabber-pro
- [x] **Permalink** `reelgrabber-pro` déjà dans `license.py` (défaut)
- [ ] **Tester une vraie activation** — créer coupon 100% sur Gumroad → acheter → tester `--activate <clé>`
  - Note: la clé "sample" du dashboard Gumroad ne passe PAS l'API verify, seule une vraie purchase fonctionne
- [ ] **Webhook Gumroad** (optionnel) → ping PostHog avec email à chaque achat

## Recently completed

- [x] `--last N` / `--first N` filtering for `--download` & `--export csv`
- [x] `--update`: full pipeline — collect new reels → download missing → rebuild podcast (PRO)
- [x] FREE/PRO parity: individual MP3s deleted for FREE, kept for PRO ✅
- [x] Badge placement fully proportional (ECHELLE_BADGE=15%)
- [x] Crossfade 2s (triangular) between tracks in medley
- [x] Full end-to-end CLI validation (16 tests passing) ✅

---

## Roadmap (post first sale)

### Phase 1 — Daily value
- [ ] Smart ordering by recency (use reel date if available)

### Phase 2 — Audio UX
- [ ] Chapter markers (1 reel = 1 chapter in the merged MP3)
- [ ] Clean filenames from reel titles

### Phase 3 — Filters & export
- [ ] `--top N`: sort by view count
- [ ] `--since DATE`: filter by date
- [ ] CSV export with filters (last N, date range)
- [ ] Include reel URL in CSV for marketers

### Phase 4 — Future
- [ ] FFmpeg smooth transitions / fades between reels
- [ ] AI-generated titles per reel
- [ ] Single video download by URL