Docs / Speech

Streaming API

The live transcription WebSocket: connection, audio frames, server messages, and session limits.

Endpoint and authentication

GET /v1/audio/stream upgrades to a standard WebSocket carrying the same live session as fermion listen: same segmentation, same cadence, same decode. Start the server with a speech model:

shell

fermion serve --model phonon

Connect to ws://127.0.0.1:8000/v1/audio/stream. With an API key, send Authorization: Bearer or append ?api_key=KEY; the query form exists because the browser WebSocket() constructor cannot set headers.

Sending audio

The client sends one JSON text frame first, then binary frames of raw mono PCM.

The opening frame is {"sample_rate": 16000, "format": "pcm_f32le"}. Both fields are optional, pcm_s16le is also accepted, and the sample rate must be 16000.
Binary frames carry raw PCM. Frame boundaries need not align to sample boundaries.
Finish with a text frame {"type":"end"} or a clean close; both finalize whatever audio is buffered.

Server frames

Every server message is a JSON text frame.

Frame	Meaning
{"type": "partial"}	The whole current hypothesis for the in-flight phrase. Each partial replaces the previous one.
{"type": "final"}	A finished segment, after about 0.7 s of silence or at the 30 s segment cap.
{"type": "done"}	The full transcript after end or close, followed by a clean close.
{"type": "error"}	Any refusal, followed by a close.

Session limits

One live stream runs at a time. A second concurrent stream is refused immediately with an in-band error frame and close code 1013 rather than queued.
A stream that sends nothing for 90 s closes with code 1001.

The Docker image serves the identical protocol, so one client works against both.