Skip to main content

​
Overview

WebSocket transports provide both client and server WebSocket implementations for real-time bidirectional communication. These transports support audio streaming, frame serialization, and connection management, making them ideal for prototyping and lightweight client-server applications where WebRTC might be overkill.
WebSocket transports are best suited for prototyping and controlled network environments.For production client-server applications, we recommend WebRTC-based transports for more robust network handling, NAT traversal, and media optimization.

WebSocket Client API Reference

Client transport methods and configuration

WebSocket Server API Reference

Server transport methods and configuration

Example Implementation

Complete client and server WebSocket examples

WebSocket Protocol

WebSocket protocol documentation and guides

​
Installation

To use WebSocket transports, install the required dependencies: 
pip install "pipecat-ai[websocket]"

​
Prerequisites

​
WebSocket Application Setup

Before using WebSocket transports, you need:
  1. Server Implementation: Set up WebSocket server using your preferred framework
  2. Client Implementation: Configure WebSocket client for browser or application use
  3. Audio Configuration: Set up audio streaming parameters and formats
  4. Connection Management: Handle WebSocket lifecycle and error recovery

​
Configuration Options

  • Transport Type: Choose between client or server WebSocket transport
  • Audio Parameters: Configure sample rates, channels, and audio formats
  • Frame Serialization: Set up custom frame serializers if needed
  • Connection Handling: Configure reconnection and error handling strategies

​
Key Features

  • Bidirectional Communication: Real-time audio and data streaming
  • Simple Protocol: Lightweight WebSocket-based communication
  • Flexible Serialization: Support for custom frame formats and audio codecs
  • Cross-Platform: Works with any WebSocket-compatible client or server

​
Configuration

​
WebsocketServerTransport

​
params
WebsocketServerParams
required
Transport configuration parameters.
​
host
str
default:"localhost"
Host address to bind the WebSocket server to.
​
port
int
default:"8765"
Port number to bind the WebSocket server to.
​
input_name
str
default:"None"
Optional name for the input transport processor.
​
output_name
str
default:"None"
Optional name for the output transport processor.

​
WebsocketServerParams

Inherits from TransportParams with additional WebSocket-specific parameters.
​
add_wav_header
bool
default:"False"
Whether to add WAV headers to outgoing audio frames.
​
serializer
FrameSerializer
default:"None"
Frame serializer for encoding/decoding WebSocket messages.
​
session_timeout
int
default:"None"
Timeout in seconds for client sessions. When set, triggers on_session_timeout if the session exceeds this duration. None disables the timeout.

​
WebsocketClientTransport

​
uri
str
required
The WebSocket URI to connect to.
​
params
WebsocketClientParams
default:"WebsocketClientParams()"
Client transport configuration parameters.
​
input_name
str
default:"None"
Optional name for the input transport processor.
​
output_name
str
default:"None"
Optional name for the output transport processor.

​
WebsocketClientParams

Inherits from TransportParams with additional WebSocket-specific parameters.
​
add_wav_header
bool
default:"True"
Whether to add WAV headers to outgoing audio frames.
​
additional_headers
dict[str, str]
default:"None"
Optional additional HTTP headers to include in the WebSocket handshake.
​
serializer
FrameSerializer
default:"None"
Frame serializer for encoding/decoding WebSocket messages.

​
Usage

WebSocket transports provide simple client-server communication for audio streaming and real-time interaction. They are ideal for prototyping and controlled network environments. See the complete examples for full implementations including:
  • WebSocket server setup and configuration
  • Client-side WebSocket integration
  • Audio streaming and frame handling
  • Connection management and error recovery

​
Event Handlers

WebSocket transports provide event handlers for client connection lifecycle and session management. Register handlers using the @event_handler decorator on the transport instance.

​
WebsocketServerTransport Events

​
Events Summary

EventDescription
on_client_connectedClient WebSocket connected
on_client_disconnectedClient WebSocket disconnected
on_session_timeoutSession timed out
on_websocket_readyWebSocket server is ready to accept connections

​
on_client_connected

Fired when a client connects to the WebSocket server. 
@transport.event_handler("on_client_connected")
async def on_client_connected(transport, websocket):
    print("Client connected")
Parameters:
ParameterTypeDescription
transportWebsocketServerTransportThe transport instance
websocketWebSocketServerProtocolThe WebSocket connection object

​
on_client_disconnected

Fired when a client disconnects from the WebSocket server. 
@transport.event_handler("on_client_disconnected")
async def on_client_disconnected(transport, websocket):
    print("Client disconnected")
Parameters:
ParameterTypeDescription
transportWebsocketServerTransportThe transport instance
websocketWebSocketServerProtocolThe WebSocket connection object

​
on_session_timeout

Fired when a client session exceeds the configured session_timeout duration. Only fires if session_timeout is set in the params. 
@transport.event_handler("on_session_timeout")
async def on_session_timeout(transport, websocket):
    print("Session timed out")
Parameters:
ParameterTypeDescription
transportWebsocketServerTransportThe transport instance
websocketWebSocketServerProtocolThe WebSocket connection object

​
on_websocket_ready

Fired when the WebSocket server has started and is ready to accept client connections. 
@transport.event_handler("on_websocket_ready")
async def on_websocket_ready(transport):
    print("WebSocket server ready")
Parameters:
ParameterTypeDescription
transportWebsocketServerTransportThe transport instance

​
WebsocketClientTransport Events

​
Events Summary

EventDescription
on_connectedConnected to WebSocket server
on_disconnectedDisconnected from WebSocket server
@transport.event_handler("on_connected")
async def on_connected(transport, websocket):
    print("Connected to server")

@transport.event_handler("on_disconnected")
async def on_disconnected(transport, websocket):
    print("Disconnected from server")
Parameters:
ParameterTypeDescription
transportWebsocketClientTransportThe transport instance
websocketWebSocketClientProtocolThe WebSocket connection object
The WebSocket server only supports one client connection at a time. If a new client connects while one is already connected, the existing connection will be closed.

​
Additional Resources