# Voxtral-STT-Satellit (M0.3)

Streaming-STT via **Voxtral-Mini-4B-Realtime-2602** (Mistral, Apache 2.0) auf
vLLM. Ersetzt whisper als STT — genauer (~5,9 % WER vs 7,4 % FLEURS) und mit
echtem Realtime-Streaming. Deutsch ist in den 13 Sprachen abgedeckt.

Zwei Container:
- **`voxtral-vllm`** — das Modell auf vLLM (GPU). Exponiert die Realtime-WS-API.
- **`voxtral-bridge`** — CPU-Glue: RVS ⇄ vLLM-Realtime-WS. Macht das Endpointing
  selbst (adaptiver Rausch-Boden-VAD, identisch zur whisper-Bridge / M0.1).

## ⚠️ Hardware-Realität — läuft NICHT auf der 3060

Das Realtime-Modell braucht laut [vLLM-Rezept](https://recipes.vllm.ai/mistralai/Voxtral-Mini-4B-Realtime-2602)
**≥ 16 GB VRAM (BF16, keine Quant)**. Die RTX 3060 hat 12 GB → passt nicht.

- **Interim-gpubox (nur 3060):** whisper (mit M0.1-Fix) + F5-TTS bleiben aktiv.
  Voxtral NICHT starten.
- **Ab der 24-GB-Karte:** Voxtral-Profil hochziehen, whisper wird Fallback.

Deshalb liegen beide Services hinter dem Compose-**Profil `voxtral`** und starten
NUR explizit — sonst würden whisper *und* voxtral dieselben `stt_*`-Messages
beantworten (Kollision).

## Starten (erst wenn die 24-GB-Karte drin ist)

```bash
cd xtts
docker compose --profile voxtral up -d --build
docker logs -f aria-voxtral-vllm      # laedt Modell (mehrere GB, dauert)
docker logs -f aria-voxtral-bridge    # "RVS verbunden" + service_status ready
```
Whisper vorher stoppen, damit nur eine STT-Engine antwortet:
```bash
docker compose stop whisper-bridge
```

## ⚠️ Auf echter Hardware verifizieren (blind gebaut, kein Test hier)

1. **vLLM-Version ≥ 0.20.0** und die **Serve-Form**. Das Rezept nutzt
   `vllm serve <model> …`. Falls das `vllm/vllm-openai`-Image einen anderen
   Entrypoint hat, das `command:` in `docker-compose.yml` anpassen
   (Rezept-Command steht dort als Kommentar).
2. **Realtime-WS-Frames.** Die exakten Event-Namen sind in `bridge.py` ganz oben
   als Konstanten gebündelt (`VLLM_SEND_APPEND`, `VLLM_DELTA_SUFFIXES`, …),
   modelliert nach dem OpenAI-Realtime-Schema. Gegen das offizielle
   **vLLM-Realtime-Client-Beispiel** prüfen und dort anpassen — nur an dieser
   einen Stelle. Das Response-Handling ist bereits defensiv (mehrere Feldnamen).
3. **Endpoint-URL/Port.** Default `ws://voxtral-vllm:8000/v1/realtime` — prüfen ob
   vLLM auf 8000 lauscht und `/v1/realtime` registriert (Log-Zeile
   `Route: /v1/realtime`).
4. **Endpointing.** Voxtral liefert keine eigene VAD → unser adaptiver Endpointer
   entscheidet (akustisch + semantisch am Delta-Wachstum). `endpointMs` kommt wie
   bei whisper aus der App; `voiceFactor` per Session tunebar.

## Protokoll (RVS, identisch zu whisper — drop-in)

Rein: `stt_stream_start`, `stt_audio_chunk` (16 kHz mono s16le, base64), `stt_stream_end`.
Raus: `stt_partial`, `stt_endpoint` (das Event, auf das aria-bridge horcht), `stt_stream_done`.

## TTS-Hinweis

Voxtral-**TTS** (Voice-Cloning) ist hier NICHT enthalten — braucht ebenfalls
16 GB VRAM und ist ein eigener Bau. Bis zur 24-GB-Karte bleibt **F5-TTS** aktiv.
Danach: eigener `voxtral-tts`-Satellit (separates Ticket).

## Quellen
- Rezept: https://recipes.vllm.ai/mistralai/Voxtral-Mini-4B-Realtime-2602
- vLLM Speech-to-Text: https://docs.vllm.ai/en/latest/serving/online_serving/speech_to_text/
- Modell: https://huggingface.co/mistralai/Voxtral-Mini-4B-Realtime-2602