Stream Ambient Audio - Overview

Quick summary

Streaming sends live visit audio to Suki over WebSocket after you create a session and seed context. The WebSocket carries JSON text frames for audio and control messages. Final notes, form fields, transcripts, and structured data come from the matching product REST APIs after you end the session.

Last updated:August 2026

This guide explains how to stream live audio to GET /ws/stream after you create an ambient session and seed context. The WebSocket is used only to send audio and exchange control messages. Use other Ambient REST APIs to end the session, check processing status, and retrieve transcripts, notes, and structured data. Form filling sessions use the same Partner WebSocket and the same ambient message protocol. If you are building clinical documentation workflows, including note sections, review experiences, and EHR handoff, start with Ambient clinical documentation. Streaming audio with the Ambient APIs lets you:

Capture audio from your own backend, mobile app, or custom client.
Stream visit audio in small chunks while the encounter is in progress.
Pause, resume, or keep a paused stream alive by sending EVENT messages.
Complete the stream and retrieve results through the Ambient REST APIs.

Before you begin

If you do not have credentials yet:

Complete Partner onboarding.
Complete Partner authentication to get an sdp_suki_token.
Use the staging base URL for API examples: https://sdp.suki-stage.com, or ask your Suki representative for the staging base URL.

To stream audio successfully, your application must:

Authenticate and obtain an sdp_suki_token.
Create an ambient session and seed context before opening the WebSocket connection.
Capture mono LINEAR16 PCM audio at 16 kHz, split it into chunks, Base64 encode each chunk, and send each message as a JSON text frame.
Close the WebSocket when streaming is complete, call End ambient session, and retrieve transcripts, notes, and structured data using the Ambient REST APIs.

Read the following related guides and references:

Click Each Button to Learn More

Audio Streaming API Streaming Comparison Architecture Diagram Wire Format Audio Capture Best Practices Complete the Session

Both Form filling and Ambient clinical note sessions use the parameter name ambient_session_id in the API reference. Those identifiers refer to different sessions.
Use only the ID returned from Form filling Create Form filling session for Form filling REST calls and for /ws/stream. Refer to Form filling basic usage.

When to use Ambient or Form filling streaming vs Dictation streaming

Ambient or Form filling streaming and Dictation streaming solve different problems.

Use Ambient or Form filling streaming (GET /ws/stream) when you want to push visit audio into an ambient or Form filling session for note generation or form output. You retrieve results mainly with REST after you end the session.
Use Dictation streaming (GET /ws/transcribe) when the provider needs real-time transcript text in your application. Refer to Stream Dictation audio.

Decide before you build your streaming client

Before you implement production streaming, align on a few engineering decisions. Agree on who owns capture, what the WebSocket owns versus REST, when you may open or reconnect the socket, how you handle pause and keep-alive, and which audio format you will send. Those choices shape handshake behavior, reconnect logic, and how you retrieve results. Use the following sections to align your team.

Who Owns Capture and the WebSocket Client

This guide is for Ambient APIs. Your application owns the microphone or media pipeline, PCM chunking, Base64 encoding, the WebSocket client, and the session lifecycle on GET /ws/stream.If you do not want to own that streaming stack, choose a different capture path:

Web SDK: Suki provides browser capture and review UI. Your application supplies encounter context and handles note handoff after submit.
Headless Web SDK: Your React application owns recording controls, status, and review UI through SDK hooks, not the Partner WebSocket wire format in this guide.

Refer to the capture path table in Ambient clinical documentation.For Ambient API streaming, use the same base host for REST and WebSocket in a given environment. Your partnership team confirms which host and credentials apply. Refer to Streaming architecture.

What the WebSocket Owns vs What REST Owns

/ws/stream streams audio and accepts control messages such as PAUSE, RESUME, CANCEL, and KEEP_ALIVE. It does not replace session create, end session, or result retrieval.After you send the ambient end marker and close the socket:

End the session with End ambient session.
Poll status and fetch transcript, note content, and structured data with ambient content REST APIs.

Final transcripts and notes are not guaranteed to arrive over WebSocket. Treat REST APIs as the source of truth. Refer to Complete the session after streaming.

Session Readiness and Reconnect Rules

Create the ambient session and seed context before you open /ws/stream.

Opening /ws/stream before the session and context are ready often leads to handshake failures or a broken stream. Refer to the Audio streaming API prerequisites.

You can reconnect to /ws/stream using the same ambient_session_id only while the session status is CREATED. Otherwise the handshake returns FailedPrecondition. Refer to Audio capture best practices and Complete the session after streaming.

Pause, Keep-Alive, and Idle Timeouts

While audio is flowing, send audio at least once every 25 seconds, or Suki disconnects the stream.While the stream is paused, send a KEEP_ALIVE event at least every 5 seconds. An ambient session can remain paused for up to 30 minutes when keep-alives are maintained.Refer to Audio capture best practices and Streaming architecture.

Audio Format and Session Length

Capture mono LINEAR16 (PCM signed 16-bit little-endian) at 16 kHz. Stream about 100 ms chunks. At that rate, each chunk is about 3200 bytes of raw PCM. Base64 encode the bytes in the data field and stream at or near real-time speed. Strip WAV headers before you encode.

Sessions shorter than 1 minute may not contain enough audio for note generation and can be marked as skipped.

Refer to Audio capture best practices and WebSocket streaming wire format.

How Ambient or Form filling streaming works

Create Session and Seed Context

Create an Ambient session and Seed session context.

Open the WebSocket

Open a WebSocket connection to GET /ws/stream.

Send START_TIME

Send one START_TIME message for the stream segment.

Stream Audio Chunks

Send one JSON message per audio chunk.

Send Optional EVENT Messages

Optionally send EVENT messages, such as PAUSE, RESUME, or KEEP_ALIVE, when control is needed.

Send the Ambient End Marker

Send the ambient end marker as the final AUDIO message with data: RU9G.

Close the Socket and Finish with REST

Close the socket, then use End ambient session to end the session and retrieve results.

For handshake details, refer to the Audio streaming API. For exact JSON shapes and required message order, refer to WebSocket streaming wire format.

Ambient streaming uses JSON text frames. Do not send raw binary audio frames to this endpoint.

Verify your first Ambient stream

Before you design the full production streaming client, confirm that your staging integration can complete the core path:

Authenticate successfully and use the returned sdp_suki_token in follow-up REST and WebSocket requests.
Create an ambient session, seed context, and store the returned ambient_session_id.
Open /ws/stream, send START_TIME, stream mono PCM chunks, send RU9G, and close the socket.
End the session and confirm that you can retrieve transcript or note content with REST.

After this path works end to end, continue with pause and resume, keep-alive handling, reconnect rules, and capture quality controls.

Send JSON text frames

Every message you send on /ws/stream must be a UTF-8 JSON text frame.

Each WebSocket frame must contain exactly one JSON object.
Each client send should contain one logical message.
Audio bytes go inside a JSON string field, not in a binary WebSocket frame.

Do not:

Send binary WebSocket frames.
Send multiple JSON objects in one frame.
Stream raw audio over HTTP. Use the WebSocket with JSON text frames instead.

If the server receives non-JSON payloads, it returns parsing errors, such as invalid character or null byte errors.

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.

For encoding steps and the message order, refer to WebSocket streaming wire format. For capture guidance before you open the socket, refer to Audio capture best practices.

Common streaming mistakes to avoid

Use this table to troubleshoot common ambient streaming mistakes before you ship. It explains what each mistake means, why it occurs, and how to resolve it. For the full Ambient troubleshooting table, refer to Complete the session after streaming.

Problem	Why it happens	How to fix it
Server returns JSON parse errors (for example, invalid character or null byte)	The WebSocket received a binary frame, a non-JSON payload, or multiple JSON objects in a single frame.	Send one UTF-8 JSON object per WebSocket text frame. Do not send binary frames or concatenate multiple JSON objects.
Audio is ignored or transcription is incorrect	Audio was not encoded as expected. Common causes include hexadecimal encoding, URL-safe Base64, or sending WAV headers instead of raw PCM audio.	Encode raw LINEAR16 PCM audio using standard Base64 before sending it in the `data` field.
The session never completes	The server never received the end-of-stream marker.	End the stream by sending a final `AUDIO` message with `"data": "RU9G"`.
Control messages are ignored	A control action was sent in the `data` field instead of as an event message.	Send control actions as `{"type":"EVENT","event":"<VALUE>"}`. Do not place control values in `data`.
No final note or transcript is available	Closing the WebSocket does not end the ambient session or trigger note generation.	After streaming completes, call the ambient REST API to end the session, then retrieve the generated note and transcript.
The WebSocket disconnects during a long pause	No messages were sent before the keep-alive timeout expired.	While audio is paused, send a `KEEP_ALIVE` event at least every 5 seconds.
Unable to reconnect after a disconnect	The session has already moved beyond the `CREATED` state.	Reconnect to `/ws/stream` using the same `ambient_session_id` only while the session status is `CREATED`.

Available cookbooks

AmbientAPI

End Ambient After Streaming

Send RU9G, then end session.

5 min

AmbientAPI

Authenticate Browser WebSocket Handshake

Auth browser WebSocket with protocols.

5 min

Available tutorials

Ambient

Build an Ambient Streaming Client

Authenticate, create a session, stream PCM audio over WebSocket, and retrieve clinical note results.

20 minIntermediate

Next steps

Open Ambient streaming wire format Follow Complete the session after streaming Copy the Ambient WebSocket client code example

Get Started

Concepts & Feature Guides

Tutorials

Resources

FAQs & Support

Stream Ambient Audio - Overview

Before you begin

When to use Ambient or Form filling streaming vs Dictation streaming

Decide before you build your streaming client

How Ambient or Form filling streaming works

Verify your first Ambient stream

Send JSON text frames

Audio streaming recommendations

Sample Rate of 16 kHz

Mono Channel

LINEAR16 Encoding

Audio Chunk Size of 100 ms

Stream at Real-Time Speed

Common streaming mistakes to avoid

Available cookbooks

End Ambient After Streaming

Authenticate Browser WebSocket Handshake

Available tutorials

Build an Ambient Streaming Client

Next steps

​Before you begin

​When to use Ambient or Form filling streaming vs Dictation streaming

​Decide before you build your streaming client

​How Ambient or Form filling streaming works

​Verify your first Ambient stream

​Send JSON text frames

​Audio streaming recommendations

Sample Rate of 16 kHz

Mono Channel

LINEAR16 Encoding

Audio Chunk Size of 100 ms

Stream at Real-Time Speed

​Common streaming mistakes to avoid

​Available cookbooks

​End Ambient After Streaming

​Authenticate Browser WebSocket Handshake

​Available tutorials

​Build an Ambient Streaming Client

​Next steps

Before you begin

When to use Ambient or Form filling streaming vs Dictation streaming

Decide before you build your streaming client

How Ambient or Form filling streaming works

Verify your first Ambient stream

Send JSON text frames

Audio streaming recommendations

Common streaming mistakes to avoid

Available cookbooks

End Ambient After Streaming

Authenticate Browser WebSocket Handshake

Available tutorials

Build an Ambient Streaming Client

Next steps