ReelGrabber — TODO

Done (MVP shipped)

Auth & browser

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

Edge cases & robustness

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

Core features

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

Audio & metadata

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

CI/CD & Delivery

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

UX & polish

• FREE upgrade messages: consistent, include export REELGRABBER_PRO=1
• All messages in English
• Auto-open videos folder after --download (Linux xdg-open, macOS open, Windows explorer)
• Auto-open output folder after --build-podcast
• 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)

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

CLI (done)

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

PRO activation flow

Code (done)

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

À faire (manuel)

• Créer le produit Gumroad — https://reelgrabber.gumroad.com/l/reelgrabber-pro
• 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

• --last N / --first N filtering for --download & --export csv
• --update: full pipeline — collect new reels → download missing → rebuild podcast (PRO)
• FREE/PRO parity: individual MP3s deleted for FREE, kept for PRO ✅
• Badge placement fully proportional (ECHELLE_BADGE=15%)
• Crossfade 2s (triangular) between tracks in medley
• 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