Skip to main content
Use this guide to format and send messages over the GET /ws/stream WebSocket. Ambient and Form filling use the same wire format on this socket. Send each message as a UTF-8 JSON text frame containing exactly one JSON object. Audio must be Base64-encoded and included in the JSON payload. Do not send audio as a binary WebSocket frame.

​
Message format

Each outbound message is a JSON object with a type field. For messages that carry a payload, use the data field. The data value must be:
  • Standard Base64 (RFC 4648).
  • An encoding of the raw bytes you intend to send.
  • Sent as a JSON string, regardless of the programming language you use.
Do not use:
  • Hex encoding.
  • URL-safe Base64.
  • Raw binary inside JSON strings.

​
Start the stream segment

Send one START_TIME message before the audio chunks for a stream segment:
  • data: Base64 encoding of the UTF-8 bytes of an RFC 3339 timestamp.
  • Example timestamp: 2026-04-25T12:34:56Z.

​
Send audio chunks

Send audio with type set to AUDIO:
  • data: Base64 encoding of the raw PCM audio bytes.

​
Send control events

Send control events with type set to EVENT:
Use the event field, not data. Supported values are PAUSE, RESUME, KEEP_ALIVE, CANCEL, and ABORT.
The ambient stream handler acts on PAUSE, RESUME, and CANCEL. While the stream is paused, send KEEP_ALIVE at least once every five seconds per the idle-timeout guidance (maximum pause 30 minutes).
Common use cases:
  • Pause or resume audio.
  • Keep the connection alive.
  • Cancel or abort a stream.
You can send EVENT messages at any point in the stream where control is needed.

​
End the stream segment

Send the final AUDIO message with data set to RU9G:
RU9G is Base64 for ASCII EOF (0x45 0x4F 0x46).
Do not:
  • Send EOF as plain text.
  • Use custom types like end_of_stream.
  • Use binary EOF signaling.

​
Required message order

For each stream segment:
  1. Send one START_TIME message.
  2. Send one or more AUDIO messages with Base64 PCM audio.
  3. Send any EVENT messages when control is needed.
  4. Send a final AUDIO message with data set to RU9G.

​
Example flow

This example shows the outbound message sequence for one ambient stream segment: one START_TIME message, multiple AUDIO chunks, an optional EVENT, and the final RU9G end marker.

​
Audio format and chunking

Use raw PCM audio chunks in each data message after Base64 decode. For more information, refer to: Read Audio capture best practices for capture settings and PCM guidance.

​
Audio streaming recommendations

Sample Rate of 16 kHz

Suki streams audio at 16 kHz, which captures the full range of clinical speech.

Mono Channel

Send a single mono channel of audio, not stereo or multi-channel.

LINEAR16 Encoding

Encode as LINEAR16 (PCM signed 16-bit little-endian). Remove WAV headers or decode to raw PCM before you send.

Audio Chunk Size of 100 ms

Suki supports 100 ms chunks to balance recognition quality, latency, and efficiency. At 16 kHz mono 16-bit, that is about 3200 bytes of raw PCM per chunk.

Stream at Real-Time Speed

Pace audio chunks to match their actual duration and stream at or near real time, rather than sending buffered audio as fast as possible.

​
PCM vs WAV

Raw PCM is audio data without a file container. .wav is a container format and includes headers. If your source is WAV, remove the 44-byte RIFF header, or decode the file to raw PCM before sending. Sending WAV headers as PCM reduces recognition quality and makes debugging harder.
  • Encoding: LINEAR16, PCM signed 16-bit little-endian.
  • Channels: Mono.
  • Sample rate: 16 kHz.

​
Chunk size

Suki supports 100 ms audio chunks to balance recognition quality, latency, and efficiency. At 16 kHz, mono, 16-bit audio, each chunk contains about 3200 bytes of raw PCM before Base64 encoding.
  • Send each chunk as one AUDIO JSON text frame.
  • Keep chunks at 100 ms throughout active streaming.
  • Pace chunks at or near real time instead of sending buffered audio as quickly as possible.
  • Send audio at least once every 25 seconds while the stream is active, or Suki disconnects the stream. When the stream is paused, follow the KEEP_ALIVE guidance.

​
Encode each chunk

For every AUDIO message:
  1. Take raw PCM bytes.
  2. Encode the bytes using standard Base64 (RFC 4648).
  3. Send the encoded string as data.

Stream Ambient Audio

How Ambient streaming works, JSON text rules, and when to use /ws/stream.

Dictation Wire Format

Outbound message contract for Dictation GET /ws/transcribe.

Audio Capture Best Practices

Capture format, environment, gain, and network readiness before you stream.

Complete the Session

Close the socket, end with REST, and troubleshoot common errors.

​
Next steps

Follow Complete the session after streaming to close the socket, end the session, and troubleshoot errors. Copy the Ambient WebSocket client code example for a full client implementation. Review Audio capture and streaming FAQs for codec, chunk size, and reconnect guidance.
Last modified on August 10, 2026