From 7e54fc22601472ce177ccf5c1b18ff8801d2d85f Mon Sep 17 00:00:00 2001 From: stephan Date: Sun, 7 Dec 2025 19:35:49 +0100 Subject: [PATCH] first commit --- .vibe/bg1-projectplan.md | 155 ++++++++++++++++++++++++++++ .vibe/bg1-session-resumee.md1 | 67 ++++++++++++ README.md | 145 ++++++++++++++++++++++++++ docs/README.md | 3 + docs/architecture.md | 3 + docs/extraction-guide.md | 3 + docs/lua-hook-spec.md | 3 + docs/tools-installation.md | 3 + scripts/create_project_structure.sh | 6 ++ 9 files changed, 388 insertions(+) create mode 100644 .vibe/bg1-projectplan.md create mode 100644 .vibe/bg1-session-resumee.md1 create mode 100644 README.md create mode 100644 docs/README.md create mode 100644 docs/architecture.md create mode 100644 docs/extraction-guide.md create mode 100644 docs/lua-hook-spec.md create mode 100644 docs/tools-installation.md create mode 100755 scripts/create_project_structure.sh diff --git a/.vibe/bg1-projectplan.md b/.vibe/bg1-projectplan.md new file mode 100644 index 0000000..80d3b19 --- /dev/null +++ b/.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/` + - `/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. + +--- + diff --git a/.vibe/bg1-session-resumee.md1 b/.vibe/bg1-session-resumee.md1 new file mode 100644 index 0000000..ac8429c --- /dev/null +++ b/.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 + +--- + diff --git a/README.md b/README.md new file mode 100644 index 0000000..04095ed --- /dev/null +++ b/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! + diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..f961e24 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,3 @@ +# BG1EE TTS Project v0.2 + +Clean doc... \ No newline at end of file diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..df815d1 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,3 @@ +# Architecture v0.2 + +Updated... \ No newline at end of file diff --git a/docs/extraction-guide.md b/docs/extraction-guide.md new file mode 100644 index 0000000..e434d57 --- /dev/null +++ b/docs/extraction-guide.md @@ -0,0 +1,3 @@ +# Extraction Guide v0.2 + +Steps... \ No newline at end of file diff --git a/docs/lua-hook-spec.md b/docs/lua-hook-spec.md new file mode 100644 index 0000000..a07eca1 --- /dev/null +++ b/docs/lua-hook-spec.md @@ -0,0 +1,3 @@ +# Lua Hook Spec v0.2 + +... \ No newline at end of file diff --git a/docs/tools-installation.md b/docs/tools-installation.md new file mode 100644 index 0000000..356fd2c --- /dev/null +++ b/docs/tools-installation.md @@ -0,0 +1,3 @@ +# Tools Installation v0.2 + +... \ No newline at end of file diff --git a/scripts/create_project_structure.sh b/scripts/create_project_structure.sh new file mode 100755 index 0000000..8bcd357 --- /dev/null +++ b/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."