server

WebSocket server proxy that receives bus messages from a remote client.

class pipecat.workers.proxy.websocket.server.WebSocketProxyServer(name: str, *, websocket: WebSocket, worker_name: str, remote_worker_name: str, forward_messages: tuple[type[BusMessage], ...] = (), serializer: MessageSerializer | None = None)

Bases: BaseWorker

Receives bus messages from a remote client over WebSocket.

Accepts a FastAPI/Starlette WebSocket connection and forwards messages between the remote client and a local worker. Only messages from the local worker targeted at the remote worker are sent. Only inbound messages targeted at the local worker are accepted.

Event handlers available:

• on_client_connected: Fired when the WebSocket client connects and the proxy is ready.

• on_client_disconnected: Fired when the WebSocket client disconnects.

Example:

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    proxy = WebSocketProxyServer(
        "gateway",
        websocket=websocket,
        worker_name="worker",
        remote_worker_name="voice",
    )

    @proxy.event_handler("on_client_connected")
    async def on_client_connected(worker, websocket):
        logger.info("Client connected")

    @proxy.event_handler("on_client_disconnected")
    async def on_client_disconnected(worker, websocket):
        logger.info("Client disconnected")

    await runner.add_workers(proxy)

__init__(name: str, *, websocket: WebSocket, worker_name: str, remote_worker_name: str, forward_messages: tuple[type[BusMessage], ...] = (), serializer: MessageSerializer | None = None)

Initialize the WebSocketProxyServer.

Parameters:

• name – Unique name for this worker.

• websocket – An accepted FastAPI/Starlette WebSocket connection.

• worker_name – Name of the local worker to route messages to/from. Only messages from this worker are forwarded to the client.

• remote_worker_name – Name of the worker on the remote client. Only outbound messages targeted at this worker are sent. Only inbound messages targeted at the local worker are accepted.

• forward_messages – Additional message types to forward from the local worker (e.g. (BusFrameMessage,) for frame routing). These are forwarded based on source worker name only, regardless of target.

• serializer – Serializer for bus messages. Defaults to JSONMessageSerializer.

async start() → None

Start the WebSocket receive loop and watch the local worker.

async stop() → None

Cancel the receive loop and close the WebSocket connection.

async on_worker_ready(data: WorkerReadyData) → None

Notify the remote client that the local worker is ready.

async on_bus_message(message: BusMessage) → None

Forward messages from the local worker to the remote client.

Parameters:

message – The bus message to process.