From 71dd660d0189cfa8feae373c3cb891c3e19bdf21 Mon Sep 17 00:00:00 2001 From: ZeasyAlex Date: Wed, 9 Sep 2026 11:36:34 +0200 Subject: [PATCH] Uebergabe: Stand, offene Punkte, Einstieg fuer den naechsten Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_013VTGjd92LsDDWF3frd9FTB --- README.md | 15 ++++-- docs/handoff.md | 113 ++++++++++++++++++++++++++++++++++++++++++ docs/offene-punkte.md | 82 ++++++++++++++++++++++++++++++ 3 files changed, 206 insertions(+), 4 deletions(-) create mode 100644 docs/handoff.md create mode 100644 docs/offene-punkte.md diff --git a/README.md b/README.md index 8b52773..d8457ef 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,9 @@ Dazu der Dienst, der unter allen anderen liegt: - [`docs/05-setup.md`](docs/05-setup.md) — Lokal einrichten - [`docs/06-hebel-analyse.md`](docs/06-hebel-analyse.md) — **Womit anfangen und warum** - [`docs/07-mvp-plan.md`](docs/07-mvp-plan.md) — **MVP „Clip-Knopf": Umfang, Scheiben, Zeitplan** +- [`docs/handoff.md`](docs/handoff.md) — **Übergabe: Stand, Fallstricke, wo weitermachen** +- [`docs/offene-punkte.md`](docs/offene-punkte.md) — was noch fehlt +- [`docs/obs-layout.md`](docs/obs-layout.md) — die Layout-Vorgabe für OBS - [`docs/projects/`](docs/projects/) — je ein Spec-Dokument pro Tool - [`docs/decisions/`](docs/decisions/) — Architekturentscheidungen (ADRs) @@ -62,10 +65,14 @@ Datei im Projekt ([ADR-0005](docs/decisions/ADR-0005-zugangsdaten.md)). ## Aktueller Stand -Scheiben **S0 und S1** des MVP „Clip-Knopf" sind fertig: Container-Toolchain, -Einrichtung im Browser, Twitch-Auth, Datenbank und Chat-Aufnahme. Als Nächstes -S2 — OBS-Anbindung und der `!clip`-Trigger. Fahrplan: -[`docs/07-mvp-plan.md`](docs/07-mvp-plan.md). +Vier von sieben Scheiben des MVP „Clip-Knopf" sind gebaut: Container-Toolchain, +Einrichtung im Browser, Twitch-Auth, Datenbank, Chat-Aufnahme, OBS-Anbindung mit +`!clip`, 9:16-Render und Untertitel. 53 Tests grün. + +Offen: die Abnahme der OBS-Anbindung an einem laufenden OBS, dann S5 — +Onboarding-Assistent und Sichtungsseite. + +Details: [`docs/handoff.md`](docs/handoff.md) ## Tests diff --git a/docs/handoff.md b/docs/handoff.md new file mode 100644 index 0000000..f5a2ef8 --- /dev/null +++ b/docs/handoff.md @@ -0,0 +1,113 @@ +# Übergabe + +Stand **2026-09-09**. Wer hier weitermacht, sollte diese Seite zuerst lesen und +danach [`07-mvp-plan.md`](07-mvp-plan.md). + +## Wo das Projekt steht + +Vier von sieben Scheiben des MVP „Clip-Knopf" sind gebaut. Die Kette vom +Auslöser bis zum fertigen Short steht **im Code vollständig** — geprüft ist sie +überall dort, wo es ohne Abdus Stream-PC ging. + +| Scheibe | Stand | Nachweis | +|---|---|---| +| S0 Container + Toolchain | fertig | `check-env` ohne harte Fehler | +| S1 Einrichtung, Auth, DB, Chat | fertig | Daemon läuft, Chat verbunden, Secrets verschlüsselt | +| S2 OBS + `!clip` | Code fertig, **nicht abgenommen** | braucht laufendes OBS | +| S3 9:16-Render | fertig | Durchlauf mit künstlicher Aufnahme | +| S4 Untertitel | fertig | Durchlauf mit echtem deutschen Clip | +| S5 Onboarding + Sichtung | offen | — | +| S6 Erstchatter-Begrüßung | offen | — | + +53 Tests, alle grün. Vollständige Liste dessen, was noch fehlt: +[`offene-punkte.md`](offene-punkte.md). + +## Was jemand wissen muss, bevor er etwas anfasst + +**Es gibt keine Abhängigkeiten und keinen Build.** Node 24 bringt SQLite, +WebSocket, `fetch` und die Ausführung von TypeScript mit. `node docker/entrypoint.ts` +läuft direkt. Deshalb gilt: nur *löschbare* TypeScript-Syntax — keine `enum`, +keine Parameter-Properties im Konstruktor, keine `namespace`. `erasableSyntaxOnly` +in der `tsconfig.json` erzwingt das und hat schon einen echten Fehler gefangen. + +**Alles läuft unter einem Dach**, einem Prozess in einem Container. Schwere +Arbeit (ffmpeg, whisper) läuft als Kindprozess und darf abstürzen. Der Ingest +darf nie sterben — was er nicht mitschreibt, ist für immer weg. + +**Zugangsdaten kommen aus der Weboberfläche**, nicht aus einer Datei. Sie liegen +verschlüsselt in einem Docker-Volume, bewusst außerhalb der Datenbank, weil die +gesichert und dabei auf die Windows-Seite kopiert wird. + +**Rohdateien gehören ins Arbeits-Volume**, nicht in den Windows-Bind-Mount. Über +die WSL2-Brücke zu encodieren kostet ein Vielfaches. Dagegen habe ich einmal +selbst verstoßen — der Fehler fiel erst in S3 auf. + +Die Begründungen stehen in [`decisions/`](decisions/), sechs ADRs. Wer eine +davon umwerfen will, sollte sie vorher lesen; jede hat einen Grund, der beim +Bauen aufgetaucht ist. + +## Loslegen + +```powershell +git clone https://git.zeasy.dev/ZeasyAlex/abdulive.git +cd abdulive +Copy-Item config\config.example.yaml config\config.yaml + +docker compose build +docker compose run --rm toolkit check-env +docker compose run --rm toolkit fetch-model # ca. 465 MB +docker compose up -d +``` + +Dann `http://localhost:4792/setup` öffnen. Ausführlich in +[`05-setup.md`](05-setup.md). + +Tests: + +```powershell +docker run --rm -v "${PWD}:/app" -w /app node:24-bookworm-slim ` + node --test "packages/**/*.test.ts" "apps/**/*.test.ts" +``` + +Typprüfung (das Einzige, wofür npm gebraucht wird): + +```powershell +docker run --rm -v "${PWD}:/app" -w /tmp node:24-bookworm-slim sh -c ` + "npm i -s typescript@5.9 @types/node && cd /app && /tmp/node_modules/.bin/tsc --noEmit --typeRoots /tmp/node_modules/@types" +``` + +## Die drei Dinge, die Abdu tun muss + +1. **Zwei Twitch-Apps anlegen** (dev.twitch.tv/console/apps), Redirect-URI + `http://localhost:4792/callback`. Client-ID und Secret danach auf der + Einrichtungsseite eintragen — nicht in eine Datei. +2. **OBS einrichten**: obs-websocket an (Port 4455), Wiedergabepuffer 90 s, + Hotkey auf „Wiedergabepuffer speichern", getrennte Audiospuren. +3. **Layout umstellen** nach [`obs-layout.md`](obs-layout.md). Die + Ausrichtungsvorlage in OBS über die Szene legen, Quellen einpassen, wieder + ausblenden. Danach `calibrate` zur Kontrolle. + +Ohne Punkt 1 liest das Toolkit den Chat anonym mit und kann nichts senden. +Ohne Punkt 2 gibt es keine Clips. Ohne Punkt 3 sitzt der Ausschnitt schief. + +## Wo ich weitermachen würde + +**S5.** Nicht wegen des Codes, sondern weil das Werkzeug ohne Einrichtungs- +Assistenten und Sichtungsseite für Abdu nicht bedienbar ist. Die Kette +funktioniert, aber sie hat noch keine Oberfläche, die jemand ohne Erklärung +benutzt. Abnahmekriterium steht im Plan: *Ein Fremder kommt von „nichts +eingerichtet" bis zum ersten eigenen Clip, ohne die Dokumentation zu lesen.* + +Davor, wenn Gelegenheit ist: **S2 an einem laufenden OBS abnehmen**. Das ist +die einzige ungeprüfte Stelle in der ganzen Kette, und alles Weitere hängt +daran. + +## Womit ich nicht zufrieden bin + +Die Untertitel sind brauchbar, nicht gut. `ggml-small` verhört sich hörbar +(„Danke" wurde „Dank es"), die Schrift ist unauffällig, und das fortlaufende +Einfärben ist nicht der Stil, der auf Shorts trägt. Sechs konkrete +Verbesserungen stehen in [`offene-punkte.md`](offene-punkte.md). + +Und: Das Aufräumen im Arbeits-Volume fehlt komplett. Rohdateien sammeln sich +unbegrenzt an. Das ist die Lücke, die als Erstes weh tun wird. diff --git a/docs/offene-punkte.md b/docs/offene-punkte.md new file mode 100644 index 0000000..eae348d --- /dev/null +++ b/docs/offene-punkte.md @@ -0,0 +1,82 @@ +# Offene Punkte + +Stand 2026-09-09. Sortiert nach Dringlichkeit, nicht nach Aufwand. +Erledigtes wandert raus, nicht ins Archiv — die Historie steht in Git. + +## Blockiert, bis jemand am Stream-PC sitzt + +- [ ] **S2 abnehmen.** Der obs-websocket-Client ist gebaut und getestet, soweit + es ohne OBS geht: Anmeldeverfahren, Pfadübersetzung, Warten auf die + fertige Datei. Ungeprüft ist das tatsächliche Gespräch mit einem + laufenden OBS. Bis dahin ist `!clip` nicht bewiesen. +- [ ] **Strecke IRC → Datenbank im Livebetrieb.** Die Teile sind einzeln + getestet, die Verdrahtung wird erst beim ersten echten Stream sichtbar. +- [ ] **Layout umstellen** nach [`obs-layout.md`](obs-layout.md) und danach + `calibrate` laufen lassen. + +## Bekannte Lücke im Betrieb + +- [ ] **Aufräumen im Arbeits-Volume.** Jede Rohdatei landet unter `/work//` + und bleibt dort liegen. Bei fünf Clips pro Stream und mehreren hundert MB + je Datei läuft das Volume in wenigen Wochen voll. Gebraucht wird eine + Aufbewahrungsregel — Vorschlag: Rohdateien der letzten 30 Clips behalten, + ältere löschen, sobald `status = 'rendered'`. **Das ist der Punkt, der als + Erstes weh tun wird.** +- [ ] Was passiert, wenn der Rechner mitten im Rendern ausgeht? Clips bleiben + auf `status = 'raw'` stehen und werden nach Neustart nicht wieder + eingereiht. + +## Untertitel verbessern + +Der Durchlauf am echten Clip war brauchbar, aber nicht gut. Was auffiel: + +- [ ] **Größeres Modell testen.** `ggml-small` machte aus „Danke" ein „Dank es" + und aus „Sabrina" ein „Savina". `medium` ist etwa dreimal so langsam — + bei 30-Sekunden-Clips nach dem Stream ist das egal. Vergleich an + demselben Clip fahren und entscheiden. +- [ ] **Wörter mit niedriger Wahrscheinlichkeit prüfen.** Whisper liefert je + Token ein `p`. Bei den Fehlgriffen lag es unter 0,15, bei korrekten + Wörtern über 0,9. Entweder weglassen oder gedimmt anzeigen. +- [ ] **Schrift.** DejaVu Sans ist im Image vorhanden, aber unauffällig. Auf + Shorts trägt eine fettere, rundere Schrift (Montserrat ExtraBold, + Inter Black). Braucht eine Schriftdatei im Image und eine Lizenzprüfung. +- [ ] **Nur das aktuelle Wort hervorheben** statt fortlaufend einzufärben. Der + heutige Karaoke-Effekt lässt gesprochene Wörter gefärbt stehen; der Stil, + der auf TikTok funktioniert, hebt genau ein Wort hervor. Braucht mehrere + Dialogzeilen je Zeile statt einer. +- [ ] **Position prüfen.** 340 px Abstand nach unten ist geschätzt, nicht + gemessen. An einem echten Handy gegen die TikTok-, Reels- und + Shorts-Oberfläche halten. +- [ ] **Nur transkribieren, wenn Abdu spricht.** Bei getrennten Tonspuren + reicht ein Pegelfilter auf der Mikrofonspur, damit aus Stille kein + erfundener Text wird. + +## Streamsetup + +- [ ] **Live-Captions verschieben.** Sie liegen im Gameplay-Band und sind fest + eingebrannt. Zwei Vorschläge stehen in [`obs-layout.md`](obs-layout.md). +- [ ] **Spieluntertitel abschalten.** +- [ ] **Bessere Bildquelle für die Facecam** — Plugin `Source Record` oder + `Aitum Vertical`. Damit entfällt die 2,25-fache Vergrößerung. Lohnt sich + erst, wenn regelmäßig Shorts entstehen. + +## Nach dem MVP + +- [ ] **Spitzen-Erkennung scharf schalten.** Sie läuft mit und schreibt jeden + Kandidaten samt Punktzahl in `events`. Sobald ein paar Streams + protokolliert sind: an echten Daten kalibrieren, dann `armed: true`. +- [ ] Automatischer Upload zu TikTok und YouTube. +- [ ] EventSub für Follows, Subs, Raids — bisher reicht IRC plus Polling. +- [ ] Follower-Prüfung bei `!clip`, falls die Abklingzeiten nicht reichen. +- [ ] Die übrigen acht Werkzeuge, siehe [`04-roadmap.md`](04-roadmap.md). + +## Kleinigkeiten + +- [ ] `docker compose run` reicht ein TTY durch, dadurch schreibt die + Fortschrittsanzeige `\r`-Zeilen ins Protokoll. Mit `-T` sauber, aber + unschön als Standard. +- [ ] `ldconfig` meldet beim Bauen `libwhisper.so.1 is not a symbolic link`. + Funktioniert, ist aber unsauber. +- [ ] `docs/05-setup.md` nennt ffmpeg 6+; im Image steckt 5.1.9 aus Debian + bookworm. Für unseren Filtergraph irrelevant, die Angabe stimmt trotzdem + nicht.