feat: Geräte-TTS, native Stimmen, Favicon, Auth-Gate, UI-Fixes

Web-UI / TTS: - Geräte-TTS ("📱 Gerät"): Antwort wird on-device vorgelesen (Web Speech API), Server sendet nur Text (text_only) -> spart Bandbreite/Kosten. Mobil-Default, geräte-lokale Speicherung, iOS-Autoplay-Freischaltung. - Vorlese-Symbol (🔊) je Bubble: Hybrid-Replay (Assistent-PCM gecacht, Eingabe via /api/speak); SVG-Icon mit kontrastreicher Farbe. - Kombiniertes Sprachmenü (Flex + feste Sprachen) statt separatem Modus-Menü. - "Neues Gespräch"-Button (frische Session gegen Sprach-Trägheit). - Dark-Mode: lesbare <option>-Popups (Kontrast-Fix). - Favicon (SVG + PNG-Fallbacks) aus mund.png. TTS-Backend: - Sprache wird an alle TTS-Provider durchgereicht; Piper-Stimme folgt der Sprache; Chatterbox mehrsprachig + cross-lingual. - Native Referenz-Stimmen je Sprache (config/voices/<lang>.wav, FLEURS CC-BY), loudness-normalisiert. LLM-Sprache: - Antwort folgt zuverlässig der gewählten Sprache (verstärkte Anweisung + Erinnerung an der letzten Nutzer-Nachricht gegen History-Trägheit). Admin / Auth: - Wörterbuch: alle 8 Sprachen, Zeilen editierbar, alphabetische Sortierung. - Web-UI hinter Auth-Gate (Redirect auf SSO_LOGIN_URL / 401); Favicons offen. - Log-Tab: Hinweis, wenn der systemd-Dienst nicht aktiv ist. - Einstellungen: Hinweis "pro Nutzer überschreibbar" bei Sprache/Modus/Qualität. Doku (BEDIENUNGSANLEITUNG.md): Geräte-TTS §6.5.0, Fix/Flex §6.6, native Stimmen §6.5.3, llama.cpp<->Ollama-Wechsel §4.7, Auth/SSO §7.4. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-20 13:12:04 +02:00 · 2026-06-20 13:12:04 +02:00 · 878bf785dd
commit 878bf785dd
parent dc8ac80505
51 changed files with 985 additions and 202 deletions
--- a/BEDIENUNGSANLEITUNG.md
+++ b/BEDIENUNGSANLEITUNG.md
@ -570,45 +570,71 @@ VA_PROFILE=local-dev make run   # alles lokal (STT/TTS in-process, LLM via Ollam

 ### 4.7 Zwischen llama.cpp und Ollama wechseln

-Beide Server können nicht gleichzeitig auf demselben GPU-Speicher laufen. Vor dem
-Wechsel muss der jeweils andere Backend-Prozess beendet werden.
+Beide nutzen denselben Gateway-Provider `local-openai-compatible` (OpenAI-kompatible
+API). Der Wechsel besteht daher aus drei Dingen: **(A)** den jeweils anderen
+Backend-Prozess stoppen (beide teilen sich den GPU-Speicher), **(B)** das gewünschte
+Backend starten, **(C)** die drei `LOCAL_LLM_*`-Zeilen in `.env` umstellen und das
+Gateway neu starten. `DEFAULT_LLM_PROVIDER` bleibt unverändert.

 **Merkhilfe:**
- llama.cpp = Docker-Container `va_llm` → stoppen mit `make llm-down`
- Ollama = systemd-Dienst → stoppen mit `sudo systemctl stop ollama`
+- llama.cpp = Docker-Container `va_llm` → `make llm-up` / `make llm-down` (Port 8001)
+- Ollama = systemd-Dienst → `sudo systemctl start/stop ollama` (Port 11434)

-#### Von Ollama → llama.cpp wechseln
-
-```bash
-# 1) Ollama stoppen
-sudo systemctl stop ollama
-# falls manuell gestartet (ollama serve im Vordergrund):
-pkill -f "ollama serve" 2>/dev/null || true
-
-# 2) llama.cpp starten und warten
-make llm-up
-make llm-status        # warten bis „Modell bereit" + HTTP OK erscheint
-
-# 3) Gateway starten
-VA_PROFILE=hybrid make run
-```
+> **Wichtig:** `.env`-Änderungen werden erst bei einem **Gateway-Neustart** wirksam
+> (uvicorn `--reload` lädt nur bei Code-Änderungen neu, nicht bei `.env`). Als Dienst:
+> `systemctl --user restart voice-assistant.service`.

 #### Von llama.cpp → Ollama wechseln

 ```bash
-# 1) llama.cpp stoppen
-make llm-down
-# alternativ direkt:
-docker rm -f va_llm
+# 1) llama.cpp stoppen (GPU freigeben)
+make llm-down                       # alternativ: docker rm -f va_llm

-# 2) Ollama starten
+# 2) Ollama starten und Modell sicherstellen
 sudo systemctl start ollama
-ollama ps              # prüfen ob Modell aktiv (oder leer — wird beim ersten Request geladen)
+ollama list                         # exakten Modellnamen ablesen (z. B. gemma4:12b)
+ollama pull gemma4:12b              # nur falls noch nicht vorhanden

-# 3) Gateway starten
-VA_PROFILE=hybrid make run
+# 3) .env umstellen:
+#    LOCAL_LLM_BASE_URL=http://127.0.0.1:11434/v1
+#    LOCAL_LLM_API_KEY=ollama
+#    LOCAL_LLM_MODEL=gemma4:12b     # exakter Name aus 'ollama list'
+
+# 4) Gateway neu starten
+VA_PROFILE=hybrid make run          # oder: systemctl --user restart voice-assistant.service
 ```

+#### Von Ollama → llama.cpp wechseln
+
+```bash
+# 1) Ollama stoppen (GPU freigeben)
+sudo systemctl stop ollama
+pkill -f "ollama serve" 2>/dev/null || true   # falls manuell im Vordergrund gestartet
+
+# 2) llama.cpp starten und warten
+make llm-up
+make llm-status                     # warten bis „Modell bereit" + HTTP OK
+
+# 3) .env umstellen:
+#    LOCAL_LLM_BASE_URL=http://127.0.0.1:8001/v1
+#    LOCAL_LLM_API_KEY=dummy
+#    LOCAL_LLM_MODEL=va_llm
+
+# 4) Gateway neu starten
+VA_PROFILE=hybrid make run          # oder: systemctl --user restart voice-assistant.service
+```
+
+**Prüfen** (egal welche Richtung):
+```bash
+curl http://127.0.0.1:11434/v1/models   # Ollama   (bzw. :8001 für llama.cpp)
+# danach im Admin → Status den LLM-Provider/das Modell kontrollieren oder kurz testen
+```
+
+> **Reasoning/Latenz:** Das Gateway sendet `enable_thinking:false`; **Ollama ignoriert**
+> das. Modelle mit eingebautem „Thinking" (z. B. `gemma4:12b`) liefern die Antwort sauber
+> im `content`, denken aber intern mit → höhere Latenz. Für reinen Smalltalk ggf. ein
+> kleineres/nicht-reasonendes Modell wählen.
+
 ---

 ### 4.8 Alles stoppen
@ -692,7 +718,7 @@ https://va.beispiel.de/        ← remote über Reverse-Proxy (alles, inkl. Mikr

 ```
 ┌─────────────────────────────────────────────────────────┐
-│  Voice Assistant               [☀️/🌙]  Angemeldet als … │
+│  Voice Assistant   [🇩🇪 ▾] [Qualität ▾]  [⚙️] [🌙]      │
 ├─────────────────────────────────────────────────────────┤
 │                                                         │
 │   Nachrichtenverlauf                                    │
@ -700,7 +726,7 @@ https://va.beispiel.de/        ← remote über Reverse-Proxy (alles, inkl. Mikr
 │   (Assistent: graue Blase links)                        │
 │                                                         │
 ├─────────────────────────────┬───────────────────────────┤
-│  Texteingabe …   [Senden]   │  [🎤]  [Stimme ▾]         │
+│  Texteingabe …   [Senden]   │  [🎤]                     │
 └─────────────────────────────┴───────────────────────────┘
  Statuszeile: „denkt …" / „verarbeite Sprache …" / leer
 ```
@ -709,7 +735,8 @@ https://va.beispiel.de/        ← remote über Reverse-Proxy (alles, inkl. Mikr
 |---------|----------|
 | **Texteingabe + Senden** | Text tippen, dann Enter oder „Senden" |
 | **🎤 Mikrofon-Button** | **Idle (grün 🎤):** Tippen → Aufnahme startet · **Aufnahme (rot pulsierend 🎤):** Tippen → Aufnahme stoppt und wird gesendet · **KI antwortet (amber ⏹):** Tippen → Antwort sofort unterbrechen (Barge-in) |
-| **Stimme ▾** | TTS-Provider wählen: leer = Server-Default, `chatterbox` = neuronale Stimme, `openrouter` = Cloud-TTS |
+| **Sprache ▾** | Antwortsprache wählen (→ § 6.6): `🔄 Flex` = folgt automatisch der gesprochenen Sprache · feste Sprache (🇩🇪/🇬🇧/…) = Eingabe wird in diese Sprache übersetzt. Die vorlesende Stimme folgt der Auswahl. |
+| **Qualität ▾** | Vorlese-Quelle wählen: `📱 Gerät` = das Handy/der Browser liest selbst vor (Web Speech API, kein Server-Audio → spart Daten/Kosten) · `Schnell` = piper (lokal) · `Hoch` = chatterbox (neuronal) · `Cloud` = openrouter |
 | **☀️ / 🌙** | Tag-/Nacht-Modus; folgt sonst automatisch dem Betriebssystem |
 | **⚙️** (Admin) | Öffnet das Admin-Panel — nur für Admin-Nutzer sichtbar (→ § 7.5) |
 | **Angemeldet als …** | SSO-Identität; „Gast" wenn AUTH deaktiviert oder kein SSO-Cookie |
@ -957,6 +984,27 @@ LOCAL_LLM_SYSTEM_PROMPT=

 ### 6.5 TTS-Einstellungen (Sprachsynthese)

+Die Vorlese-Quelle wählt der Nutzer im Kopfzeilen-Menü **Qualität** (→ § 5.1.2). Es gibt
+vier Optionen: das **Gerät** selbst (§ 6.5.0) oder einen der drei Server-Provider
+**piper** (§ 6.5.2), **chatterbox** (§ 6.5.3) bzw. **OpenRouter** (§ 6.5.1).
+
+#### 6.5.0 Geräte-TTS (Web Speech API) — „📱 Gerät"
+
+Wählt der Nutzer **„📱 Gerät"**, liest das Endgerät die Antwort **selbst** vor (iPhone:
+Safari/Siri-Stimmen, Android: System-TTS). Der Server erzeugt und überträgt dann **kein
+Audio** — er schickt nur den Text. Das spart Mobilfunk-Daten und TTS-Rechenzeit/Kosten.
+
+- **Vorteile:** keine Audio-Bytes, geringere Latenz, funktioniert auch ohne laufenden
+  TTS-Dienst.
+- **Grenzen:** Stimme/Qualität hängen vom Gerät ab; deine eigenen Stimmen (Klon,
+  FLEURS-Referenzen) und der Aussprache-Normalizer/das Wörterbuch (§ 6.5.4) greifen **nicht**.
+- **Verhalten:** Auf Mobilgeräten ist „Gerät" voreingestellt (solange nichts gewählt wurde).
+  Die Wahl ist **geräte-lokal** gespeichert (kein Server-Pref), da On-Device-Stimmen pro
+  Gerät verschieden sind. Browser ohne Web Speech API blenden die Option aus.
+- **Technik:** Das Frontend sendet `text_only:true`; die Antwortsprache je Bubble steuert
+  `SpeechSynthesisUtterance.lang`. iOS erlaubt Sprachausgabe erst nach einer Nutzergeste —
+  das Frontend schaltet sie beim ersten Tippen/Senden frei.
+
 #### 6.5.1 Cloud-TTS (OpenRouter) — Stimmen wählen

 Das Gateway reicht den Stimmennamen unverändert an OpenRouter weiter. Welche
@ -1050,10 +1098,22 @@ Konfiguration in `.env`:
 ```bash
 CHATTERBOX_BASE_URL=http://127.0.0.1:9999
 CHATTERBOX_VOICE=/pfad/zu/referenz_stimme.wav   # leer = Standardstimme
-CHATTERBOX_LANG=de
+CHATTERBOX_LANG=de                              # Fallback-Sprache (Gesprächssprache gewinnt)
 CHATTERBOX_SPEED=1.0
+CHATTERBOX_VOICES_DIR=config/voices             # native Referenz-Stimmen je Sprache
 ```

+**Mehrsprachig + native Stimme je Sprache.** Chatterbox ist mehrsprachig (de, en, fr,
+es, it, nl, ru, zh u. a.) und klont **cross-lingual**: Die Antwortsprache (→ § 6.6)
+wird automatisch an den Dienst übergeben, und die passende Referenz-Stimme wird aus
+`CHATTERBOX_VOICES_DIR` nach Konvention `<lang>.wav` gewählt (z. B. `fr.wav`, `zh.wav`).
+So spricht jede Sprache mit einer muttersprachlichen Stimme statt deutsch-akzentuiert.
+
+- Reihenfolge der Stimm-Auswahl: explizit angefragte `voice` (WAV-Pfad) → `config/voices/<lang>.wav` → `CHATTERBOX_VOICE` (persönlicher Klon) → Standardstimme des Dienstes.
+- Deutsch nutzt bewusst keine Datei in `config/voices/`, sondern `CHATTERBOX_VOICE`.
+- Die mitgelieferten Referenz-Clips stammen aus dem FLEURS-Datensatz (CC-BY 4.0) —
+  Quelle/Lizenz/Austausch siehe `config/voices/README.md`.
+
 #### 6.5.4 Aussprache verbessern (TTS-Normalizer)

 Vor dem TTS läuft ein Normalizer, der Ausspracheprobleme des Phonemizers behebt:
@ -1232,20 +1292,49 @@ print(result)   # → 'Chluteur kommt.'

 ---

-### 6.6 Sprache wechseln
+### 6.6 Sprache wechseln (Fix / Flex)
+
+Die Antwortsprache wird in der Web-Oberfläche über **ein einziges Dropdown** („Sprache")
+gesteuert. Es kennt zwei Arten von Werten:
+
+| Auswahl | Bedeutung | Whisper (STT) | LLM-Antwort + Stimme |
+|---------|-----------|---------------|----------------------|
+| **🔄 Flex** | keine feste Sprache — folgt automatisch der gesprochenen | erkennt die Sprache, **übersetzt nicht** | in der **erkannten** Sprache (blaue Blase zeigt das Original) |
+| **🇩🇪 / 🇬🇧 / … (feste Sprache)** | „Fix": System bleibt bei dieser Sprache | bekommt die feste Sprache → **übersetzt** die Eingabe | immer in der **festen** Sprache, egal worin gefragt wurde |
+
+**Beispiele** (Eingabe auf Französisch gesprochen):
+
+- **Flex** → blaue Blase: französischer Originaltext · Antwort + Stimme: Französisch.
+- **🇩🇪 DE** → blaue Blase: deutsche Übersetzung · Antwort + Stimme: Deutsch.
+
+Die vorlesende Piper-Stimme folgt immer der Antwortsprache automatisch (z. B. `thorsten`
+für Deutsch, `siwis` für Französisch — Zuordnung → `LANG_TO_PIPER_VOICE`). Bei Text-Chat
+im Flex-Modus (keine Audio-Erkennung möglich) bekommt das LLM **keine** Sprachvorgabe und
+antwortet von selbst in der Sprache der Eingabe; als Fallback gilt `DEFAULT_LANGUAGE`.
+
+> **Hinweis:** Es gibt kein separates „Fix/Flex"-Menü mehr — eine konkrete Sprache zu
+> wählen *ist* der Fix-Modus, „🔄 Flex" der flexible. Intern bleiben zwei Felder
+> erhalten: `language` (ISO-Code) und `language_mode` (`fix` | `flex`).
+
+**Konfiguration außerhalb der Web-UI:**

 ```bash
-DEFAULT_LANGUAGE=de   # global in .env
+DEFAULT_LANGUAGE=de        # global in .env (Fallback-/Standardsprache)
+DEFAULT_LANGUAGE_MODE=fix  # global: fix | flex (Admin: Tab „⚙ Einstellungen")
 ```

-Pro Nutzer:
+Pro Nutzer (dauerhaft):
 ```bash
-curl -X PUT $URL/api/me/prefs \
-  -H "Authorization: Bearer $TOKEN" \
-  -H 'Content-Type: application/json' -d '{"language":"en"}'
+# Feste Sprache (Fix):
+curl -X PUT $URL/api/me/prefs -H "Authorization: Bearer $TOKEN" \
+  -H 'Content-Type: application/json' -d '{"language":"en","language_mode":"fix"}'
+
+# Flex (Sprache folgt automatisch):
+curl -X PUT $URL/api/me/prefs -H "Authorization: Bearer $TOKEN" \
+  -H 'Content-Type: application/json' -d '{"language_mode":"flex"}'
 ```

-Pro Aufruf: `{"text":"…","language":"en"}` im Body.
+Pro Aufruf: `{"text":"…","language":"en","language_mode":"fix"}` im Body.

 ---

@ -1564,6 +1653,7 @@ TRUSTED_AUTH_COOKIE_CLAIM=user
 TRUSTED_PROXY_IPS=192.168.179.10
 ADMIN_USERS=atoor,dieterschlueter,dschlueter
 SSO_LOGOUT_URL=https://linix.de/yunohost/sso/?action=logout
+SSO_LOGIN_URL=https://linix.de/yunohost/sso/   # unauth. Seitenaufrufe -> hierhin umleiten

 # Optional: Signaturprüfung des JWT-Cookies
 TRUSTED_AUTH_JWT_SECRET=<hs256-secret aus /etc/yunohost/.ssowat_cookie_secret>
@ -1574,6 +1664,17 @@ TRUSTED_AUTH_HEADER=X-Remote-User

 Vollständige Anleitung: [deploy/README.md](deploy/README.md).

+**Zugriffsschutz der Web-UI (mehrstufig):**
+1. **YunoHost SSOwat (primär):** Die App-Berechtigung darf die Gruppe „visitors" nicht
+   enthalten → unauthentifizierte Besucher werden zum Portal umgeleitet, bevor sie das
+   Gateway erreichen: `yunohost user permission update <APP>.main --remove visitors --add all_users`.
+2. **Gateway, API/WS:** Anfragen über den Proxy ohne gültiges `yunohost.portal`-Cookie
+   bekommen 401 (auch bei `AUTH_ENABLED=false` — das betrifft nur den LAN-Direktzugriff).
+3. **Gateway, statische Seite:** Unauthentifizierte Seitenaufrufe werden auf `SSO_LOGIN_URL`
+   umgeleitet (bzw. 401, falls nicht gesetzt) — Defense-in-Depth, falls SSOwat umgangen wird.
+4. **Port:** Das Gateway sollte nicht offen im Netz lauschen (`HOST=127.0.0.1` bzw. Firewall
+   auf die Proxy-IP), damit der SSO-Weg nicht per Direktzugriff umgangen werden kann.
+
 ### 7.5 Admin-Web-Panel

 > 🔧 Admin — erreichbar über den **⚙️-Button** im Web-Interface (nur für Admin-Nutzer sichtbar)
@ -2073,13 +2174,15 @@ Wichtige Body-Felder für `/api/chat` und `/api/speak`:
 | Feld | Typ | Bedeutung |
 |------|-----|-----------|
 | `text` | string | Eingabe-Text (Pflicht) |
-| `language` | string | Sprache, z. B. `de`, `en` |
+| `language` | string | Sprache, z. B. `de`, `en` (im Fix-Modus maßgeblich) |
+| `language_mode` | string | `fix` (feste Sprache, Eingabe wird übersetzt) oder `flex` (folgt der erkannten Sprache) — → § 6.6 |
 | `stt_provider` | string | Provider für diese Anfrage |
 | `llm_provider` | string | Provider für diese Anfrage |
 | `tts_provider` | string | Provider für diese Anfrage |
 | `voice` | string | TTS-Stimme für diese Anfrage |
 | `stream` | bool | LLM-Token-Streaming (nur WebSocket) |
 | `audio_stream` | bool | Satzweises Audio-Streaming (nur WebSocket) |
+| `text_only` | bool | Kein Server-Audio erzeugen/senden (nur Text) — fürs Geräte-TTS (→ § 6.5.0) |

 ## B.3 Sessions und Routing

@ -2095,7 +2198,7 @@ Body-Felder: `input_endpoint`, `output_endpoint`, `stt_provider`, `llm_provider`
 | Methode | Pfad | Beschreibung |
 |---------|------|--------------|
 | `GET` | `/api/me` | Aktueller Nutzer + Präferenzen |
-| `PUT` | `/api/me/prefs` | Dauerhafte Routing-Präferenzen setzen |
+| `PUT` | `/api/me/prefs` | Dauerhafte Routing-Präferenzen setzen (Merge; Felder u. a. `language`, `language_mode`, `tts_provider` — → § 6.6) |
 | `GET` | `/api/me/memories` | Alle Langzeit-Erinnerungen |
 | `POST` | `/api/me/memories` | Erinnerung hinzufügen |
 | `DELETE` | `/api/me/memories/{id}` | Erinnerung löschen |
@ -2190,7 +2293,9 @@ in `app/dependencies.py` + Implementierung in `app/providers/`. → [Architektur
 | Fallback-Ketten | § 9.1, Anhang A.3 |
 | faster-whisper | § 6.3, Anhang C |
 | Fehlerbehebung | § 13 |
+| Fix / Flex (Sprachmodus) | § 6.6 |
 | Gedächtnis (Sitzung) | § 8.1 |
+| Geräte-TTS (Web Speech API) | § 6.5.0 |
 | Hybrid-Profil | § 3.2 |
 | Installation | § 2 |
 | Konfigurationsebenen / Priorität | § 6.1 |
@ -2212,8 +2317,10 @@ in `app/dependencies.py` + Implementierung in `app/providers/`. → [Architektur
 | Remote-Zugang / HTTPS / SSO | § 11 |
 | Sachregister | Anhang D |
 | Sitzungsgedächtnis | § 8.1 |
+| Sprache wechseln (Fix/Flex) | § 6.6 |
 | Sprech-Loop | § 5.2 |
 | Stimmen (TTS) | § 6.5.1, § 6.5.2 |
+| Stimme folgt Sprache (Flex) | § 6.6 |
 | STT-Einstellungen | § 6.3 |
 | Streaming (Audio/Token/VAD) | § 6.8, Anhang B.6 |
 | Tests | § 12 |