<!-- status: canonical -->
<!-- lastReviewed: 2026-05-10 -->
<!-- verifiedAgainst: platform-core/modules/{connectors/connectorVoiceGoogle.py,interfaces/interfaceVoiceObjects.py,routes/routeVoiceGoogle.py}; platform-core/modules/features/{commcoach/serviceCommcoach.py,teamsbot/service.py}; ui-nyla/src/hooks/useSpeechAudioCapture.ts; ui-nyla/src/pages/views/commcoach/useVoiceController.ts -->

# Google Voice (STT / TTS)

Zentrale Sprach-Pipeline im Gateway: **Google Cloud Speech-to-Text (v1)** und **Text-to-Speech** über die Fassade `VoiceObjects` (`interfaceVoiceObjects.py`) und den Connector `ConnectorGoogleSpeech` (`connectorVoiceGoogle.py`). Kein direkter Feature-Code soll den Connector umgehen; Billing-Hooks hängen an der Interface-Schicht (u. a. Streaming-STT bei finalen Segmenten).

## Batch-Erkennung (`speechToText`)

- **API:** `SpeechClient.recognize` (ein Request pro Audioclip).
- **Parameter (optional, abwaertskompatibel):**
  - **`model`:** z. B. `latest_long` (Default), `latest_short`.
  - **`lightweight`:** `True` schaltet u. a. ab: Word-Timestamps, Word-Confidence, `max_alternatives>1`, `use_enhanced`. Ziel: geringere Latenz/Kosten bei Kurzäusserungen.
  - **`audioFormat`:** z. B. `webm_opus`, `linear16`, `mp3`, `flac`, `wav` — wenn gesetzt, entfällt `validateAudioFormat()` (Fast-Path); fehlende Sample-Rate wird formattypisch defaulted (z. B. `webm_opus` → 48 kHz).
- **Fallbacks:** Bei leeren Ergebnissen (wenn nicht `skipFallbacks`) weiterhin Encoding-/Modell-Matrix; erstes Fallback-Modell ist der vom Caller gewählte `model`-Wert.

## Streaming-Erkennung

- **Route:** `POST /voice-google/stt/token` (kurzlebiges `wsToken`), WebSocket **`/voice-google/stt/stream?wsToken=...`** (`routeVoiceGoogle.py`).
- **Client-Protokoll (JSON):**
  - `open`: `language`, optional `model`, `lightweight`, `singleUtterance` (Booleans).
  - `audio`: `chunk` (Base64), typisch WebM/Opus-Fragmente vom `MediaRecorder`.
  - `close` / `ping` / `pong` unveraendert.
- **Server-Antworten:** `interim`, `final`, optional **`end_of_single_utterance`** (mit `audioDurationSec`) wenn Google Single-Utterance-Modus endet — Client sendet daraufhin erneut `open` mit denselben STT-Optionen (Recorder laeuft weiter).
- **Connector:** `streamingRecognize` — `StreamingRecognitionConfig.single_utterance` steuerbar; **Abrechnungs-Dauer** fuer Finals bevorzugt aus `result_end_time` der Streaming-Results (Fallback: Byte-Heuristik).

## Feature-Zuordnung (Ist-Stand)

| Bereich | STT-Pfad | Konfiguration (Kurz) |
|---------|----------|----------------------|
| **CommCoach Live** | Streaming WS → Text → Coach | Frontend (`useVoiceStream`): `latest_short`, `lightweight`, `singleUtterance: true` (`useVoiceController`). |
| **CommCoach Batch** | `processAudioMessage` → `speechToText` | `latest_short`, `lightweight: true` (Format weiterhin Auto-Detect wenn kein `audioFormat`). |
| **Workspace** | Gleicher generischer WS | `start(language)` ohne Extra-Optionen → Defaults wie frueher (`latest_long`, kein Single-Utterance). |
| **Teamsbot** | Pro Audio-Chunk `speechToText` (Batch) | Gemeinsamer Connector; **`audioFormat: linear16`** (bekannte PCM-Chunks); Modell/Default wie bisher `latest_long` + volle Features (`lightweight: false`). |
| **Agent-Tool** `_mediaTools.speechToText` | Batch | Keine zusaetzlichen Argumente → Default-Verhalten. |

## TTS

Unveraendert ueber `textToSpeech` / Gemini-TTS-Pfad im Connector; diese Seite fokussiert STT.

## Weiterfuehrung

- Evaluation **Speech-to-Text v2 / Chirp:** [`wiki/c-work/1-plan/stt-chirp-v2-evaluation.md`](../../c-work/1-plan/stt-chirp-v2-evaluation.md).