# Entwicklerdokumentation Für Programmierer, die den Code verstehen, ändern oder erweitern wollen. Anwender lesen die [Bedienungsanleitung](../BEDIENUNGSANLEITUNG.md), Client-Entwickler die [API-Referenz](API.md). ## Inhalt 1. [Designziele](#1-designziele) 2. [Projektstruktur](#2-projektstruktur) 3. [Architektur im Überblick](#3-architektur-im-überblick) 4. [Modul `stt_core.py`](#4-modul-stt_corepy) 5. [Modul `stt_service.py`](#5-modul-stt_servicepy) 6. [Modul `stt_wyoming.py`](#6-modul-stt_wyomingpy) 7. [Modul `stt_cli.py`](#7-modul-stt_clipy) 8. [Nebenläufigkeit — die wichtigsten Regeln](#8-nebenläufigkeit--die-wichtigsten-regeln) 9. [Konfiguration](#9-konfiguration) 10. [Entwicklungsumgebung](#10-entwicklungsumgebung) 11. [Tests](#11-tests) 12. [Erweitern: typische Aufgaben](#12-erweitern-typische-aufgaben) 13. [Designentscheidungen](#13-designentscheidungen) 14. [Bekannte Grenzen und mögliche nächste Schritte](#14-bekannte-grenzen-und-mögliche-nächste-schritte) 15. [Konventionen](#15-konventionen) --- ## 1. Designziele | Ziel | Umsetzung | |---|---| | **Schnell** | Modell einmal laden und halten; `large-v3-turbo` auf GPU; genau eine Transkription pro Äußerung | | **Nicht blockierend** | Inferenz in einem Worker-Thread; Event-Loop bleibt frei; begrenzte Warteschlange mit sofortigem 503 | | **Zuverlässig** | GPU→CPU-Fallback beim Laden; Halluzinationsfilter; robustes Dekodieren beliebiger Formate; Fehler einzelner Anfragen beenden keine Verbindung | | **Vielseitig anbindbar** | eine Engine, mehrere Schnittstellen: OpenAI-HTTP, Roh-HTTP, WebSocket, Wyoming, CLI | | **Testbar** | reine Logik ohne I/O im Kern; App-Fabrik mit injizierbarer Engine und VAD | | **Gegenstück zu chatterbox-tts-cli** | gleiche Bauart: Kernmodul + FastAPI-Dienst + CLI + systemd-User-Unit | Das Projekt ersetzt das alte Einzelskript `legacy/stt.py`. Dessen Schwächen — Stoppwort-Erkennung in starren 2-s-Blöcken, doppelte Transkription, Modell-Laden pro Aufruf, falsches Lesen von Stereo-WAVs, alles in einer Datei mit `print`/`sys.exit` — haben das Design direkt geprägt. Als Vorbild für funktionierendes STT diente `my_voice_assistant_v3` (Modell-Cache, `asyncio.to_thread`, VAD-Segmentierung, Warm-up). --- ## 2. Projektstruktur ``` SpeechToText/ ├── stt_core.py Kern: Engine, Audio-Hilfen, Halluzinationsfilter, VAD-Segmentierung (kein I/O) ├── stt_service.py FastAPI-Dienst: HTTP-Endpunkte, WebSocket, Worker, Start des Wyoming-Servers ├── stt_wyoming.py Wyoming-Protokoll-Handler (Home Assistant) ├── stt_cli.py Client: Dateien/Mikrofon → Dienst, oder --local direkt mit dem Kern ├── stt_llm.py optionale LLM-Nachkorrektur (nur CLI --llm-correct) ├── tests/ │ ├── conftest.py Fixtures und Test-Helfer (FakeEngine, EnergyProb, make_wav, tone, espeak_wav) │ ├── test_core.py Audio, Filter, Konfiguration, Segmentierung │ ├── test_service.py HTTP, Überlast, Nicht-Blockieren, WebSocket │ ├── test_wyoming.py Wyoming über echten TCP-Socket │ ├── test_llm.py LLM-Korrektur mit geskripteten Antworten (+ 1 Integrationstest mit Ollama) │ └── test_integration.py echtes Whisper + Silero (Marker "integration") ├── deploy/stt-service.service systemd-User-Unit ├── docs/API.md Schnittstellen-Referenz ├── docs/ENTWICKLER.md dieses Dokument ├── BEDIENUNGSANLEITUNG.md Anwender-Handbuch ├── README.md Überblick und Schnellstart ├── CLAUDE.md Kurzkontext für Claude Code ├── requirements.txt ├── pytest.ini Marker, Standard: Integrationstests ausgeschlossen └── legacy/ historische Einzelskripte (nicht gepflegt) ``` **Abhängigkeitsrichtung** (keine Zyklen): ```mermaid flowchart LR cli[stt_cli.py] -. "nur mit Option local" .-> core[stt_core.py] service[stt_service.py] --> core service -. Import zur Laufzeit .-> wyoming[stt_wyoming.py] wyoming --> core cli -- HTTP/WS --> service cli -. "nur mit Option llm-correct" .-> llm[stt_llm.py] llm -- HTTP --> ollama[(Ollama / OpenAI-kompatibel)] ``` `stt_core` importiert nichts aus dem Projekt; `stt_llm` nutzt aus dem Kern nur `_env`. Dienst und Wyoming wissen nichts von der LLM-Korrektur. `stt_wyoming` wird erst beim Start importiert, damit der Dienst ohne das Paket `wyoming` lauffähig bleibt. --- ## 3. Architektur im Überblick ```mermaid flowchart TB subgraph Clients HA[Home Assistant / ESPHome] ESP[ESP32 / Skripte] OAI[OpenAI-kompatible Tools] CLI[stt_cli.py] end subgraph Prozess["stt_service.py (ein Prozess, ein Event-Loop)"] WY[Wyoming-Handler
stt_wyoming.py] HTTP[HTTP-Endpunkte
/transcribe, /v1/audio/transcriptions] WS[_StreamSession
/ws/stream] SEG[UtteranceSegmenter
+ SileroProb] W[TranscriptionWorker
ThreadPoolExecutor 1 Thread
pending ≤ max_queue] E[SttEngine
WhisperModel] end HA -- TCP 10300 --> WY ESP --> HTTP OAI --> HTTP CLI --> HTTP CLI --> WS ESP --> WS WS --> SEG WY --> W HTTP --> W SEG -- Äußerung --> W W -- Thread --> E E -- CTranslate2 --> GPU[(GPU / CPU)] ``` Alle Schnittstellen enden im **selben `TranscriptionWorker`** und damit in **einem** geladenen Modell. Der Worker serialisiert die Inferenz (eine GPU-Aufgabe zur Zeit) und begrenzt die Anzahl wartender Aufträge. ### Ablauf einer HTTP-Anfrage ```mermaid sequenceDiagram participant C as Client participant L as Event-Loop (FastAPI) participant D as to_thread (Dekodieren) participant W as Worker-Thread participant E as SttEngine C->>L: POST /transcribe (Body) L->>L: Größe prüfen (413) L->>D: decode_audio_bytes (PyAV) D-->>L: float32 16 kHz L->>L: pending >= max_queue? → 503 L->>W: run_in_executor(engine.transcribe) Note over L: Event-Loop frei für /health, WS, Wyoming W->>E: transcribe (mit _run_lock) E-->>W: Transcript W-->>L: Transcript L-->>C: JSON ``` --- ## 4. Modul `stt_core.py` Reine Logik: **kein `print`, kein `sys.exit`, keine Netzwerkzugriffe**. Fehler als Exceptions, Ergebnisse als Dataclasses. Schwere Importe (`faster_whisper`, `scipy`, `soxr`) erfolgen erst in den Funktionen, die sie brauchen — `import stt_core` ist dadurch schnell. ### 4.1 Audio-Hilfen | Funktion/Klasse | Zweck | |---|---| | `pcm16_to_float(data, channels, channel)` | s16le → float32 mono; Kanal auswählen oder mitteln; unvollständige Frames verwerfen | | `float_to_pcm16(audio)` | Gegenrichtung (Tests, Clients) | | `resample(audio, src, dst)` | ganze Signale (`scipy.signal.resample_poly`) | | `StreamResampler(src, dst)` | fortlaufende Stücke ohne Randartefakte (`soxr.ResampleStream`); `process(chunk, last=True)` leert den Filter | | `decode_audio_bytes(data)` | beliebige Container über `faster_whisper.decode_audio` (PyAV) → 16 kHz mono; wirft `AudioDecodeError` | Konstante `SAMPLE_RATE = 16000` ist das interne Format überall. ### 4.2 Ergebnisobjekte `Segment(start, end, text, avg_logprob, no_speech_prob)` und `Transcript(text, language, language_probability, duration, processing_s, segments, dropped_segments)` mit `to_dict(with_segments=True)`. Die JSON-Antworten der Schnittstellen sind direkt daraus abgeleitet — neue Felder hier erscheinen automatisch in `/transcribe` und im WebSocket. ### 4.3 Halluzinationsfilter Whisper erzeugt bei Stille oder Rauschen typische Floskeln aus seinen Trainingsdaten (Untertitel). `is_hallucination(seg)` verwirft ein Segment, wenn 1. der normalisierte Text (klein, Satzzeichen weg) **vollständig** einem Muster aus `_HALLUCINATION_PATTERNS` entspricht (z. B. „untertitel im auftrag des zdf 2021“), oder leer ist, oder 2. Whisper selbst unsicher ist **und** Stille vermutet: `no_speech_prob > 0.6 and avg_logprob < -0.8`. „Vollständig“ ist Absicht: „Die Untertitel im Fernsehen sind zu klein.“ bleibt erhalten. Verworfene Segmente zählt `Transcript.dropped_segments`; mit `STT_LOG_LEVEL=DEBUG` werden sie geloggt. ### 4.4 `EngineConfig` und `SttEngine` `EngineConfig` bündelt alle Modellparameter; `EngineConfig.from_env()` liest `STT_*`. **Laden** (`SttEngine.load`, idempotent, durch `_load_lock` geschützt): ```mermaid flowchart TD A[load] --> B{Modell schon geladen?} B -- ja --> Z[fertig] B -- nein --> C[_load_attempts] C --> D{device auto/cuda
und CUDA-GPU vorhanden?} D -- ja --> E[Versuch: cuda, model, float16] D -- nein --> F E -- Fehler --> F[Versuch: cpu, cpu_model*, int8] E -- ok --> R[status = ready] F -- ok --> R F -- Fehler --> X[status = error, RuntimeError] ``` \* bei `device=cpu` wird `model` statt `cpu_model` verwendet — wer CPU explizit wählt, bekommt sein Modell. Status-Felder für `/health`: `status` (`idle|loading|ready|error`), `error`, `active_model`, `active_device`, `active_compute_type`, `load_seconds`. **Transkribieren** (`SttEngine.transcribe`, blockierend): - `< 100 ms` Audio → sofort leeres `Transcript`, ohne das Modell anzufassen. - Sprache über `resolve_language`: `None` → Config, `"auto"`/`""` → Erkennung, `"de-DE"` → `"de"`. - Aufruf von `WhisperModel.transcribe` unter `_run_lock` mit: | Parameter | Wert | Grund | |---|---|---| | `vad_filter` | `True` (Standard) | Stille innerhalb des Audios überspringen → schneller, weniger Halluzinationen | | `vad_parameters` | `min_silence_duration_ms=500, speech_pad_ms=200` | Wörter an Pausen nicht abschneiden | | `condition_on_previous_text` | `False` | verhindert Wiederholungsschleifen über 30-s-Fenster hinweg | | `beam_size` | Config (5) | Genauigkeit; `warmup` nutzt 1 | | `initial_prompt` | Anfrage oder Config | Eigennamen | | `hotwords` | nur Wyoming | Namen/Begriffe aus Home Assistant | - **Wichtig:** `segments` ist ein Generator — die eigentliche Rechenarbeit passiert erst bei `list(...)`, deshalb liegt das innerhalb des Locks. `warmup()` lädt das Modell und transkribiert 1 s leises Rauschen (ohne VAD), damit CUDA-Kernel und Decoder initialisiert sind und die erste echte Anfrage schnell ist. ### 4.5 Streaming-Segmentierung **`SileroProb`** liefert die Sprachwahrscheinlichkeit je 512-Sample-Fenster (32 ms) mit dem in faster-whisper mitgelieferten Silero-VAD (ONNX, CPU, kein Download). Besonderheit: Das Modell leitet den 64-Sample-Kontext eines Fensters aus dem **vorherigen Fenster im selben Aufruf** ab. Damit das über Aufrufgrenzen stimmt, wird das letzte Fenster des vorigen Aufrufs vorangestellt und dessen Ergebnis verworfen. **`UtteranceSegmenter`** ist eine Zustandsmaschine über diesen Fenstern: ```mermaid stateDiagram-v2 [*] --> Warten Warten --> Warten: Fenster in Pre-Roll-Puffer, p < threshold → voiced = 0 Warten --> Sprache: voiced ≥ min_speech_ms, → Ereignis speech_start, Pre-Roll wird Äußerungsanfang Sprache --> Sprache: Fenster anhängen, p < threshold − 0,15 → silent += 1, sonst silent = 0 Sprache --> Warten: silent ≥ silence_ms, → utterance (reason silence) Sprache --> Warten: Länge ≥ max_utterance_s, → utterance (reason max_length) Sprache --> Warten: flush(), → utterance (reason flush) ``` - **Hysterese:** Start bei `p ≥ threshold`, Stille erst bei `p < threshold − 0,15` → kein Flattern. - **Pre-Roll:** Ringpuffer der letzten `pre_roll_ms + min_speech_ms` → Anlaute bleiben erhalten. - **Stream-Zeit** (`time_s`) zählt verarbeitete Samples, nicht die Uhr → Dateien dürfen schneller als Echtzeit gestreamt werden. - `prob_fn` ist injizierbar (Tests nutzen `EnergyProb`), `feed()` gibt eine Liste von `VadEvent` zurück. - Unvollständige Fenster bleiben in `_pending` bis zum nächsten `feed()`. --- ## 5. Modul `stt_service.py` ### 5.1 App-Fabrik ```python app = create_app(engine=None, settings=None, vad_config=None, prob_fn_factory=None) ``` Ohne Argumente wird alles aus der Umgebung gebaut (`EngineConfig.from_env()`, `ServiceSettings.from_env()`, `VadConfig.from_env()`, `SileroProb`). Tests übergeben `FakeEngine` und `EnergyProb`. Auf Modulebene steht `app = create_app()` für `uvicorn stt_service:app` — das ist billig, weil erst die **Lifespan** das Modell lädt. **Lifespan:** 1. `STT_PRELOAD`: `engine.warmup` als **erster Job im Worker** starten, **ohne** zu warten. Der Dienst antwortet sofort (`/health` → `loading`); frühe Anfragen reihen sich hinter dem Laden ein. 2. Wyoming-Server starten, falls Port gesetzt (Fehler → nur Log, der HTTP-Dienst läuft trotzdem). 3. Beim Beenden: Wyoming stoppen, Preload abbrechen, Executor herunterfahren. ### 5.2 `TranscriptionWorker` - `ThreadPoolExecutor(max_workers=1)` → genau eine Inferenz gleichzeitig (GPU-schonend, vorhersagbarer Speicher). - `pending` zählt laufende + wartende Aufträge. Er wird **nur im Event-Loop** verändert, daher ohne Lock. - `transcribe()` wirft `Overloaded`, wenn `pending ≥ max_queue` → HTTP 503 bzw. WS-`error`. - `run(fn, …)` für beliebige blockierende Aufgaben im selben Thread (z. B. `warmup`). ### 5.3 HTTP-Endpunkte `_run_transcription` übersetzt Ausnahmen in HTTP-Status (`Overloaded` → 503, `RuntimeError` → 500). `_decode` dekodiert in `asyncio.to_thread` (PyAV kostet bei langen Dateien CPU) und macht aus `AudioDecodeError` einen 400. `_check_size` erzwingt `max_upload_mb`. ### 5.4 WebSocket: `_StreamSession` Eine Instanz pro Verbindung. Zwei nebenläufige Tasks: ```mermaid flowchart LR RX["run() — Empfangsschleife"] -- Binär --> A[_on_audio:
pcm16_to_float → StreamResampler
→ UtteranceSegmenter.feed] RX -- Text --> B[_on_control:
start / end / close] A -- speech_start --> SEND A -- utterance --> Q[(jobs: asyncio.Queue)] B -- flush / done-Marker --> Q Q --> C["_consume() — Task"] C -- worker.transcribe --> W[TranscriptionWorker] C -- transcript / error / done --> SEND[send mit send_lock] ``` - Die Empfangsschleife **wartet nie auf Whisper** → Audio wird auch während der Transkription angenommen; Äußerungen werden in Reihenfolge abgearbeitet. - `send_lock`, weil beide Tasks senden. - Queue-Einträge: `(audio, reason, t)` · `"done"` (Marker nach `end`) · `None` (Ende). - Ohne VAD sammelt `buffer` bis `end` bzw. bis `max_utterance_s` erreicht ist. - `start` baut Resampler und Segmenter neu (setzt die Sitzung zurück). - Beim Verbindungsende: `None` einreihen, `_consume` bis 120 s ausstehende Transkripte abarbeiten lassen. --- ## 6. Modul `stt_wyoming.py` `SttEventHandler(AsyncEventHandler)` — eine Instanz pro TCP-Verbindung. | Ereignis | Aktion | |---|---| | `describe` | `build_info(engine)` → `Info` mit `AsrProgram("speech-to-text")`, Modellname, Whisper-Sprachen | | `transcribe` | `language` merken; `transcript_names + transcript_terms` → `hotwords` | | `audio-start` | Puffer und `AudioChunkConverter(16000 Hz, 16 Bit, mono)` neu | | `audio-chunk` | konvertieren und anhängen | | `audio-stop` | `worker.transcribe` → `Transcript`-Ereignis → `return False` (Verbindung schließen, HA-Konvention) | Fehler bei der Transkription führen zu einem **leeren** Transkript statt zu einem Abbruch — Home Assistant würde sonst auf eine Antwort warten. `start_server(worker, host, port)` gibt den `AsyncTcpServer` zurück; Port `0` ist in Tests erlaubt (freien Port über `server._server.sockets[0]` ermitteln). --- ## 7. Modul `stt_cli.py` | Funktion | Aufgabe | |---|---| | `main` | Argumente, Modus-Auswahl, Fehler → Exit-Code, Hinweis bei nicht erreichbarem Dienst | | `service_file` | `POST /transcribe` mit Datei als Body (Streaming-Upload über `requests`) | | `service_mic` | Mikrofon → `/ws/stream` (synchroner `websockets`-Client, Empfänger-Thread) | | `local_files` / `local_mic` | wie oben, aber `SttEngine` + `UtteranceSegmenter` im Prozess; Inferenz im `ThreadPoolExecutor(1)` | | `start_enter_watcher` / `emit_joined` | `--until-enter`: Thread wartet auf Enter; Abschnitte sammeln und am Ende als ein Ergebnis ausgeben (Dienst: `end` senden, auf `done` warten; lokal: `segmenter.flush()`, Futures in Reihenfolge) | | `Microphone` | `sounddevice.InputStream` mit Callback → `queue.Queue` von s16le-Mono-Blöcken (100 ms) | | `resolve_input` | Gerätewahl: kein `-d` → ALSA-Gerät `pulse` (folgt PipeWire-Default), Zahl → Index, Text → Namenssuche | **Threads im Mikrofon-Modus mit Dienst:** Audio-Callback (PortAudio) → Queue → Hauptthread sendet; ein Empfänger-Thread liest Ereignisse und schreibt Transkripte auf stdout. Keine Stelle blockiert die Aufnahme; läuft die Queue (60 s) voll, werden Blöcke gezählt verworfen. **Warum `pulse` statt PortAudio-Default?** PortAudio wählt auf PipeWire-Systemen die erste ALSA-Karte (hier: Onboard-ALC1220), nicht das eingestellte Mikrofon. Über `pulse` wird mit 16 kHz aufgenommen (PipeWire resampelt); der Name der Standardquelle kommt aus `pactl get-default-source` und dient der ReSpeaker-Erkennung (→ Kanal 1). **Ausgabevertrag:** stdout nur Ergebnisse (Text oder JSON-Zeile), stderr alles andere. Exit-Codes `0/1/2/130` (siehe Bedienungsanleitung). --- ### LLM-Nachkorrektur (`stt_llm.py`) Optionaler Zusatz, bewusst **außerhalb** von Kern und Dienst: Smarthome-, ESP32- und Wyoming-Pfade bleiben schnell und deterministisch. Eingebunden nur über `Output` in `stt_cli.py` (`--llm-correct`). ```mermaid flowchart LR T[Transkript] --> O[Output.put] O -- ohne LLM --> E[emit stdout] O -- mit LLM --> X[ThreadPoolExecutor 1
Reihenfolge bleibt] X --> C[LlmCorrector.correct] C --> S[split_chunks
≤ 1200 Zeichen] S --> CH[_chat
Ollama /api/chat oder /v1/chat/completions] CH --> CL[clean_output] CL --> G{_accept
Ähnlichkeit ≥ 0,75
Länge ±30 %} G -- ja --> K[korrigierter Text] G -- nein --> R[Rohtext] CH -- Exception --> R K --> E R --> E ``` | Baustein | Aufgabe | |---|---| | `LlmConfig` / `from_env` | URL, Modell, `api` (`auto`/`ollama`/`openai`), `keep_alive`, `num_ctx`, Timeout, Schwellen (`STT_LLM_*`) | | `SYSTEM_PROMPT` + `FEW_SHOT` | nur Erkennungsfehler korrigieren; Diktat in ``-Tags; Beispiel mit „Anweisung“ im Diktat | | `LlmCorrector._detect_api` | `…/v1` → OpenAI-kompatibel; sonst `GET /api/version` → Ollama | | `LlmCorrector._chat` | Ollama nativ mit `think: false`, `keep_alive`, `num_ctx`, `temperature 0`; sonst Chat Completions | | `clean_output` | entfernt Tags, umschließende Anführungszeichen, „Korrigierter Text:“ | | `_accept` | Ähnlichkeit (`difflib`) und Längenänderung → sonst Rohtext | | `correct` | wirft nie; `Correction(text, raw_text, status, detail, llm_text, similarity, seconds, model)` | **Warum Ollama nativ statt `/v1`?** Auf dem Entwicklungsrechner ist Ollama global mit `OLLAMA_CONTEXT_LENGTH=131072` und `OLLAMA_NUM_PARALLEL=4` konfiguriert. Über `/v1` lässt sich der Kontext nicht pro Anfrage setzen — die Modelle liefen dann zu 75–90 % auf der CPU (5–8 s pro Satz, `mistral-nemo` 95 GB). Mit `num_ctx=4096` pro Anfrage laufen sie zu 100 % auf der GPU (0,5–1,5 s). **Modellvergleich** (2026-09-14, 11 Fälle: 5 Whisper-Fehler, 5 korrekte Sätze, 1 „Anweisung“; RTX 3090, Prompt mit Tags und Beispielen): | Modell | bestanden | Latenz warm | Beobachtung | |---|---|---|---| | `gemma4:12b` | 9/11 | ~1,2 s | widersteht der Anweisung schon per Prompt; scheitert nur an stark verstümmelten Sätzen | | `mistral-nemo` | 9/11 | ~0,6 s | Anweisung und Tags nur durch `_accept` abgefangen; erfindet Namen („Meredith-Stehle“) | | `qwen3.5:9b` | 4/11 | ~0,8 s | verändert Befehle („Schalte das Licht aus“ → „Das Licht ist ausgeschaltet“) | Das erste Laden eines Modells dauert 35–75 s; `Output.warmup()` stößt es im Mikrofon-Modus sofort an. ## 8. Nebenläufigkeit — die wichtigsten Regeln 1. **Nie** `engine.transcribe` (oder anderes Blockierendes) direkt in einer `async`-Funktion aufrufen — immer über `worker.transcribe` / `worker.run` bzw. `asyncio.to_thread`. 2. `worker.pending` nur im Event-Loop verändern. 3. In einer WebSocket-Sitzung nur über `_StreamSession.send` senden (Lock). 4. `SttEngine` ist thread-sicher (`_load_lock`, `_run_lock`), aber der Dienst verlässt sich zusätzlich auf den Ein-Thread-Worker für die Warteschlangenlogik. 5. `UtteranceSegmenter` und `StreamResampler` sind **nicht** thread-sicher — eine Instanz pro Stream. 6. Silero-VAD läuft im Event-Loop (gemessen ≈ 0,4 ms Rechenzeit pro 100 ms Audio). Bei sehr vielen gleichzeitigen Streams wäre das der erste Kandidat für einen eigenen Thread. --- ## 9. Konfiguration Alle Einstellungen sind Umgebungsvariablen (vollständige Tabelle: [Bedienungsanleitung §9](../BEDIENUNGSANLEITUNG.md#9-einstellungen)). Gelesen werden sie an genau drei Stellen: | Klasse | Variablen | |---|---| | `stt_core.EngineConfig.from_env` | `STT_MODEL`, `STT_DEVICE`, `STT_COMPUTE_TYPE`, `STT_DEVICE_INDEX`, `STT_CPU_MODEL`, `STT_CPU_THREADS`, `STT_LANGUAGE`, `STT_BEAM_SIZE`, `STT_INITIAL_PROMPT`, `STT_DOWNLOAD_ROOT` | | `stt_core.VadConfig.from_env` | `STT_VAD_THRESHOLD`, `STT_VAD_MIN_SPEECH_MS`, `STT_VAD_SILENCE_MS`, `STT_VAD_PRE_ROLL_MS`, `STT_VAD_MAX_UTTERANCE_S` | | `stt_service.ServiceSettings.from_env` | `STT_MAX_QUEUE`, `STT_MAX_UPLOAD_MB`, `STT_PRELOAD`, `STT_WYOMING_HOST`, `STT_WYOMING_PORT` | Außerdem direkt: `STT_LOG_LEVEL`, `STT_HOST`, `STT_PORT` (`stt_service.py`), `STT_URL` (`stt_cli.py`). Hilfsfunktion `stt_core._env(name, default, cast)`: leere Werte gelten als „nicht gesetzt“, `bool` akzeptiert `1/true/yes/on`. Neue Einstellung = Feld in der passenden Dataclass + Zeile in `from_env` + Tabelle in der Bedienungsanleitung + Test (`test_engine_config_from_env` als Muster). --- ## 10. Entwicklungsumgebung ```bash cd ~/Python_Programs/SpeechToText python3 -m venv --system-site-packages .venv .venv/bin/pip install -r requirements.txt ``` Die venv erbt auf dem Entwicklungsrechner faster-whisper, FastAPI, onnxruntime usw. aus `~/miniforge3`; `wyoming` ist nur in der venv installiert. **Immer `.venv/bin/python` verwenden**, sonst fehlt `wyoming` (Wyoming-Tests werden dann übersprungen, der Dienst startet ohne Wyoming). **Dienst im Entwicklungsbetrieb:** ```bash CUDA_VISIBLE_DEVICES=GPU-83ba6d1f-ebbe-f8c8-1433-153e0ebc3866 STT_LOG_LEVEL=DEBUG .venv/bin/python stt_service.py # schneller Start ohne GPU/Download: STT_MODEL=tiny STT_DEVICE=cpu STT_WYOMING_PORT= .venv/bin/uvicorn stt_service:app --port 9998 --reload ``` **GPU-Umgebung des Entwicklungsrechners:** T600 + 2× RTX 3090. `nvidia-smi` zählt in PCI-Reihenfolge, CUDA „fastest first“ — Indizes stimmen nicht überein, daher GPU per UUID pinnen. GPU 1 ist durch llama.cpp/Ollama nahezu voll; GPU 2 teilen sich chatterbox-tts, Open Notebook (STT/TTS) und dieser Dienst (`large-v3-turbo` ≈ 2,4 GB). Hugging-Face-Modelle liegen unter `$HF_HOME/hub`. **Schnelle Handtests:** ```bash espeak-ng -v de -w /tmp/t.wav "Schalte das Licht im Wohnzimmer ein." curl --data-binary @/tmp/t.wav localhost:9998/transcribe | python3 -m json.tool .venv/bin/python stt_cli.py /tmp/t.wav ``` --- ## 11. Tests ```bash .venv/bin/python -m pytest # 49 Unit-Tests, ~9 s, ohne Modell .venv/bin/python -m pytest -m integration # 5 Integrationstests: Whisper small auf CPU (~20 s), LLM über Ollama (bis ~75 s) .venv/bin/python -m pytest tests/test_service.py -k ws -v STT_TEST_MODEL=large-v3-turbo STT_TEST_DEVICE=cuda .venv/bin/python -m pytest -m integration ``` `pytest.ini` schließt `integration` standardmäßig aus. ### Helfer in `tests/conftest.py` | Helfer | Zweck | |---|---| | `FakeEngine(delay=0)` | Engine ohne Modell; Text = `"audio s"`; zeichnet Aufrufe in `calls` auf; `delay` simuliert Rechenzeit | | `EnergyProb` | deterministische Ersatz-VAD: Fenster-RMS > 0,05 = Sprache | | `make_wav(audio, rate, channels, width)` | float32 → WAV-Bytes (16/32 Bit) | | `tone(sec, freq, amp, rate)` / `silence(sec, rate)` | synthetische Signale | | `espeak_wav(text, voice)` | echte (synthetische) Sprache für Integrationstests; `None` ohne espeak-ng | `conftest.py` setzt `STT_WYOMING_PORT=""`, damit das beim Import erzeugte Modul-`app` keinen TCP-Port belegt. ### Was wie getestet wird | Bereich | Muster | |---|---| | Kernlogik | direkte Funktionsaufrufe (`test_core.py`) | | HTTP | `TestClient(create_app(FakeEngine(), ServiceSettings(wyoming_port=None), …))` | | Nebenläufigkeit (503, nicht blockieren) | `httpx.ASGITransport` + `asyncio.gather`, `FakeEngine(delay=…)`; auf `worker.pending` warten statt fester `sleep`s | | WebSocket | `client.websocket_connect("/ws/stream")`, Hilfsfunktion `_receive_until(ws, "done")` | | Wyoming | echter `start_server(…, port=0)` + `wyoming.client.AsyncTcpClient` | | Ende-zu-Ende | `test_integration.py`: espeak-Sprache → Silero-Segmentierung → Whisper | | LLM-Korrektur | `ScriptedCorrector` überschreibt `_chat` mit vorgegebenen Antworten (Annahme, Verwerfen, Fehler, Stückelung); `test_real_llm_correction` nur mit laufendem Ollama (`STT_TEST_LLM_MODEL`) | Neue Funktionen bitte mit Unit-Test ohne Modell absichern; nur was wirklich Whisper braucht, als `@pytest.mark.integration`. --- ## 12. Erweitern: typische Aufgaben **Neuer HTTP-Endpunkt** — in `create_app` definieren, Audio über `_decode` bzw. `core.pcm16_to_float` beschaffen, Transkription über `_run_transcription`. Test in `test_service.py` mit `_client()`. In `docs/API.md` dokumentieren. **Neuer Transkriptionsparameter** (z. B. Wort-Zeitstempel) — Parameter in `SttEngine.transcribe` ergänzen und an `model.transcribe` durchreichen; bei Bedarf Felder in `Segment`/`Transcript`; in den Endpunkten als Query/Form/`start`-Feld annehmen. `FakeEngine.transcribe` akzeptiert `**kwargs`, bestehende Tests laufen weiter. **Halluzinationsmuster ergänzen** — Regex (klein, ohne Satzzeichen am Ende) in `_HALLUCINATION_PATTERNS`, Parametrisierung in `test_hallucinations_are_detected` **und** ein Gegenbeispiel echter Sprache in `test_real_speech_is_kept`. **Andere VAD** — Klasse mit `__call__(windows: np.ndarray) -> np.ndarray` (eine Wahrscheinlichkeit je 512er-Fenster) und optional `reset()`; im Dienst über `create_app(prob_fn_factory=…)` einsetzen. **Andere Engine** (z. B. anderes STT-Backend) — Unterklasse von `SttEngine`, die `load` und `transcribe` überschreibt und ein `Transcript` liefert (`FakeEngine` zeigt das minimale Muster). **Neuer Client** — gegen [docs/API.md](API.md) programmieren; `stt_cli.py` ist die Referenzimplementierung für Datei-Upload und WebSocket-Streaming. **Version erhöhen** — `stt_core.__version__` (wird von `/health`, FastAPI und Wyoming übernommen). --- ## 13. Designentscheidungen | Entscheidung | Begründung | Verworfene Alternative | |---|---|---| | Äußerungsende per Silero-VAD | natürliche Bedienung, geringe Latenz, für Smarthome üblich | Stoppwort (legacy): unzuverlässig an Blockgrenzen, doppelte Transkription | | Ein Worker-Thread | GPU-Speicher vorhersagbar, keine Konkurrenz um den Kontext; ~0,2 s pro Befehl reicht für einen Haushalt | mehrere Worker (`num_workers`): mehr VRAM, kaum Gewinn auf einer geteilten GPU | | Sofortiges 503 bei voller Queue | „nicht blockieren“: Clients bekommen schnell eine Antwort und können neu versuchen | unbegrenzte Queue: Latenz wächst unbemerkt | | `large-v3-turbo` als Standard | nahezu `large-v3`-Qualität, deutlich schneller, ~2,4 GB statt ~4 GB | `large-v3`: langsamer; `medium`: schlechter bei Deutsch | | CPU-Fallback mit `small` | Dienst bleibt nutzbar, wenn die GPU belegt ist; `small` ist auf CPU noch schnell | Abbruch: Smarthome ohne Spracherkennung | | `condition_on_previous_text=False` | verhindert Wiederholungsschleifen | Standard `True` | | Preload ohne Warten | Dienst sofort erreichbar, `/health` zeigt Fortschritt | blockierender Start: systemd-Timeouts, keine Diagnose | | Wyoming im selben Prozess | ein Modell im Speicher, eine Konfiguration | separater Wyoming-Dienst (`wyoming-faster-whisper`): zweites Modell | | OpenAI-kompatibler Endpunkt | vorhandene OpenAI-Clients (SDK, Voice-Assistant v3 …) nutzbar, nur Basis-URL `…/v1` setzen | nur eigene API | | Roh-Endpunkt `/transcribe` | Mikrocontroller können kein bequemes multipart | nur multipart | | CLI über `pulse`-Gerät | folgt der Systemeinstellung; PortAudio-Default ist falsch | PortAudio-Default (legacy-Fehler) | | LLM-Korrektur nur optional in der CLI, mit Ähnlichkeitsprüfung | LLMs können Inhalte verfälschen und kosten ~1 s; Rohtext muss erhalten bleiben | LLM immer im Dienst (legacy `stt.py`): langsam, unkontrolliert, schnitt bei 500 Tokens ab | | Keine Authentifizierung (vorerst) | Heimnetz-Betrieb, einfache Clients (ESP32) | Token: siehe nächste Schritte | --- ## 14. Bekannte Grenzen und mögliche nächste Schritte **Grenzen** - Wörtlich wiederholte Sätze innerhalb eines 30-s-Fensters fasst Whisper teilweise zusammen. - Keine Zwischenergebnisse während des Sprechens; Transkripte kommen pro Äußerung. - Keine Authentifizierung, kein TLS. - Ein Modell pro Dienstinstanz; Modellwechsel = Neustart. - Wyoming protokolliert Transkripttexte auf `INFO`. - Die Mikrofonpfade der CLI sind mit synthetischer Sprache und Pegelmessung getestet, der WebSocket-Pfad mit echter Sprache in Echtzeit-Simulation — nicht automatisiert mit echtem Mikrofon. **Mögliche nächste Schritte** - Optionales Bearer-Token (`STT_API_TOKEN`) für HTTP/WebSocket. - Metriken (`/metrics` im Prometheus-Format: Latenzen, Queue, Fehler). - Zwischenergebnisse (partielle Transkripte) während langer Äußerungen. - MCP-Adapter analog zu chatterbox-tts-cli (`mcp_adapter.py`). - Remote-Repository auf kitux.de (Forgejo). - Anbindung als STT-Provider im Voice-Assistant v3 (OpenAI-kompatibel bereits möglich). --- ## 15. Konventionen - **Sprache:** Kommentare, Docstrings, Doku, Log-/Fehlermeldungen und Commit-Nachrichten auf Deutsch; Bezeichner englisch. - **Kern ohne I/O:** `stt_core` gibt nichts aus und beendet nichts — Rückgabewerte und Exceptions. - **Logging** über `logging` (`stt`, `stt.service`, `stt.wyoming`), nicht `print` (Ausnahme: CLI-Ausgabe). - **Typen:** Type Hints und `from __future__ import annotations`; Datenobjekte als `@dataclass`. - **Konfiguration** nur über Umgebungsvariablen in den `from_env`-Methoden. - **Tests** zu jeder Änderung; Unit-Tests ohne Modell, Integration mit Marker. - **Commits:** kleine, thematische Commits; Autor `dschlueter `. - **Leere Datei `3`:** entsteht durch einen System-Bug, gehört nie in einen Commit und darf gelöscht werden.