dschlueter
340100210d
- BEDIENUNGSANLEITUNG.md: Installation, Betrieb, CLI, Mikrofon, Home Assistant, Einstellungen, Modellwahl, Fehlerbehebung, Datenschutz - docs/API.md: HTTP, WebSocket-Protokoll, Wyoming, Fehlercodes, geprüfte Beispiele - docs/ENTWICKLER.md: Architektur, Module, Nebenläufigkeit, Tests, Erweitern, Designentscheidungen - CLAUDE.md: Verweis auf die Dokumentation Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
90 lines
4.1 KiB
Markdown
90 lines
4.1 KiB
Markdown
# 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.
|
|
|
|
## 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, Tests, Erweitern, Designentscheidungen |
|
|
|
|
## 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)
|
|
```
|
|
|
|
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 |
|
|
| `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 # 36 Unit-Tests, ohne Modell
|
|
.venv/bin/python -m pytest -m integration # 4 Integrationstests: Whisper small (CPU) + Silero, espeak-ng-Sprache
|
|
```
|
|
|
|
## 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).
|