STT WebSocket

Production endpoint dla real-time speech-to-text używany przez Vista clients.

Endpoint

Parametr	Wartość
URL	wss://api.libraxis.cloud/stt/v1/stream
Auth	x-api-key: <LIBRAXIS_API_KEY>
Protocol	JSON (init → audio → interim/final → end)

Protokół

sequenceDiagram
    participant C as Client
    participant S as Server

    C->>S: init (language, sample_rate, encoding)
    S-->>C: ready (session_id, model, language)

    loop Audio streaming
        C->>S: audio (base64 PCM16)
        S-->>C: interim (text, confidence)
    end

    C->>S: end
    S-->>C: final (text, confidence, words)
    S-->>C: ended

Init

{
  "type": "init",
  "language": "pl",
  "sample_rate": 16000,
  "encoding": "pcm16",
  "session_id": "optional"
}

Server odpowiada ready:

{
  "type": "ready",
  "session_id": "sess_abc",
  "model": "whisper-large-v3",
  "language": "pl",
  "sample_rate": 16000
}

Audio chunks

{
  "type": "audio",
  "audio": "<base64 of PCM16LE mono @16kHz>"
}

• Chunk size: 20ms–1s
• Recommended: 32kB (~1s)

Results

Interim (podczas mówienia)

{
  "type": "interim",
  "text": "...",
  "confidence": 0.85,
  "language": "pl"
}

Final (po ~1s ciszy / buffer / end)

{
  "type": "final",
  "text": "...",
  "confidence": 0.94,
  "words": [
    {
      "word": "...",
      "start": 0.0,
      "end": 0.5,
      "confidence": 0.96
    }
  ]
}

Control messages

Message	Response	Opis
{"type": "pause"}	—	Pauza streamingu
{"type": "resume"}	—	Wznowienie
{"type": "end"}	{"type": "ended"}	Zakończenie sesji

Limity

Limit	Wartość
Max global connections	100
Per IP	10
Per API key	20
Idle timeout	300s
Max session duration	3600s

Integracja z Vista

Kluczowe pliki

Plik	Rola
src-tauri/src/engines/recordings/visit_audio.rs	libraxis_stt::WebsocketClient
unified_ai/service_resolver/provider_registry.rs	Provider routing
src/hooks/audio/useAudioRecording/uploadController.ts	FE upload controller

Dev vs Production

Środowisko	URL
Production	wss://api.libraxis.cloud/stt/v1/stream
Development	VISTASCRIBE_URL via provider_registry

Audio format

• Preferowany: PCM16LE 16kHz mono
• Jeśli input OGG/OPUS: transcode w kliencie do PCM16 (convert_to_pcm_stereo)

Obsługa w UI

1. Handle interim/final messages
2. Surface partials w UI
3. Send end on stream completion lub gdy user przestaje mówić

Error handling

Errors z recoverable=true nie powinny przerywać sesji:

• Retry lub kontynuuj streaming
• Log do secure_logger dla visibility

Przykłady

Node.js

Minimalny client z ffmpeg - patrz ~/.ai-collaborators/ws-stt-quickstart.md

Python

Copy sample i ustaw LIBRAXIS_API_KEY