docs: add README and Bedienungsanleitung

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

README.md

@@ -0,0 +1,96 @@
+# Voice Assistant
+
+Lokaler, vollständig offline-fähiger Sprachassistent mit Wake-Word-Erkennung,
+GPU-Transkription, LLM-Antwortgenerierung und mehrsprachiger Sprachausgabe.
+
+## Features
+
+- **Wake-Word** „Hey Jarvis" via [openwakeword](https://github.com/dscripka/openWakeWord)
+- **Spracherkennung** via [faster-whisper](https://github.com/SYSTRAN/faster-whisper) (`large-v3`, CUDA)
+- **LLM-Backends**: llama.cpp (lokal), Ollama, OpenAI-kompatible APIs
+- **Text-to-Speech** via [Piper](https://github.com/rhasspy/piper) mit automatischer Spracherkennung
+- **11 TTS-Sprachen** (de/en/fr/es/it/nl/pt/ru/pl/uk/cs), Stimmen werden bei Bedarf automatisch heruntergeladen
+- **5-Zustands-Maschine** (LAUSCH → AUFNAHME → GENERATOR → VORLESE → DIALOG)
+- **Steuer-Wörter** während der Wiedergabe: Stopp, Pause, Weiter, Noch einmal, …
+- **„Stopp"** funktioniert in allen aktiven Zuständen (AUFNAHME, GENERATOR, VORLESE, DIALOG)
+- **Wählbares Mikrofon**: ReSpeaker XVF3800, MOTU M2, Kamera-Mikrofon, Bluetooth, Index
+- **Wählbarer Ausgang**: beliebiger PipeWire-Sink
+
+## Voraussetzungen
+
+### Hardware
+- Mikrofon (empfohlen: [ReSpeaker XVF3800](https://wiki.seeedstudio.com/ReSpeaker_XVF3800/) mit Hardware-AEC)
+- NVIDIA GPU mit CUDA (für Whisper; llama.cpp kann separat konfiguriert werden)
+
+### Software
+```
+Python >= 3.12
+faster-whisper
+openwakeword
+piper-tts
+sounddevice
+scipy
+langdetect
+openai          # Python-Client (auch für lokale Backends)
+```
+
+PipeWire + paplay müssen als Audio-Backend aktiv sein.
+
+## Schnellstart
+
+```bash
+# Verfügbare Mikrofone anzeigen
+python3 assistant.py --list-mics
+
+# Starten mit Standard-Einstellungen (ReSpeaker, llama.cpp lokal)
+python3 assistant.py
+
+# Ohne Wake-Word (direkt in Aufnahme-Modus)
+python3 assistant.py --no-wakeword
+
+# Mit Ollama-Backend
+python3 assistant.py --backend ollama --model llama3.2
+
+# Britisches Englisch als TTS-Variante
+python3 assistant.py --en-variant gb
+```
+
+## Dateien
+
+| Datei | Beschreibung |
+|---|---|
+| `assistant.py` | Hauptprogramm — Zustands-Maschine, LLM-Integration |
+| `speak.py` | TTS-Modul — Piper-Wrapper, Spracherkennung, Sink-Auswahl |
+| `mic.py` | Mikrofon-Modul — Geräteauflösung, Alias-Tabelle |
+| `transcribe.py` | Standalone-Transkription zum Testen |
+
+## Architektur
+
+```
+Mikrofon (PortAudio)
+    │
+    ▼
+audio_q
+    │
+    ├─► LAUSCH:    openwakeword → "Hey Jarvis" → AUFNAHME
+    ├─► AUFNAHME:  Stille/Stop-Wort/Stopp → record_buffer
+    ├─► GENERATOR: whisper.transcribe → LLM-Stream → VORLESE
+    ├─► VORLESE:   piper-synth (Thread) + paplay + ctrl_monitor
+    └─► DIALOG:    5s-Fenster für Rückfrage ohne Wake-Word
+```
+
+## Separate Tools
+
+```bash
+# Sprachausgabe testen
+python3 speak.py --text "Hallo Welt" --out respeaker
+
+# Verfügbare Ausgänge anzeigen
+python3 speak.py --list
+
+# Live-Transkription testen
+python3 transcribe.py --mic respeaker
+
+# Verfügbare Mikrofone anzeigen
+python3 mic.py
+```