Realtime Client

RealtimeAPI

Entrypoint for realtime helpers on SonioxClient.

Parameter	Type	Description
`client`	`SonioxClient`	Soniox client instance.

Properties

Property	Type	Description
`stt`	`RealtimeSTTClient`	Speech-to-text API namespace.

AsyncRealtimeAPI

Entrypoint for async realtime helpers on AsyncSonioxClient.

Parameter	Type	Description
`client`	`AsyncSonioxClient`	Soniox client instance.

Properties

Property	Type	Description
`stt`	`AsyncRealtimeSTTClient`	Speech-to-text API namespace.

RealtimeSTTClient

Factory for creating synchronous realtime speech-to-text sessions.

This class validates credentials and prepares session configuration, but does not itself manage WebSocket connections.

Parameter	Type	Description
`client`	`SonioxClient`	Parent Soniox client providing configuration and credentials.

connect()

connect(*, config: RealtimeSTTConfig, api_key: str | None = None) -> RealtimeSTTSession

Create a new realtime STT session.

The returned session is not connected until entered as a context manager.

Parameters

Parameter	Type	Description
`config`	`RealtimeSTTConfig`	Realtime transcription configuration.
`api_key`	`str \| None`	Optional API key override. If not provided, the client's default API key is used.

Returns

RealtimeSTTSession

A new RealtimeSTTSession instance.

Raises

SonioxValidationError If no API key is available.

RealtimeSTTSession

Synchronous WebSocket session for a single real-time speech-to-text stream.

This class manages the full lifecycle of a real-time transcription session: connecting to the WebSocket endpoint, streaming audio data, receiving events, and gracefully closing the stream. A session is stateful and represents exactly one streaming interaction with the Soniox realtime API.

Instances are designed to be used as context managers.

Constructor

RealtimeSTTSession(url: str, config: RealtimeSTTConfig)

Create a new realtime STT session.

This does not open a network connection. The WebSocket connection is established when entering the context manager.

Parameters

Parameter	Type	Description
`url`	`str`	WebSocket URL for the realtime transcription endpoint.
`config`	`RealtimeSTTConfig`	Configuration describing the audio format and transcription behavior for this session.

Returns

None

Properties

Property	Type	Description
`config`	`RealtimeSTTConfig`	Return the configuration used to initialize this session.
`paused`	`bool`	Return True if the session is currently paused.
`last_message`	`RealtimeEvent \| None`	Return the most recently received realtime event, if any.

close()

close() -> None

Gracefully close the realtime session.

Sends a final empty message to signal end-of-stream, then closes the WebSocket connection. Calling this method multiple times is safe.

Returns

None

send_byte_chunk()

send_byte_chunk(chunk: bytes) -> None

Send a single chunk of raw audio bytes to the realtime stream.

The audio data must match the format declared in the session configuration (sample rate, channels, encoding).

Parameters

Parameter	Type	Description
`chunk`	`bytes`	Raw audio bytes to send.

Returns

None

Raises

SonioxRealtimeError If the session is not connected or the send operation fails.

send_bytes()

send_bytes(chunks: bytes | Iterator[bytes], *, finish: bool = True) -> None

Send audio data to the realtime stream.

This method accepts either a single bytes object or an iterator yielding audio chunks. When an iterator is provided, a FINISH control message is sent automatically after all chunks have been transmitted.

Parameters

Parameter	Type	Description
`chunks`	`bytes \| Iterator[bytes]`	Audio data as raw bytes or an iterator of byte chunks.
`finish`	`bool`	Whether to send a finish signal after streaming completes.

Returns

None

send_control_message()

send_control_message(control_type: RealtimeControlType) -> None

Send a control message to the realtime session.

Control messages modify the state of the stream, such as signaling end-of-audio or requesting finalization.

Parameters

Parameter	Type	Description
`control_type`	`RealtimeControlType`	The type of control message to send.

Returns

None

Raises

SonioxRealtimeError If the session is not connected or the message cannot be sent.

finish()

finish() -> None

Signal that no more audio will be sent for this session.

Returns

None

keep_alive()

keep_alive() -> None

Send a keep-alive message to prevent the session from timing out.

Returns

None

finalize()

finalize() -> None

Finalize all outstanding non-final tokens while keeping the session open.

Subsequent tokens will be delivered with is_final=True.

Returns

None

recv_bytes()

recv_bytes() -> bytes

Receive a raw message from the WebSocket connection.

Returns

bytes

The received message as bytes. An empty bytes object indicates that the connection has been closed.

parse_event()

parse_event(raw: str | bytes) -> RealtimeEvent

Parse a raw WebSocket message into a structured realtime event.

Parameters

Parameter	Type	Description
`raw`	`str \| bytes`	Raw message payload received from the server.

Returns

RealtimeEvent

A validated RealtimeEvent instance.

receive_event()

receive_event() -> RealtimeEvent | None

Receive and parse the next realtime event from the server.

Returns

RealtimeEvent | None

The next RealtimeEvent, or None if the connection has closed.

Raises

SonioxRealtimeError If the session is not connected.

receive_events()

receive_events() -> Iterator[RealtimeEvent]

Yield realtime events as they are received from the server.

Iteration stops automatically when the connection is closed.

Returns

Iterator[RealtimeEvent]

handle_events()

handle_events(handler: Callable[[RealtimeEvent], None]) -> None

Receive realtime events and dispatch them to a handler callback.

Parameters

Parameter	Type	Description
`handler`	`Callable[[RealtimeEvent], None]`	Callable invoked for each received RealtimeEvent.

Returns

None

pause()

pause() -> None

Pause the session, suppressing outgoing audio and starting a background keepalive thread.

While paused, calls to :meth:send_byte_chunk are silently dropped. A background thread sends a keepalive message every KEEP_ALIVE_INTERVAL_SEC seconds to prevent the server from timing out the session.

Calling pause on an already-paused session is a no-op.

Returns

None

Raises

SonioxRealtimeError If the session is not connected.

resume()

resume() -> None

Resume a paused session, stopping the keepalive thread and allowing audio to be sent again.

Calling resume on a session that is not paused is a no-op.

Returns

None

Raises

SonioxRealtimeError If the session is not connected.

AsyncRealtimeSTTClient

Factory for creating asynchronous realtime speech-to-text sessions.

This class validates credentials and prepares session configuration, but does not itself manage WebSocket connections.

Constructor

AsyncRealtimeSTTClient(client: AsyncSonioxClient)

Create a realtime STT client bound to an existing API client.

Parameters

Parameter	Type	Description
`client`	`AsyncSonioxClient`	Parent Soniox client providing configuration and credentials.

Returns

None

connect()

connect(*, config: RealtimeSTTConfig, api_key: str | None = None) -> AsyncRealtimeSTTSession

Create a new realtime STT session.

The returned session is not connected until entered as an async context manager.

Parameters

Parameter	Type	Description
`config`	`RealtimeSTTConfig`	Realtime transcription configuration.
`api_key`	`str \| None`	Optional API key override. If not provided, the client's default API key is used.

Returns

AsyncRealtimeSTTSession

A new AsyncRealtimeSTTSession instance.

Raises

SonioxValidationError If no API key is available.

AsyncRealtimeSTTSession

Asynchronous WebSocket session for a single real-time speech-to-text stream.

Instances are designed to be used as async context managers.

Constructor

AsyncRealtimeSTTSession(url: str, config: RealtimeSTTConfig)

Create a new realtime STT session.

This does not open a network connection. The WebSocket connection is established when entering the async context manager.

Parameters

Parameter	Type	Description
`url`	`str`	WebSocket URL for the realtime transcription endpoint.
`config`	`RealtimeSTTConfig`	Configuration describing the audio format and transcription behavior for this session.

Returns

None

Properties

Property	Type	Description
`config`	`RealtimeSTTConfig`	Return the configuration used to initialize this session.
`paused`	`bool`	Return True if the session is currently paused.
`last_message`	`RealtimeEvent \| None`	Return the most recently received realtime event, if any.

close()

close() -> None

Gracefully close the realtime session.

Sends a final empty message to signal end-of-stream, then closes the WebSocket connection. Calling this method multiple times is safe.

Returns

None

send_byte_chunk()

send_byte_chunk(chunk: bytes) -> None

Send a single chunk of raw audio bytes to the realtime stream.

The audio data must match the format declared in the session configuration (sample rate, channels, encoding).

Parameters

Parameter	Type	Description
`chunk`	`bytes`	Raw audio bytes to send.

Returns

None

Raises

SonioxRealtimeError If the session is not connected or the send operation fails.

send_bytes()

send_bytes(chunks: bytes | AsyncIterator[bytes], *, finish: bool = True) -> None

Send audio data to the realtime stream.

Parameters

Parameter	Type	Description
`chunks`	`bytes \| AsyncIterator[bytes]`	Audio data as raw bytes or an iterator of byte chunks.
`finish`	`bool`	Whether to send a finish signal after streaming completes.

Returns

None

send_control_message()

send_control_message(control_type: RealtimeControlType) -> None

Send a control message to the realtime session.

Control messages modify the state of the stream, such as signaling end-of-audio or requesting finalization.

Parameters

Parameter	Type	Description
`control_type`	`RealtimeControlType`	The type of control message to send.

Returns

None

Raises

SonioxRealtimeError If the session is not connected or the message cannot be sent.

finish()

finish() -> None

Signal that no more audio will be sent for this session.

Returns

None

keep_alive()

keep_alive() -> None

Send a keep-alive message to prevent the session from timing out.

Returns

None

finalize()

finalize() -> None

Finalize all outstanding non-final tokens while keeping the session open.

Subsequent tokens will be delivered with is_final=True.

Returns

None

recv_bytes()

recv_bytes() -> bytes

Receive a raw message from the WebSocket connection.

Returns

bytes

The received message as bytes. An empty bytes object indicates that the connection has been closed.

parse_event()

parse_event(raw: str | bytes) -> RealtimeEvent

Parse a raw WebSocket message into a structured realtime event.

Parameters

Parameter	Type	Description
`raw`	`str \| bytes`	Raw message payload received from the server.

Returns

RealtimeEvent

A validated RealtimeEvent instance.

receive_event()

receive_event() -> RealtimeEvent | None

Receive and parse the next realtime event from the server.

Returns

RealtimeEvent | None

The next RealtimeEvent, or None if the connection has closed.

Raises

SonioxRealtimeError If the session is not connected.

receive_events()

receive_events() -> AsyncIterator[RealtimeEvent]

Yield realtime events as they are received from the server.

Iteration stops automatically when the connection is closed.

Returns

AsyncIterator[RealtimeEvent]

handle_events()

handle_events(handler: Callable[[RealtimeEvent], Awaitable[None]]) -> None

Receive realtime events and dispatch them to a handler callback.

Parameters

Parameter	Type	Description
`handler`	`Callable[[RealtimeEvent], Awaitable[None]]`	Callable invoked for each received RealtimeEvent.

Returns

None

pause()

pause() -> None

Pause the session, suppressing outgoing audio and starting a background keepalive task.

While paused, calls to :meth:send_byte_chunk are silently dropped. A background task sends a keepalive message every KEEP_ALIVE_INTERVAL_SEC seconds to prevent the server from timing out the session.

Calling pause on an already-paused session is a no-op.

Returns

None

Raises

SonioxRealtimeError If the session is not connected.

resume()

resume() -> None

Resume a paused session, stopping the keepalive task and allowing audio to be sent again.

Calling resume on a session that is not paused is a no-op.

Returns

None

Raises

SonioxRealtimeError If the session is not connected.

On this page