first commit

.vibe/bg1-projectplan.md

@@ -0,0 +1,155 @@
+# Projektbeschreibung (Extended)
+## Baldur’s Gate EE – Dual-Language Live-TTS System
+
+## Zielsetzung
+Das Projekt entwickelt ein System, das **BG1 Enhanced Edition**
+während des Spielens in **Deutsch und Englisch** automatisch vertont
+und per Hotkey zwischen den Sprachen umschaltet.
+
+**Keine Änderung an der Engine.
+Kein Wine-Gefrickel.
+Saubere, modulare Architektur.**
+
+---
+
+# Architekturübersicht
+
+## ASCII-Diagramm – Systemkomponenten
+
+```
++-----------------+          +------------------+
+|  BG1EE (Game)   |          |  Dialog-Hook     |
+|-----------------|  ID -->  |  Lua Listener    |
+| Dialog Window   |          | (OnNodeChange)   |
++-----------------+          +------------------+
+                                      |
+                                      v
+                           +----------------------+
+                           |  TTS Controller      |
+                           |  (FastAPI Service)   |
+                           +----------+-----------+
+                                      |
+                     +----------------+----------------+
+                     |                                 |
+                     v                                 v
+        +-----------------------+         +-----------------------+
+        | TLK+DLG DB (JSON)    |         |   TTS Engines         |
+        | text_de, text_en     |         |  Melo, Kokoro, F5     |
+        +----------+------------+         +-----+----------------+
+                   |                            |
+                   v                            |
+         +------------------+                   |
+         | Audio Cache      |                   |
+         | lineID_lang.wav  | <-----------------+
+         +--------+---------+
+                  |
+                  v
+         +------------------+
+         | Audio Playback   |
+         +------------------+
+```
+
+---
+
+# Datenfluss-Diagramm
+
+```
+Spiel zeigt Dialog → Hook erkennt Node → sendet ID → Backend prüft Cache:
+  Wenn vorhanden → Sofort abspielen
+  Wenn nicht      → Text(DE/EN) holen → TTS generieren → speichern → abspielen
+Sprache wechseln  → Backend toggelt Runtime-Flag
+```
+
+---
+
+# Datenmodell (vereinfacht)
+
+```json
+{
+  "id": 47281,
+  "speaker": "Imoen",
+  "text": {
+    "de": "Hey, wach auf! Es ist etwas im Busch!",
+    "en": "Hey, wake up! Something's not right!"
+  },
+  "options": [
+    { "id": 47282, "reply_de": "Was ist los?", "reply_en": "What's happening?" }
+  ]
+}
+```
+
+---
+
+# TTS-Backend Architektur
+
+- **FastAPI**
+- Endpunkte:
+  - `/speak/<id>`
+  - `/set_language/de|en`
+  - `/status`
+  - `/cache/clear`
+- Intern:
+  - DB-Lookup → Text holen
+  - Engine auswählen
+  - WAV generieren
+  - Abspielen
+  - Logging (Dialog-ID, Dauer, Engine, Sprache)
+
+---
+
+# Projektplan (Roadmap)
+
+## Phase 1 – Extract (READY TO START)
+- BG1EE installieren
+- Near Infinity einrichten
+- Deutsch & Englisch TLK extrahieren
+- DLG-Bäume exportieren
+- JSON vereinheitlichen
+
+## Phase 2 – Parser & Datenmodell
+- Python-Modul bauen
+- Konsistenzprüfungen (IDs müssen matchen)
+- NPC-Zuordnungen
+- Szenenstruktur optional
+
+## Phase 3 – TTS Service
+- FastAPI-Server
+- Sprache als Runtime-State
+- Engine-Abstraktionslayer
+- Audio-Caching
+- Playback-Pipeline
+
+## Phase 4 – Lua Ingame Listener
+- BGEE Mod erstellen
+- Events `OnDialogStart` + `OnDialogNodeChange` abgreifen
+- HTTP Requests an TTS Server
+
+## Phase 5 – Live Umschaltung
+- Hotkey-System
+- Ereignis → REST → TTS-State ändern
+- Visual Logging
+
+## Phase 6 – Testing
+- Kapitel 1 vollständige Tests
+- Langtext-Szenen (Gorion, Imoen, Candlekeep)
+- Performance testen
+- Audio-Lag eliminieren
+
+## Phase 7 – Erweiterungen
+- individuelle NPC-Stimmen
+- Emotionserkennung (stimmungsbasierte Modelle)
+- Prosodie-Mapping
+- BG2EE Integration
+- Mod-Support
+
+---
+
+# Vision
+Ein vollständig automatisiertes, zweisprachiges,
+KI-vertontes Baldur’s Gate EE –
+mit Möglichkeit zum sofortigen Umschalten, eigenen Voices,
+und einer Engine-agnostischen Pipeline,
+die auf jeden Infinity-Engine Titel angewendet werden kann.
+
+---
+

.vibe/bg1-session-resumee.md1

@@ -0,0 +1,67 @@
+# Session-Resümee (Extended)
+## Baldur’s Gate Enhanced Edition – Dual-Language Live-TTS Projekt
+**Stand:** 2025-12-07
+
+## Übersicht
+Wir haben die Herangehensweise für ein vollautomatisches, zweisprachiges
+Text-to-Speech-System für **Baldur’s Gate 1 Enhanced Edition** entworfen.
+
+Ziel:
+→ Das Spiel zeigt einen Dialog
+→ wir erkennen ihn in Echtzeit
+→ erzeugen passende Audioausgabe (DE oder EN)
+→ Umschalten der Sprache jederzeit möglich
+→ Keine Spielmodifikation außer einem kleinen Listener.
+
+---
+
+## Kernentscheidungen
+### ✔ Beste Extraktionsmethode
+- Nutzung der originalen **TLK-Dateien** (DE & EN)
+- Nutzung der **DLG-Dateien** (Dialogbäume)
+- Alles wird in **JSON** überführt
+- IDs sind in allen Sprachen 1:1 identisch → perfekt für Dual-Pipeline
+
+### ✔ Live-TTS Architektur
+- BGEE löst Dialog-Events via Lua aus
+- Ein externes TTS-Backend empfängt IDs
+- Backend spielt Audio sofort ab
+- Interner State: aktive Sprache (de/en)
+- Wechsel per Hotkey, CLI oder API
+
+### ✔ Die Technik bleibt sauber
+- Kein OCR, kein Bildschirm-Scraping
+- Keine Hooks in Engine-Memory
+- Keine Modding-Orgien
+- Saubere, reproduzierbare Pipeline
+- Ideal für spätere Erweiterung auf BG2EE, IWD, PST
+
+---
+
+## Erweiterte Erkenntnisse
+- BG1EE ist extrem modfreundlich → Lua-Injection ist minimaler Aufwand
+- Sämtliche Texte lassen sich 1:1 extrahieren
+- TTS-Qualität ist mit Melo/Kokoro/F5 deutlich über 90er-Studio-Level
+- Das System kann beliebig erweitert werden (NPC-eigene Stimmen, Emotionen)
+
+---
+
+## Risiken & offene Punkte
+- Hook-Timing muss getestet werden (Dialogwechsel)
+- Manche Mods überschreiben DLG-Pfade → wir brauchen optionales Rescan
+- TTS-Caching muss sauber gebaut werden (Performance)
+
+---
+
+## Nächste Schritte (konkret)
+1. BG1EE installieren
+2. TLK & DLG extrahieren (Near Infinity)
+3. Parser bauen
+4. Datenbank erzeugen
+5. FastAPI-TTS-Backend aufsetzen
+6. Lua-Hook-Mod erstellen
+7. Hotkey-Switch implementieren
+8. Erste Spielszene voll vertonen
+
+---
+

README.md

@@ -0,0 +1,145 @@
+# Projektstruktur & README
+
+## 📁 Empfohlene Ordnerstruktur (Best Practice)
+```text
+bg1ee-tts/
+├── README.md
+├── docs/
+│   ├── architecture.md
+│   ├── extraction-guide.md
+│   ├── tools-installation.md
+│   └── lua-hook-spec.md
+├── data/
+│   ├── raw/
+│   │   ├── tlk/
+│   │   │   ├── dialog_de.tlk
+│   │   │   └── dialog_en.tlk
+│   │   └── dlg/
+│   ├── processed/
+│   │   └── dialogs.json
+│   └── mappings/
+│       └── npc_map.json
+├── scripts/
+│   ├── extract_tlk.py
+│   ├── parse_dlg.py
+│   ├── build_database.py
+│   └── selftest.py
+├── tts-service/
+│   ├── app/
+│   │   ├── main.py
+│   │   ├── engines/
+│   │   ├── cache/
+│   │   └── playback/
+│   ├── tests/
+│   └── requirements.txt
+├── lua-hook/
+│   ├── bg1ee_tts_hook/
+│   │   ├── dialog.lua
+│   │   └── mod.ini
+│   └── build_instructions.md
+├── audio/
+│   ├── de/
+│   └── en/
+└── tools/
+    ├── NearInfinity.jar
+    └── weidu/
+```
+
+---
+
+# 📘 README.md
+
+## 🎯 BG1EE Dual‑Language TTS Projekt
+Dieses Repository enthält die vollständige Infrastruktur, um **Baldur's Gate Enhanced Edition (Steam)** automatisch in **Deutsch** und **Englisch** zu vertonen – live während des Spielens, mit Umschaltung per Hotkey.
+
+Ziel: Dialog erscheint im Spiel → ID wird abgefangen → TTS erzeugt Audio → Audio wird abgespielt.
+
+---
+
+## 🚀 Features
+- Extraktion aller BG1EE‑Texte (DE & EN)
+- Parser für TLK + DLG Dateien → JSON‑Datenbank
+- TTS‑Backend mit mehreren Engines (Melo, Kokoro, F5‑TTS, Piper)
+- Live‑Integration via Lua‑Dialoghook
+- Plattformunabhängig (Linux: Entwicklung / Windows: Spielen)
+
+---
+
+## 🧩 Voraussetzungen
+Du benötigst:
+- **Baldur's Gate: Enhanced Edition (Steam)**
+- **Java 17+** (für Near Infinity)
+- **Python 3.10+**
+- **FastAPI**
+- Optional: GPU‑TTS Engines
+
+---
+
+## 🔧 Installation externer Tools
+### Near Infinity (TLK + DLG Viewer/Exporter)
+Download:
+https://github.com/Argent77/NearInfinity
+
+```
+wget https://github.com/Argent77/NearInfinity/releases/latest/download/NearInfinity.jar
+```
+
+### WeiDU (Modding Toolkit)
+Download:
+https://github.com/WeiDUorg/weidu
+
+---
+
+## 📥 BG1EE Dateien finden (Steam)
+Linux‑Pfad:
+```
+~/.steam/steam/steamapps/common/Baldur's Gate Enhanced Edition/data/
+```
+Windows‑Pfad:
+```
+C:\Program Files (x86)\Steam\steamapps\common\Baldur's Gate Enhanced Edition\data
+```
+
+Relevante Dateien:
+- `lang/de_DE/dialog.tlk`
+- `lang/en_US/dialog.tlk`
+- `dialog.bif`
+- sämtliche `.dlg` Dateien
+
+---
+
+## 🏗️ Projektaufbau
+1. **TLK & DLG exportieren** (Near Infinity)
+2. **Parser ausführen** → erzeugt `dialogs.json`
+3. **TTS‑Service starten** (`uvicorn app.main:app`)
+4. **Lua‑Hook als Mod installieren**
+5. Spiel starten → Vertonung läuft automatisch
+
+---
+
+## 📚 Dokumentation
+- [docs/architecture.md](docs/architecture.md)
+- [docs/extraction-guide.md](docs/extraction-guide.md)
+- [docs/tools-installation.md](docs/tools-installation.md)
+- [lua-hook-spec.md](docs/lua-hook-spec.md)
+
+---
+
+## 📜 Rechtliches
+Dieses Projekt enthält **keine Originalspieldateien**.  
+Alle Extraktionen müssen lokal auf einem legal erworbenen BGEE‑Spiel erfolgen.  
+Siehe:
+- Baldur's Gate EE Copyright © Beamdog
+- https://store.steampowered.com/app/228280
+
+Quellenverlinkungen enthalten nur **offizielle** Hersteller‑Seiten.
+
+---
+
+## 🤝 Mitwirken
+PRs, Issues und Erweiterungen willkommen. Dies ist ein technisches Forschungs‑ und Hobbyprojekt.
+
+---
+
+Fertig!
+

docs/README.md

@@ -0,0 +1,3 @@
+# BG1EE TTS Project v0.2
+
+Clean doc...

docs/architecture.md

@@ -0,0 +1,3 @@
+# Architecture v0.2
+
+Updated...

docs/extraction-guide.md

@@ -0,0 +1,3 @@
+# Extraction Guide v0.2
+
+Steps...

docs/lua-hook-spec.md

@@ -0,0 +1,3 @@
+# Lua Hook Spec v0.2
+
+...

docs/tools-installation.md

@@ -0,0 +1,3 @@
+# Tools Installation v0.2
+
+...

scripts/create_project_structure.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+# create_project_structure.sh v2.0
+
+mkdir -p bg1ee-tts/{docs,data/raw/tlk,data/raw/dlg,data/processed,data/mappings,scripts,tts-service/app/engines,tts-service/app/cache,tts-service/app/playback,tts-service/tests,lua-hook/bg1ee_tts_hook,audio/de,audio/en,tools/weidu}
+
+echo "Projektstruktur angelegt."