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.SingleClientWebsocketServerParams(*, 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, allowed_origins: list[str] = <factory>)

Bases: TransportParams

Configuration parameters for SingleClientWebsocketServerTransport.

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.

• allowed_origins – List of allowed origins. Empty list allows all origins. When set, connections with a missing or disallowed Origin header are rejected. Defaults to PIPECAT_ALLOWED_ORIGINS env var (comma-separated).

add_wav_header: bool

serializer: FrameSerializer | None

session_timeout: int | None

allowed_origins: list[str]

class pipecat.transports.websocket.server.SingleClientWebsocketServerCallbacks(*, 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.SingleClientWebsocketServerInputTransport(transport: BaseTransport, host: str, port: int, params: SingleClientWebsocketServerParams, callbacks: SingleClientWebsocketServerCallbacks, **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: SingleClientWebsocketServerParams, callbacks: SingleClientWebsocketServerCallbacks, **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.

acquire_server()

Register a hold on the shared WebSocket server.

Called by the output transport when it starts, so the server stays up until both the input and output sides have released it.

async stop(frame: EndFrame)

Stop the input side and release its hold on the server.

Parameters:

frame – The end frame signaling transport shutdown.

async release_server()

Release one hold on the shared server, draining it once none remain.

Called by the input transport when its EndFrame arrives and by the output transport once it has flushed all pending output. The last release drives the graceful drain.

async cancel(frame: CancelFrame)

Cancel the WebSocket server and stop all processing.

Parameters:

frame – The cancel frame signaling immediate cancellation.

async cleanup()

Release input transport resources at teardown.

class pipecat.transports.websocket.server.SingleClientWebsocketServerOutputTransport(transport: BaseTransport, params: SingleClientWebsocketServerParams, **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: SingleClientWebsocketServerParams, **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, flushing final output before releasing the server.

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.SingleClientWebsocketServerTransport(params: SingleClientWebsocketServerParams, host: str = 'localhost', port: int = 8765, input_name: str | None = None, output_name: str | None = None)

Bases: BaseTransport

WebSocket server transport that serves a single client at a time.

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.

Only one client can be connected at a time. While a client is connected, new connection attempts are rejected and the existing client is kept; once that client disconnects, the server accepts a new one. This makes it well suited for local development and single-session bots, but not for serving multiple concurrent clients.

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: SingleClientWebsocketServerParams, 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() → SingleClientWebsocketServerInputTransport

Get the input transport for receiving client data.

Returns:

The WebSocket server input transport instance.

output() → SingleClientWebsocketServerOutputTransport

Get the output transport for sending data to clients.

Returns:

The WebSocket server output transport instance.

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, allowed_origins: list[str] = <factory>)

Bases: SingleClientWebsocketServerParams

Deprecated alias for SingleClientWebsocketServerParams.

Deprecated since version 1.4.0: Use SingleClientWebsocketServerParams instead. Will be removed in 2.0.0.

add_wav_header: bool

serializer: FrameSerializer | None

session_timeout: int | None

allowed_origins: list[str]

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: SingleClientWebsocketServerCallbacks

Deprecated alias for SingleClientWebsocketServerCallbacks.

Deprecated since version 1.4.0: Use SingleClientWebsocketServerCallbacks instead. Will be removed in 2.0.0.

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(**kwargs)

Bases: SingleClientWebsocketServerInputTransport

Deprecated alias for SingleClientWebsocketServerInputTransport.

Deprecated since version 1.4.0: Use SingleClientWebsocketServerInputTransport instead. Will be removed in 2.0.0.

class pipecat.transports.websocket.server.WebsocketServerOutputTransport(**kwargs)

Bases: SingleClientWebsocketServerOutputTransport

Deprecated alias for SingleClientWebsocketServerOutputTransport.

Deprecated since version 1.4.0: Use SingleClientWebsocketServerOutputTransport instead. Will be removed in 2.0.0.

class pipecat.transports.websocket.server.WebsocketServerTransport(**kwargs)

Bases: SingleClientWebsocketServerTransport

Deprecated alias for SingleClientWebsocketServerTransport.

Deprecated since version 1.4.0: Use SingleClientWebsocketServerTransport instead. The renamed class makes it explicit that the server handles a single client at a time. Will be removed in 2.0.0.