Skip to main content
Quick summary
After you create the ambient session and add visit context, open /ws/stream when the clinician starts recording. Your application owns the microphone and clear Recording, Paused, and Generating states. When recording ends, send RU9G, close the WebSocket, and call End ambient session endpoint to start processing the ambient session’s generated content.

Use this guide to design the recorder experience and sequence these operations correctly. For WebSocket handshake, PCM encoding, frame structure, and control-event details, see Stream Ambient audio and Ambient streaming wire format. Ambient and Form filling share the same wire format on /ws/stream; this guide focuses on Ambient recorder UX.
Last updated:August 2026
Streaming connects the clinician’s live audio to an ambient session. In a custom Ambient experience, your application manages the recorder UI and microphone, while the Ambient streaming API receives the audio and control events. The typical flow for an ambient session is: Streaming is one part of the ambient session lifecycle. It does not replace session creation, adding visit context, session ending, or content retrieval. Your application should follow this sequence to stream ambient audio:
1

Create the Ambient Session

Create the ambient session before you open the WebSocket.
2

Add Visit Context

Add visit context for the session before streaming begins.
3

Open /ws/stream

Open the WebSocket when the clinician starts recording.
4

Capture and Stream Audio

Capture and stream the clinician’s audio over the socket.
5

Handle Pause and Resume

Send EVENT PAUSE, EVENT RESUME, and EVENT KEEP_ALIVE messages when the clinician pauses or resumes.
6

Send RU9G to Stop Recording

Stop the recording by sending RU9G after the final PCM audio chunk.
7

Close the WebSocket

Close the WebSocket after RU9G is sent.
8

Call the End Endpoint

Call the Ambient End endpoint to start note generation.
9

Poll Status and Retrieve Content

Poll the session status and retrieve the generated content when processing is complete.
Do not open the WebSocket before the session has been created and its context has been added.
Mental model: to remember the flow: For the complete streaming protocol, see the following guides:

​
Design the recorder experience

A custom ambient experience should make the recording state clear at every point. The clinician should always be able to tell whether audio is being captured. At minimum, provide:
  • Start to begin ambient recording indicating that the ambient session is active.
  • Pause to temporarily stop capturing audio and show in the UI that the ambient session is paused.
  • Resume to continue the same ambient session. If you are showing a timer, resume the timer when the ambient session is resumed.
  • Stop to finish recording and start processing. Show in the UI that the ambient session is generating content.
A typical state transition looks like this:

​
Show the recording state clearly

Use a persistent recording indicator while the ambient session is capturing audio. When the clinician pauses, make the paused state equally clear. After Stop, move the UI to a Generating state rather than leaving the clinician in a Recording state while ambient content is processed.

​
Keep microphone ownership clear

Do not stream Ambient and Dictation audio streams from the same device microphone at the same time. The two experiences use different streaming contracts and can contend for microphone access. Disable Dictation microphone while ambient session owns the microphone. Depending on your application flow, you may also keep it disabled while the ambient session is generating.
Refer to Ambient vs Dictation streaming guide to learn more about the differences between the two streaming flows.

​
Pause and resume

Pause and Resume should operate on the same ambient session. When the clinician pauses:
  • Send the EVENT PAUSE message.
  • Stop sending audio.
  • Continue sending EVENT KEEP_ALIVE messages at least every 5 seconds.
When the clinician resumes:
  • Send the EVENT RESUME message.
  • Resume audio capture.
  • Continue streaming audio on the same ambient session.
The maximum supported pause duration is 30 minutes when keep-alives are maintained.
Refer to Ambient streaming wire format guide to learn more about the event format and frame details.

​
Stop the recording cleanly

Stopping an ambient session recording requires more than closing the WebSocket. After the final PCM audio chunk has been sent:
  • Send RU9G on the WebSocket.
  • Close the WebSocket.
  • Call the Ambient End endpoint.
  • Poll the ambient session status.
  • Retrieve the ambient session’s generated content after processing completes.
Closing the WebSocket without sending RU9G and calling End is not enough to complete the ambient session and start note generation.
Refer to Complete an ambient visit and End Ambient after streaming guides to learn more about the End endpoint and how to complete the ambient session.

​
Audio capture requirements

For ambient session streaming, capture:
  • Channel: Mono
  • Encoding: LINEAR16 PCM
  • Sample rate: 16 kHz
  • Send audio and control information according to the ambient session WebSocket wire format.
  • For frame structure and handshake behavior, see Ambient streaming wire format. Keep those details in the streaming client implementation, not in the recorder UI layer.
  • Plan for about one minute or longer of captured audio. Short or empty sessions may finish with a skipped status after End.

​
Implementation flow

Use the following sequence in your application.
1

Authenticate and Create the Session

Obtain the required authentication credentials and create the ambient session. See Create ambient session.
2

Add Visit Context

Add visit context before opening the WebSocket. See Provide visit context.
3

Open the WebSocket

When the clinician starts recording, open /ws/stream using the authentication pattern required by your client. See Audio streaming API.
4

Stream Audio

Capture mono LINEAR16 PCM audio at 16 kHz and send it according to the Ambient streaming wire format.
5

Handle Pause and Resume

Send EVENT PAUSE and EVENT RESUME messages as the clinician pauses and resumes recording. While paused, send EVENT KEEP_ALIVE at least every 5 seconds.
6

Stop and End the Session

After the final audio, send RU9G, close the WebSocket, and call the End endpoint.
7

Wait for Processing

Poll the ambient session status and retrieve the generated content after processing completes. See Check note status.

​
What belongs in your application

Keep the responsibilities separated between your recorder UI and streaming client.

Recorder UI

Your application is responsible for:
  • Start, Pause, Resume, and Stop controls.
  • Showing whether Ambient is Recording, Paused, or Generating.
  • Managing microphone access.
  • Preventing conflicting microphone use with Dictation.
  • Moving the UI from Recording to Generating after Stop.

Streaming Client

Your streaming implementation is responsible for:
  • Opening /ws/stream at the correct point in the session lifecycle.
  • Capturing and encoding audio in the required format.
  • Sending audio frames.
  • Sending control events (EVENT messages for pause, resume, and keep-alive).
  • Maintaining keep-alives while paused.
  • Sending RU9G before closing the WebSocket.
For protocol details, see Ambient streaming wire format.

​
Common mistakes to avoid

Do not open /ws/stream before the ambient session has been created and visit context has been added. Open it as part of the Start Ambient flow.
Closing the WebSocket is not the complete Stop flow. Send RU9G, close the socket, and call the Ambient End endpoint.
Do not stop the keep-alive mechanism during a pause. Send EVENT KEEP_ALIVE at least every 5 seconds while paused.
Do not stream Ambient and Dictation from the same device microphone at the same time. Keep microphone ownership explicit in your application.
Always make Recording, Paused, and Generating states visible. The clinician should be able to tell whether Ambient is actively listening.
Plan for about one minute or longer of audio. Short or empty sessions may finish with a skipped status.

​
Implementation checklist

Before shipping a custom Ambient recorder, verify that your application:
  • Creates the ambient session before opening /ws/stream.
  • Adds visit context before streaming begins.
  • Clearly shows Recording, Paused, and Generating states.
  • Supports Pause and Resume on the same ambient session.
  • Sends EVENT KEEP_ALIVE at least every 5 seconds while paused.
  • Keeps Ambient and Dictation from using the same microphone at the same time.
  • Captures mono LINEAR16 PCM at 16 kHz.
  • Sends RU9G after the final audio.
  • Closes the WebSocket after sending RU9G.
  • Calls the Ambient End endpoint after closing the socket.
  • Polls session status after End.
  • Handles the skipped status for short or empty sessions.

Stream Ambient Audio

Learn how to connect to the Ambient WebSocket and stream audio.

Ambient Streaming Wire Format

Learn about WebSocket frames, PCM encoding, control events, and the streaming protocol.

Audio Capture Best Practices

Review audio capture guidance for streaming clients.

Ambient vs Dictation Streaming

Understand the differences between Ambient and Dictation streaming.

​
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
AmbientAPI

​
Poll Session Status Before Fetching Content

Poll status until completed, then retrieve.

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
Headless Web SDK

​
Build Headless Ambient Recorder

Use Headless Web SDK hooks to authenticate, create an ambient session, and control recording in React.

20 minIntermediate

​
What’s next

Audio streaming API WebSocket endpoint reference for Ambient audio streaming. Stream Ambient audio End-to-end streaming implementation guide. Complete an ambient visit End the ambient session after recording. Check note status Monitor processing after the session ends.
Last modified on August 20, 2026