whisper-stt-cli/README.md

SpeechToText

Lokaler, schneller Spracherkennungs-Dienst (Sprache → Text) auf Basis von faster-whisper — das STT-Gegenstück zu 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	Anwender	Installation, Starten, CLI, Mikrofon, Home Assistant, Einstellungen, Fehlerbehebung
docs/API.md	Client-Entwickler	HTTP, WebSocket-Protokoll, Wyoming, Fehlercodes, Beispiele (Python, curl, ESP32)
docs/ENTWICKLER.md	Programmierer am Projekt	Architektur, Module, Nebenläufigkeit, Tests, Erweitern, Designentscheidungen

Schnellstart

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

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

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

.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.

Lizenz und Autor

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