STT Troubleshooting

Problemy z VistaScribe

Symptom	Prawdopodobna przyczyna	Rozwiązanie
`GET /healthz` zwraca `{"ok":false}`	Whisper model downloading lub failed to load	Sprawdź `logs/VistaScribe.log`; upewnij się że `models/whisper-<variant>` istnieje i `WHISPER_DIR` wskazuje poprawnie
`curl: (7) Failed to connect to 127.0.0.1:8237`	Backend nie działa lub port conflict	Uruchom `./VistaScribe start backend`; sprawdź `lsof -i :8237`
`HTTP 413` z `/transcribe`	Upload większy niż `BACKEND_MAX_UPLOAD_MB`	Re-encode audio lub zwiększ env var przed startem
Streaming nie emituje `transcript.final`	Client zapomniał wysłać `flush` lub `end`	Zawsze wysyłaj flush/end po ostatnim chunku
WebSocket zamyka się z error JSON	Invalid message schema (brak `audio_base64`)	Użyj tej samej struktury payload co Voice & Chat Lab
AI formatting zwraca raw text	`ai_formatting_enabled` false lub brak API key	Toggle “AI Formatting” w tray menu, ustaw `HARMONY_BASE_URL` + `HARMONY_API_KEY`, verify z `/healthz`
`/demo/chat` zwraca 500	Invalid Harmony/Ollama credentials	Sprawdź logi backendu dla exact exception; fix API key lub upewnij się że local Ollama daemon działa
`ValueError: audio_base64 required` w logach	Client wysłał malformed NDJSON lub binary HTTP body	Upewnij się że każdy `chunk` JSON zawiera `audio_base64` (base64-encoded PCM16)

Problemy z WebSocket (produkcyjny)

Symptom	Prawdopodobna przyczyna	Rozwiązanie
Connection refused	Firewall lub network issues	Sprawdź connectivity do `api.libraxis.cloud`
401 Unauthorized	Invalid lub expired `LIBRAXIS_API_KEY`	Sprawdź klucz w 1Password, refresh jeśli potrzeba
Connection drops po ~5 min	Idle timeout (300s)	Wysyłaj heartbeat lub audio chunks regularnie
Brak `interim` messages	Server busy lub low confidence	Check network latency; interim może być suppressed przy niskiej confidence
`final` z pustym text	Brak rozpoznawalnej mowy	Sprawdź jakość audio (noise, poziom głośności)

Audio format issues

Symptom	Rozwiązanie
Garbled transcription	Upewnij się że format to PCM16LE mono 16kHz
”Unsupported format” error	Transcode do PCM16 przed wysłaniem
Very slow transcription	Zmniejsz chunk size (32kB recommended)

Diagnostyka

Logi

# VistaScribe logs
tail -f VistaScribe/logs/VistaScribe.log

# Vista secure_logger
# sprawdź logs/vista-debug.log dla STT events

Test connectivity

# VistaScribe health
curl http://127.0.0.1:8237/healthz | jq

# VistaScribe version
curl http://127.0.0.1:8237/version | jq

# Production WebSocket (wymaga wscat lub podobnego)
wscat -c "wss://api.libraxis.cloud/stt/v1/stream" \
  -H "x-api-key: $LIBRAXIS_API_KEY"

OpenAPI spec

Import openapi.json z folderu VistaScribe do Insomnia/Postman dla generowania client code.

General tips

Tail logs during tests - hotkey events, backend status, AI errors
Check audio format - PCM16LE mono 16kHz to preferowany format
Verify API keys - sprawdź ważność i uprawnienia
Monitor network - WebSocket wymaga stabilnego połączenia
Check disk space - modele Whisper zajmują miejsce

Recovery actions

Problem	Quick fix
VistaScribe nie startuje	`./VistaScribe stop && ./VistaScribe start backend`
Whisper model corrupted	Delete `models/whisper-*` i restart (auto-download)
Port 8237 zajęty	`lsof -i :8237` → `kill <PID>`
WebSocket rate limited	Poczekaj 60s, zmniejsz connection frequency