client

WebSocket client transport implementation for Pipecat.

This module provides a WebSocket client transport that enables bidirectional communication over WebSocket connections, with support for audio streaming, frame serialization, and connection management.

class pipecat.transports.websocket.client.WebsocketClientParams(*, audio_out_enabled: bool = False, audio_out_sample_rate: int | None = None, audio_out_channels: int = 1, audio_out_bitrate: int = 96000, audio_out_10ms_chunks: int = 4, audio_out_mixer: Mapping[str | None, ~pipecat.audio.mixers.base_audio_mixer.BaseAudioMixer] | None=None, audio_out_destinations: list[str] = <factory>, audio_out_end_silence_secs: int = 2, audio_out_auto_silence: bool = True, audio_in_enabled: bool = False, audio_in_sample_rate: int | None = None, audio_in_channels: int = 1, audio_in_filter: BaseAudioFilter | None = None, audio_in_stream_on_start: bool = True, audio_in_passthrough: bool = True, video_in_enabled: bool = False, video_out_enabled: bool = False, video_out_is_live: bool = False, video_out_width: int = 1024, video_out_height: int = 768, video_out_bitrate: int | None = None, video_out_framerate: int = 30, video_out_color_format: str = 'RGB', video_out_codec: str | None = None, video_out_destinations: list[str] = <factory>, add_wav_header: bool = True, additional_headers: dict[str, str] | None=None, serializer: FrameSerializer | None = None)[source]

Bases: TransportParams

Configuration parameters for WebSocket client transport.

Parameters:

add_wav_header – Whether to add WAV headers to audio frames.
serializer – Frame serializer for encoding/decoding messages.

add_wav_header: bool

additional_headers: dict[str, str] | None

serializer: FrameSerializer | None

class pipecat.transports.websocket.client.WebsocketClientCallbacks(*, on_connected: Callable[[WebSocketClientProtocol], Awaitable[None]], on_disconnected: Callable[[WebSocketClientProtocol], Awaitable[None]], on_message: Callable[[WebSocketClientProtocol, str | bytes], Awaitable[None]])[source]

Bases: BaseModel

Callback functions for WebSocket client events.

Parameters:

on_connected – Called when WebSocket connection is established.
on_disconnected – Called when WebSocket connection is closed.
on_message – Called when a message is received from the WebSocket.

on_connected: Callable[[WebSocketClientProtocol], Awaitable[None]]

on_disconnected: Callable[[WebSocketClientProtocol], Awaitable[None]]

on_message: Callable[[WebSocketClientProtocol, str | bytes], Awaitable[None]]

class pipecat.transports.websocket.client.WebsocketClientSession(uri: str, params: WebsocketClientParams, callbacks: WebsocketClientCallbacks, transport_name: str)[source]

Bases: object

Manages a WebSocket client connection session.

Handles connection lifecycle, message sending/receiving, and provides callback mechanisms for connection events.

__init__(uri: str, params: WebsocketClientParams, callbacks: WebsocketClientCallbacks, transport_name: str)[source]

Initialize the WebSocket client session.

Parameters:

uri – The WebSocket URI to connect to.
params – Configuration parameters for the session.
callbacks – Callback functions for session events.
transport_name – Name of the parent transport for logging.

property task_manager: BaseTaskManager

Get the task manager for this session.

Returns:: The task manager instance.
Raises:: Exception – If task manager is not initialized.

async setup(task_manager: BaseTaskManager)[source]

Set up the session with a task manager.

Parameters:: task_manager – The task manager to use for session tasks.

async connect()[source]: Connect to the WebSocket server.

async disconnect()[source]: Disconnect from the WebSocket server.

async send(message: str | bytes) → bool[source]

Send a message through the WebSocket connection.

Parameters:: message – The message data to send.

property is_connected: bool

Check if the WebSocket is currently connected.

Returns:: True if the WebSocket is in connected state.

property is_closing: bool

Check if the WebSocket is currently closing.

Returns:: True if the WebSocket is in the process of closing.

class pipecat.transports.websocket.client.WebsocketClientInputTransport(transport: BaseTransport, session: WebsocketClientSession, params: WebsocketClientParams)[source]

Bases: BaseInputTransport

WebSocket client input transport for receiving frames.

Handles incoming WebSocket messages, deserializes them to frames, and pushes them downstream in the processing pipeline.

__init__(transport: BaseTransport, session: WebsocketClientSession, params: WebsocketClientParams)[source]

Initialize the WebSocket client input transport.

Parameters:

transport – The parent transport instance.
session – The WebSocket session to use for communication.
params – Configuration parameters for the transport.

async setup(setup: FrameProcessorSetup)[source]

Set up the input transport with the frame processor setup.

Parameters:: setup – The frame processor setup configuration.

async start(frame: StartFrame)[source]

Start the input transport and initialize the WebSocket connection.

Parameters:: frame – The start frame containing initialization parameters.

async stop(frame: EndFrame)[source]

Stop the input transport and disconnect from WebSocket.

Parameters:: frame – The end frame signaling transport shutdown.

async cancel(frame: CancelFrame)[source]

Cancel the input transport and disconnect from WebSocket.

Parameters:: frame – The cancel frame signaling immediate cancellation.

async cleanup()[source]: Clean up the input transport resources.

async on_message(websocket, message)[source]

Handle incoming WebSocket messages.

Parameters:

websocket – The WebSocket connection that received the message.
message – The received message data.

class pipecat.transports.websocket.client.WebsocketClientOutputTransport(transport: BaseTransport, session: WebsocketClientSession, params: WebsocketClientParams)[source]

Bases: BaseOutputTransport

WebSocket client output transport for sending frames.

Handles outgoing frames, serializes them for WebSocket transmission, and manages audio streaming with proper timing simulation.

__init__(transport: BaseTransport, session: WebsocketClientSession, params: WebsocketClientParams)[source]

Initialize the WebSocket client output transport.

Parameters:

transport – The parent transport instance.
session – The WebSocket session to use for communication.
params – Configuration parameters for the transport.

async setup(setup: FrameProcessorSetup)[source]

Set up the output transport with the frame processor setup.

Parameters:: setup – The frame processor setup configuration.

async start(frame: StartFrame)[source]

Start the output transport and initialize the WebSocket connection.

Parameters:: frame – The start frame containing initialization parameters.

async stop(frame: EndFrame)[source]

Stop the output transport and disconnect from WebSocket.

Parameters:: frame – The end frame signaling transport shutdown.

async cancel(frame: CancelFrame)[source]

Cancel the output transport and disconnect from WebSocket.

Parameters:: frame – The cancel frame signaling immediate cancellation.

async cleanup()[source]: Clean up the output transport resources.

async send_message(frame: OutputTransportMessageFrame | OutputTransportMessageUrgentFrame)[source]

Send a transport message through the WebSocket.

Parameters:: frame – The transport message frame to send.

async write_audio_frame(frame: OutputAudioRawFrame) → bool[source]

Write an audio frame to the WebSocket with optional WAV header.

Parameters:: frame – The output audio frame to write.
Returns:: True if the audio frame was written successfully, False otherwise.

class pipecat.transports.websocket.client.WebsocketClientTransport(uri: str, params: WebsocketClientParams | None = None)[source]

Bases: BaseTransport

WebSocket client transport for bidirectional communication.

Provides a complete WebSocket client transport implementation with input and output capabilities, connection management, and event handling.

Event handlers available:

on_connected(transport): Connected to WebSocket server
on_disconnected(transport): Disconnected from WebSocket server

Example:

@transport.event_handler("on_connected")
async def on_connected(transport):
    ...

__init__(uri: str, params: WebsocketClientParams | None = None)[source]

Initialize the WebSocket client transport.

Parameters:

uri – The WebSocket URI to connect to.
params – Optional configuration parameters for the transport.

input() → WebsocketClientInputTransport[source]

Get the input transport for receiving frames.

Returns:: The WebSocket client input transport instance.

output() → WebsocketClientOutputTransport[source]

Get the output transport for sending frames.

Returns:: The WebSocket client output transport instance.