server

WebSocket server transport implementation for Pipecat.

This module provides WebSocket server transport functionality for real-time audio and data streaming, including client connection management, session handling, and frame serialization.

class pipecat.transports.websocket.server.WebsocketServerParams(*, 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 = False, serializer: FrameSerializer | None = None, session_timeout: int | None = None)

Bases: TransportParams

Configuration parameters for WebSocket server transport.

Parameters:

• add_wav_header – Whether to add WAV headers to audio frames.

• serializer – Frame serializer for message encoding/decoding.

• session_timeout – Timeout in seconds for client sessions.

add_wav_header: bool

serializer: FrameSerializer | None

session_timeout: int | None

class pipecat.transports.websocket.server.WebsocketServerCallbacks(*, on_client_connected: Callable[[WebSocketServerProtocol], Awaitable[None]], on_client_disconnected: Callable[[WebSocketServerProtocol], Awaitable[None]], on_session_timeout: Callable[[WebSocketServerProtocol], Awaitable[None]], on_websocket_ready: Callable[[], Awaitable[None]])

Bases: BaseModel

Callback functions for WebSocket server events.

Parameters:

• on_client_connected – Called when a client connects to the server.

• on_client_disconnected – Called when a client disconnects from the server.

• on_session_timeout – Called when a client session times out.

• on_websocket_ready – Called when the WebSocket server is ready to accept connections.

on_client_connected: Callable[[WebSocketServerProtocol], Awaitable[None]]

on_client_disconnected: Callable[[WebSocketServerProtocol], Awaitable[None]]

on_session_timeout: Callable[[WebSocketServerProtocol], Awaitable[None]]

on_websocket_ready: Callable[[], Awaitable[None]]

class pipecat.transports.websocket.server.WebsocketServerInputTransport(transport: BaseTransport, host: str, port: int, params: WebsocketServerParams, callbacks: WebsocketServerCallbacks, **kwargs)

Bases: BaseInputTransport

WebSocket server input transport for receiving client data.

Handles incoming WebSocket connections, message processing, and client session management including timeout monitoring and connection lifecycle.

__init__(transport: BaseTransport, host: str, port: int, params: WebsocketServerParams, callbacks: WebsocketServerCallbacks, **kwargs)

Initialize the WebSocket server input transport.

Parameters:

• transport – The parent transport instance.

• host – Host address to bind the WebSocket server to.

• port – Port number to bind the WebSocket server to.

• params – WebSocket server configuration parameters.

• callbacks – Callback functions for WebSocket events.

• **kwargs – Additional arguments passed to parent class.

async start(frame: StartFrame)

Start the WebSocket server and initialize components.

Parameters:

frame – The start frame containing initialization parameters.

async stop(frame: EndFrame)

Stop the WebSocket server and cleanup resources.

Parameters:

frame – The end frame signaling transport shutdown.

async cancel(frame: CancelFrame)

Cancel the WebSocket server and stop all processing.

Parameters:

frame – The cancel frame signaling immediate cancellation.

async cleanup()

Cleanup resources and parent transport.

class pipecat.transports.websocket.server.WebsocketServerOutputTransport(transport: BaseTransport, params: WebsocketServerParams, **kwargs)

Bases: BaseOutputTransport

WebSocket server output transport for sending data to clients.

Handles outgoing frame serialization, audio streaming with timing control, and client connection management for WebSocket communication.

__init__(transport: BaseTransport, params: WebsocketServerParams, **kwargs)

Initialize the WebSocket server output transport.

Parameters:

• transport – The parent transport instance.

• params – WebSocket server configuration parameters.

• **kwargs – Additional arguments passed to parent class.

async set_client_connection(websocket: WebSocketServerProtocol | None)

Set the active client WebSocket connection.

Parameters:

websocket – The WebSocket connection to set as active, or None to clear.

async start(frame: StartFrame)

Start the output transport and initialize components.

Parameters:

frame – The start frame containing initialization parameters.

async stop(frame: EndFrame)

Stop the output transport and send final frame.

Parameters:

frame – The end frame signaling transport shutdown.

async cancel(frame: CancelFrame)

Cancel the output transport and send cancellation frame.

Parameters:

frame – The cancel frame signaling immediate cancellation.

async cleanup()

Cleanup resources and parent transport.

async process_frame(frame: Frame, direction: FrameDirection)

Process frames and handle interruption timing.

Parameters:

• frame – The frame to process.

• direction – The direction of frame flow in the pipeline.

async send_message(frame: OutputTransportMessageFrame | OutputTransportMessageUrgentFrame)

Send a transport message frame to the client.

Parameters:

frame – The transport message frame to send.

async write_audio_frame(frame: OutputAudioRawFrame) → bool

Write an audio frame to the WebSocket client with timing control.

Parameters:

frame – The output audio frame to write.

Returns:

True if the audio frame was written successfully, False otherwise.

class pipecat.transports.websocket.server.WebsocketServerTransport(params: WebsocketServerParams, host: str = 'localhost', port: int = 8765, input_name: str | None = None, output_name: str | None = None)

Bases: BaseTransport

WebSocket server transport for bidirectional real-time communication.

Provides a complete WebSocket server implementation with separate input and output transports, client connection management, and event handling for real-time audio and data streaming applications.

Event handlers available:

• on_client_connected(transport, websocket): Client WebSocket connected

• on_client_disconnected(transport, websocket): Client WebSocket disconnected

• on_session_timeout(transport, websocket): Session timed out

• on_websocket_ready(transport): WebSocket server is ready to accept connections

Example:

@transport.event_handler("on_client_connected")
async def on_client_connected(transport, websocket):
    ...

__init__(params: WebsocketServerParams, host: str = 'localhost', port: int = 8765, input_name: str | None = None, output_name: str | None = None)

Initialize the WebSocket server transport.

Parameters:

• params – WebSocket server configuration parameters.

• host – Host address to bind the server to. Defaults to “localhost”.

• port – Port number to bind the server to. Defaults to 8765.

• input_name – Optional name for the input processor.

• output_name – Optional name for the output processor.

input() → WebsocketServerInputTransport

Get the input transport for receiving client data.

Returns:

The WebSocket server input transport instance.

output() → WebsocketServerOutputTransport

Get the output transport for sending data to clients.

Returns:

The WebSocket server output transport instance.