whisper-stt-cli/README.md

# SpeechToText

Lokaler, schneller Spracherkennungs-Dienst (Sprache → Text) auf Basis von
[faster-whisper](https://github.com/SYSTRAN/faster-whisper) — das STT-Gegenstück zu
[chatterbox-tts-cli](https://kitux.de/forgejo/dschlueter/chatterbox-tts-cli).

Gedacht als Baustein für Sprachassistenten und Smarthome: **Home Assistant** (Wyoming),
**Mikrocontroller** wie ESP32 (HTTP/WebSocket), **Skripte** (CLI) und **OpenAI-kompatible Tools**.

- **Schnell:** Modell bleibt geladen. Gemessen auf RTX 3090 mit `large-v3-turbo`:
  5,8 s Audio → 0,2 s, 35 s Audio → 0,7 s Rechenzeit; ~2,4 GB VRAM.
- **Nicht blockierend:** Inferenz in einem Worker-Thread, begrenzte Warteschlange (503 statt Stau).
- **Äußerungsende per Sprechpause** (Silero-VAD) statt Stoppwort; Text ca. 1 s nach Sprechende.
- **Robust:** automatischer CPU-Fallback, beliebige Audioformate, Filter gegen Whisper-Halluzinationen.
- **Lokal:** keine Cloud; Internet nur zum einmaligen Herunterladen des Modells.
- **Optionale LLM-Korrektur** (`--llm-correct`, lokales `gemma4:12b`) mit Schutz gegen verfälschte Antworten.

## Dokumentation

| Dokument | Für wen | Inhalt |
|---|---|---|
| **[BEDIENUNGSANLEITUNG.md](BEDIENUNGSANLEITUNG.md)** | Anwender | Installation, Starten, CLI, Mikrofon, Home Assistant, Einstellungen, Fehlerbehebung |
| **[docs/API.md](docs/API.md)** | Client-Entwickler | HTTP, WebSocket-Protokoll, Wyoming, Fehlercodes, Beispiele (Python, curl, ESP32) |
| **[docs/ENTWICKLER.md](docs/ENTWICKLER.md)** | Programmierer am Projekt | Architektur, Module, Nebenläufigkeit, LLM-Korrektur, Tests, Erweitern, Designentscheidungen |
| **[CHANGELOG.md](CHANGELOG.md)** | alle | Änderungen je Version (aktuell 0.2.0) |

## Schnellstart

```bash
cd ~/Python_Programs/SpeechToText
python3 -m venv --system-site-packages .venv
.venv/bin/pip install -r requirements.txt

# Dienst starten (GPU per UUID aus `nvidia-smi -L`; ohne GPU einfach weglassen)
CUDA_VISIBLE_DEVICES=GPU-<uuid> .venv/bin/python stt_service.py

# in einem zweiten Terminal
curl http://127.0.0.1:9998/health                  # "status":"ok" = bereit
.venv/bin/python stt_cli.py aufnahme.wav            # Datei → Text
.venv/bin/python stt_cli.py -v                      # Mikrofon → Text (Strg+C beendet)
.venv/bin/python stt_cli.py --until-enter            # Pausen erlaubt, Enter beendet → ein Text
.venv/bin/python stt_cli.py --until-enter --llm-correct   # zusätzlich per lokalem LLM korrigieren (Ollama)
```

Beim ersten Start wird das Modell geladen (`large-v3-turbo` ≈ 1,6 GB). Schnittstellen zum Ausprobieren
im Browser: http://127.0.0.1:9998/docs

## Schnittstellen auf einen Blick

| Schnittstelle | Adresse | Zweck |
|---|---|---|
| `GET /health` | `:9998` | Status, Modell, Gerät, Warteschlange |
| `POST /v1/audio/transcriptions` | `:9998` | OpenAI-kompatibel (multipart) |
| `POST /transcribe` | `:9998` | Audio direkt im Body (WAV/MP3/… oder rohes PCM) — ideal für Mikrocontroller |
| `WS /ws/stream` | `:9998` | Live-Streaming mit automatischer Satzende-Erkennung |
| Wyoming | `tcp :10300` | Home Assistant / ESPHome-Satelliten |

```bash
curl --data-binary @aufnahme.wav http://127.0.0.1:9998/transcribe
curl -F file=@aufnahme.mp3 http://127.0.0.1:9998/v1/audio/transcriptions
```

> Der Dienst hat keine Authentifizierung — nur im eigenen Netz betreiben.

## Projektaufbau

| Datei | Aufgabe |
|---|---|
| `stt_core.py` | Kern: Whisper-Engine, Audio-Hilfen, Halluzinationsfilter, Satzende-Erkennung |
| `stt_service.py` | FastAPI-Dienst: HTTP, WebSocket, Worker, Start des Wyoming-Servers |
| `stt_wyoming.py` | Wyoming-Protokoll für Home Assistant |
| `stt_cli.py` | Kommandozeile: Dateien und Mikrofon über den Dienst oder lokal |
| `stt_llm.py` | optionale LLM-Nachkorrektur (Ollama oder OpenAI-kompatibel), nur mit `--llm-correct` |
| `tests/` | Unit-Tests (ohne Modell) und Integrationstests (echtes Whisper) |
| `deploy/stt-service.service` | systemd-User-Unit für den Dauerbetrieb |
| `legacy/` | alte Einzelskripte `stt.py`, `stt_respeaker.py` (historisch, nicht gepflegt) |

## Tests

```bash
.venv/bin/python -m pytest                    # 49 Unit-Tests, ohne Modell
.venv/bin/python -m pytest -m integration     # 5 Integrationstests: Whisper small (CPU) + Silero, espeak-ng; LLM über Ollama
```

## Bekannte Grenzen

- Wörtlich wiederholte Sätze innerhalb eines 30-s-Fensters fasst Whisper teils zusammen
  (bei natürlicher Sprache selten).
- Keine Zwischenergebnisse während des Sprechens — Text kommt pro Äußerung.
- Keine Authentifizierung und kein TLS.
- LLM-Korrektur nur in der CLI; kostet ~1 s pro Text, das erste Laden des LLM rund eine Minute.

## Lizenz und Autor

Autor: dschlueter. Verwendete Komponenten: faster-whisper (MIT), OpenAI Whisper-Modelle (MIT),
Silero VAD (MIT), Wyoming (MIT), FastAPI (MIT).