VistaScribe

VistaScribe to lokalny serwer STT oparty na FastAPI. Obsługuje speech-to-text, formatowanie AI i diagnostykę.

Podstawowe informacje

Parametr	Wartość
Base URL	http://127.0.0.1:8237
Framework	FastAPI
Firewall	Loopback-only

Endpointy

Endpoint	Transport	Purpose
GET /healthz	HTTP	Liveness/readiness - Whisper availability + AI provider info
GET /version	HTTP	Build metadata - model paths, Light+ status, AI toggles
POST /transcribe	Multipart HTTP	Single-shot STT (wav/mp3/m4a/flac/webm)
POST /stream/transcribe	Chunked HTTP (NDJSON)	Streaming STT bez socketów
WS /ws/transcribe	WebSocket	Bidirectional streaming STT - najlepsza latencja
POST /format	JSON	AI formatting only (Light+ → Harmony/Ollama)
POST /stt_and_format	Multipart HTTP	Convenience: /transcribe + /format
POST /demo/chat	JSON	Chat proxy dla Voice & Chat Lab

Health check

curl http://127.0.0.1:8237/healthz | jq

Single-shot transcription

curl -X POST \
  -F "audio=@/path/to/sample.wav" \
  http://127.0.0.1:8237/transcribe

Response:

{ "text": "Pan pies czuje się dobrze..." }

NDJSON streaming

Send newline-delimited JSON (chunked):

cat <<'PAYLOAD' | curl -X POST \
  -H 'Content-Type: application/x-ndjson' \
  --data-binary @- \
  http://127.0.0.1:8237/stream/transcribe
{"type":"chunk","audio_base64":"<PCM16 base64>","sample_rate":16000}
{"type":"chunk","audio_base64":"...","last":true}
PAYLOAD

Response (also NDJSON):

{"type":"hello","protocol":"stt-jsonl-v1"}
{"type":"ack","received_bytes":32768}
{"type":"transcript.final","text":"..."}
{"type":"stream.closed"}

Notatka

To jest chunked NDJSON, nie SSE. Działa z każdym HTTP clientem wspierającym incremental reads (Fetch ReadableStream, httpx .aiter_lines(), NSURLSession delegate).

WebSocket streaming

Ta sama schema jak NDJSON:

const ws = new WebSocket('ws://127.0.0.1:8237/ws/transcribe');
ws.onmessage = (event) => console.log(JSON.parse(event.data));
ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'chunk',
    audio_base64: '<PCM16 base64>',
    sample_rate: 16000,
  }));
  ws.send(JSON.stringify({ type: 'end' }));
};

Oczekiwane eventy: hello, ack, transcript.final, stream.closed.

Stream semantics

Message	Response	Opis
chunk	ack (received_bytes)	PCM16 base64 + optional sample_rate/encoding
flush	transcript.final	Immediate transcription
end	transcript.final + stream.closed	Flush and close

Formatting only

curl -X POST http://127.0.0.1:8237/format \
  -H 'Content-Type: application/json' \
  -d '{"text":"pan pies jest zdrowy.","assistive":false}'

Combined STT + formatting

curl -X POST \
  -F "audio=@/path/to/sample.wav" \
  -F "instruction=stress important diagnoses" \
  http://127.0.0.1:8237/stt_and_format

Transport mix

Scenariusz	Rekomendacja
Najniższa latencja (hands-off mode)	WebSocket /ws/transcribe
Pure-HTTP (Safari extension, service worker)	/stream/transcribe
Batch uploads (drag-and-drop)	/transcribe

Limity

Limit	Wartość	Konfiguracja
Max upload size	20 MB	BACKEND_MAX_UPLOAD_MB

Konfiguracja AI

Zmienna	Opis
HARMONY_BASE_URL	URL do Harmony API
HARMONY_API_KEY	Klucz API
ai_formatting_enabled	Toggle w tray menu