sharon8811/newsread

Vidéo de démonstration README NewsRead

Une seule commande produit le mp4 de démonstration canonique :

.claude/skills/demo-video/scripts/run_demo.sh [output.mp4]
# sortie par défaut : docs/assets/newsread-demo.mp4

Le pipeline : démarre un backend isolé (:8010, base newsread_test) → préremplit le contenu de démonstration → démarre le frontend (:3010, mode dev) → enregistre une visite Playwright scriptée avec le Chrome système (headless, curseur animé + sous-titres incrustés) → convertit en mp4 H.264 avec ffmpeg. Les serveurs sont arrêtés et seule la base de test est touchée — la pile docker-compose réelle de l'utilisateur sur :3000/:8000 n'est jamais impliquée.

Paramètres : DEMO_SCHEME=dark|light (sombre par défaut), DEMO_SPEED=1.15 (accélération de la lecture dans le mp4), CHROME_PATH (binaire navigateur alternatif).

Prérequis (généralement déjà présents sur cette machine)

• docker-compose Postgres démarré sur :5433 (seule la base newsread_test est utilisée)
• backend/.venv synchronisé (uv sync), frontend/node_modules installé
• ffmpeg dans le PATH, Google Chrome installé
• Accès Internet — la visite récupère les commentaires HN en direct, les aperçus du catalogue de flux et les vignettes picsum. Hors ligne, la vidéo s'enregistre quand même mais ces sections sont dégradées.
• Les ports 8010/3010 doivent être libres ; le worker arq ne doit pas tourner contre la base de test (il essaierait d'actualiser les flux de démo factices — inoffensif mais bruyant).

Contenu de la visite canonique (~80s avant accélération)

1. Carte titre au-dessus de la boîte de réception en chargement
2. Défilement de la boîte de réception — la lecture automatique marque les articles au passage ; le compteur de non-lus diminue
3. Article phare (« SQLite : 35% plus rapide que le système de fichiers ») — résumé IA en markdown
4. Couverture associée — les regroupements d'embeddings préremplis produisent des niveaux MÊME HISTOIRE + connexes
5. Commentaires Hacker News en direct (« Afficher les commentaires » sur le fil HN réel)
6. Catalogue — recherche « nasa », ouvre une modale d'aperçu de flux, s'abonne avec les paramètres rapides
7. Carte de fin

Les composants mobiles (modifiez-les pour changer la démo)

• scripts/seed_demo_data.py — utilisateur démo (demo / demo-pass-1234), 4 flux fictifs, ~16 articles rédigés à la main avec résumés en markdown, embeddings pgvector artisanaux (cosinus ~0,08 → « même histoire », ~0,50 → « connexe », aléatoire ≈ orthogonal → caché). L'identifiant du fil HN de l'article phare est résolu en direct via l'API Algolia. Idempotent ; refuse toute URL de base qui n'est pas newsread_test.
• scripts/record_tour.js — la liste des scènes. Effectue d'abord un passage de préchauffage non enregistré pour que le mode dev de Next compile et que les images soient mises en cache avant l'enregistrement.
• scripts/demo_helpers.js — incrustations de curseur, sous-titres, cartes titre et primitives de saisie au rythme humain. Le défilement utilise de vrais événements de molette pour que le comportement auto-lecture par IntersectionObserver soit exactement le même que pour un utilisateur.
• scripts/convert_to_mp4.sh — webm → H.264/yuv420p/faststart mp4.

Vérification du résultat

Ne livrez pas une vidéo que vous n'avez pas regardée. Extrayez des images de contrôle :

ffmpeg -i docs/assets/newsread-demo.mp4 -vf fps=1/6 /tmp/demo-frames/f%02d.png

et examinez-en quelques-unes — vérifiez que les sous-titres sont lisibles, que les sections résumé/connexe/HN sont bien apparues, et que le bouton d'abonnement est passé à « Abonné ». Si une section manque, consultez le journal de l'enregistreur et $WORK/backend.log (le répertoire de travail est affiché au début de l'exécution).

Intégration dans le README

GitHub ne rend un lecteur vidéo que pour les mp4 téléversés via son éditeur web (glisser-déposer lors de l'édition de README.md, ce qui génère une URL de type github.com/user-attachments/assets/...) — un fichier .mp4 commité et référencé par un chemin NE sera PAS rendu en ligne. Donc : remettez le mp4 final à l'utilisateur et dites-lui de le glisser-déposer dans le README sur github.com. Commiter le fichier sous docs/assets/ comme copie canonique reste tout à fait correct.

Pièges connus

• L'abonnement dans la scène du catalogue déclenche une récupération synchrone réelle de ce flux côté backend — choisissez des flux fiables (la visite recherche « nasa ») ; l'attente autorise 30s.
• Ne jamais préremplir via POST /api/feeds — cela récupère l'URL du flux de manière synchrone. Le script de préremplissage insère directement les lignes ORM.
• L'interface IA de résumé du frontend se cache entièrement si /api/ai/status signale un état non configuré ; run_demo.sh exporte une NEWSREAD_OPENAI_API_KEY fictive pour qu'elle s'affiche. Aucun LLM n'est jamais appelé : les résumés sont préremplis, et le point de terminaison de résumé court-circuite lorsqu'ils existent.
• L'étiquette model d'embedding des vecteurs préremplis doit correspondre au NEWSREAD_OPENAI_EMBEDDING_MODEL du serveur — run_demo.sh l'exporte pour les deux processus ; n'exécutez pas le script de préremplissage avec un environnement différent de celui du serveur.