---
title: "Streaming API"
description: "The live transcription WebSocket: connection, audio frames, server messages, and session limits."
canonical: "https://www.fermionresearch.com/docs/speech-streaming/"
source: "Fermion Research"
---

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:

```text
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.

Source: [https://www.fermionresearch.com/docs/speech-streaming/](https://www.fermionresearch.com/docs/speech-streaming/)