Audio Capture Best Practices

Audio capture best practices define how to prepare audio before streaming it to Suki over WebSocket. Capture mono LINEAR16 PCM audio at 16 kHz, split it into small chunks, Base64 encode each chunk, and send it as JSON text frames over the WebSocket. Ambient, Form filling, and Dictation all use the same audio capture requirements. However, each product uses different WebSocket endpoints, message formats, and end-of-stream markers. Read the following related guides:

Related Guides

Wire FormatStreaming ArchitectureCapture And Streaming FAQs

​

What this guide covers

Use this guide before implementing audio capture or opening a WebSocket connection. You will learn:

• The audio format required by Ambient, Form filling, and Dictation
• How to prepare and stream audio over the WebSocket
• Recommended network requirements for reliable real-time streaming
• Product-specific streaming differences you must handle

​

What audio format should you capture

Ambient, Form filling, and Dictation all use the same recommended audio format.

​

What should you avoid

Avoid the following common mistakes:

• Sending binary WebSocket frames instead of JSON text frames
• Sending multiple JSON objects in a single WebSocket message
• Encoding audio with hexadecimal, URL-safe Base64, or other non-standard Base64 variants
• Streaming audio over HTTP using Content-Type: application/json

Always encode the raw PCM bytes using standard Base64 defined by RFC 4648.

​

How do you prepare audio for streaming

Once audio has been captured:

1. Split the PCM stream into approximately 100 ms chunks.
2. Encode each chunk using standard Base64 (RFC 4648).
3. Wrap each chunk in a single JSON message.
4. Send one JSON text frame per audio chunk.
5. Stream chunks at approximately real-time speed so transmission stays synchronized with the captured audio.

For the required message fields, streaming sequence, and end-of-stream messages, see WebSocket streaming wire format.

​

What network requirements are recommended

All streaming uses secure WebSockets (wss://). For reliable real-time streaming, Suki recommends the following minimum network conditions: For the source of these recommendations, see Audio capture and streaming FAQs. For keep-alives, reconnection behavior, and pause handling, see Streaming architecture.

​

What differs by product

Although all products use the same audio format, each streaming API has different protocol requirements.

​

Ambient and Form filling

• Send a START_TIME message before streaming audio.
• Send Base64 PCM in the data field.
• End the stream by sending a final AUDIO message whose data value is RU9G (Base64 of ASCII EOF).
• While the stream is active, send audio at least once every 25 seconds, or Suki disconnects the stream.
• While the stream is paused, send an EVENT message with event: KEEP_ALIVE at least every 5 seconds. An ambient session can remain paused for up to 30 minutes.
• You can reconnect to /ws/stream using the same ambient_session_id only while the session remains in the CREATED state. Otherwise the handshake returns FailedPrecondition.
• Sessions shorter than 1 minute may not contain enough audio for note generation and can be marked as skipped.

​

Dictation

• Open /ws/transcribe only when the session state is READY or IDLE. If the session is not ready, the handshake returns FailedPrecondition.
• Send Base64 PCM in audioData, not data.
• End streaming by sending {"type":"EVENT","event":"AUDIO_END"} after the last AUDIO chunk.
• Use interim transcripts (is_final: false) for live display, and treat is_final: true as the finalized transcript. See Dictation transcript frames.

​

Next steps

Review WebSocket streaming wire format for the exact outbound message formats. Read Audio capture and streaming FAQs for additional guidance on audio formats and network requirements. Follow Complete the session after streaming to properly finalize streaming sessions.