sharon8811/newsread

NewsRead README-Demovideo

Ein Befehl erzeugt das kanonische Demo-mp4:

.claude/skills/demo-video/scripts/run_demo.sh [output.mp4]
# Standardausgabe: docs/assets/newsread-demo.mp4

Die Pipeline: Isoliertes Backend starten (:8010, newsread_test-DB) → Demoinhalte seeden → Frontend starten (:3010, Entwicklungsmodus) → eine skriptgesteuerte Playwright-Tour mit systemeigenem Chrome aufzeichnen (kopflos, mit animiertem Cursor und eingeblendeten Untertiteln) → mit ffmpeg in H.264-mp4 konvertieren. Server werden beendet und nur die Test-DB wird berührt – der echte Docker-Compose-Stack des Benutzers auf :3000/:8000 wird nie involviert.

Einstellungen: DEMO_SCHEME=dark|light (Standard dark), DEMO_SPEED=1.15 (Abspielgeschwindigkeit im mp4), CHROME_PATH (alternativer Browser-Pfad).

Voraussetzungen (normalerweise auf diesem Rechner bereits erfüllt)

• docker-compose Postgres auf :5433 hochgefahren (nur die newsread_test-DB wird verwendet)
• backend/.venv synchronisiert (uv sync), frontend/node_modules installiert
• ffmpeg im PATH, Google Chrome installiert
• Internetzugang – die Tour ruft live HN-Kommentare, Katalog-Feed-Vorschauen und picsum-Thumbnails ab. Offline zeichnet das Video zwar auf, aber diese Abschnitte sind degradiert.
• Ports 8010/3010 frei; der arq-Worker darf nicht gegen die Test-DB laufen (er würde versuchen, die unechten Demo-Feeds zu aktualisieren – harmlos aber laut).

Was die kanonische Tour zeigt (~80 s vor Beschleunigung)

1. Titelbild über dem ladenden Posteingang
2. Posteingang-Scroll – automatisches Lesen markiert Artikel beim Vorbeiscrollen; ungelesener Zähler tickt herunter
3. Flaggschiff-Artikel ("SQLite: 35% schneller als das Dateisystem") – KI-Zusammenfassung im Markdown
4. Verwandte Berichterstattung – gesetzte Embedding-Cluster erzeugen die Stufen "SELBE GESCHICHTE" und "VERWANDT"
5. Live-Hacker-News-Kommentare ("Kommentare anzeigen" im echten HN-Thread)
6. Katalog – Suche "nasa", Feed-Vorschau-Modal öffnen, mit Schnelleinstellungen abonnieren
7. Abspann

Die beweglichen Teile (zum Ändern der Demo bearbeiten)

• scripts/seed_demo_data.py – Demobenutzer (demo / demo-pass-1234), 4 fiktive Feeds, ~16 handgeschriebene Artikel mit Markdown-Teaser-Zusammenfassungen, handgefertigte pgvector-Embeddings (cosinus ~0.08 → "gleiche Geschichte", ~0.50 → "verwandt", zufällig ≈ orthogonal → ausgeblendet). Die HN-Thread-ID des Flaggschiffs wird live über die Algolia-API aufgelöst. Idempotent; lehnt jede DB-URL ab, die nicht newsread_test ist.
• scripts/record_tour.js – Die Szenenliste. Führt zuerst einen nicht aufgezeichneten Warmlauf durch, damit Next.js im Dev-Modus kompiliert und Bilder gecacht werden, bevor die Aufnahme beginnt.
• scripts/demo_helpers.js – Eingefügte Cursor-/Untertitel-/Titelbild-Overlays und Eingabeprimitive mit menschlichem Tempo. Scrollen verwendet echte Radereignisse, sodass sich der IntersectionObserver-Autoread genau wie bei einem Benutzer verhält.
• scripts/convert_to_mp4.sh – webm → H.264/yuv420p/faststart mp4.

Überprüfen des Ergebnisses

Versenden Sie kein Video, das Sie nicht angesehen haben. Extrahieren Sie Stichproben-Einzelbilder:

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

und lesen Sie einige – überprüfen Sie, ob Untertitel lesbar sind, die Abschnitte Zusammenfassung/verwandt/HN tatsächlich erschienen sind und der Abonnieren-Button auf "Abonniert" umgeschaltet hat. Fehlt ein Abschnitt, prüfen Sie das Recorder-Log und $WORK/backend.log (das Arbeitsverzeichnis wird zu Beginn des Laufs ausgegeben).

Einbinden in das README

GitHub rendert einen Video-Player nur für mp4s, die über den Web-Editor hochgeladen wurden (Drag-and-Drop während der Bearbeitung der README.md, erzeugt eine github.com/user-attachments/assets/...-URL) – eine per Pfad referenzierte .mp4 in der Versionsverwaltung wird NICHT inline gerendert. Also: Geben Sie das fertige mp4 an den Benutzer und sagen Sie ihm, es per Drag-and-Drop in das README auf github.com zu ziehen. Das Einchecken der Datei unter docs/assets/ als kanonische Kopie ist trotzdem in Ordnung.

Bekannte Fallstricke

• Abonnieren in der Katalog-Szene löst einen synchronen echten Abruf dieses Feeds auf dem Backend aus – wählen Sie zuverlässige Feeds (die Tour sucht "nasa"); die Wartezeit erlaubt 30 s.
• Niemals über POST /api/feeds seeden – es ruft synchron die Feed-URL ab. Das Seed-Skript fügt ORM-Zeilen direkt ein.
• Die Frontend-KI-Zusammenfassungs-Benutzeroberfläche wird vollständig ausgeblendet, wenn /api/ai/status "nicht konfiguriert" meldet; run_demo.sh exportiert einen Platzhalter NEWSREAD_OPENAI_API_KEY, damit sie angezeigt wird. Es wird nie ein LLM aufgerufen: Zusammenfassungen sind vorausgefüllt, und der Zusammenfassungs-Endpunkt macht einen Kurzschluss, wenn sie vorhanden sind.
• Der Embedding-model-Tag auf gesetzten Vektoren muss dem NEWSREAD_OPENAI_EMBEDDING_MODEL des Servers entsprechen – run_demo.sh exportiert ihn für beide Prozesse; führen Sie das Seed-Skript nicht mit anderen Umgebungsvariablen als der Server.