​
Overview

WebsocketServerTransport provides a WebSocket server implementation for real-time audio communication. It supports bidirectional audio streams and voice activity detection (VAD).
WebsocketServerTransport is best suited for server-side applications and prototyping client/server apps.For client/server production applications, we strongly recommend using a WebRTC-based transport for robust network and media handling.

​
Installation

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

​
Configuration

​
Constructor Parameters

​
host
str
default:"localhost"
Host address to bind the WebSocket server
​
port
int
default:"8765"
Port number for the WebSocket server
​
params
WebsocketServerParams
default:"WebsocketServerParams()"
Transport configuration parameters

​
WebsocketServerParams Configuration

​
add_wav_header
bool
default:"False"
Add WAV header to audio frames
​
serializer
FrameSerializer
default:"ProtobufFrameSerializer()"
Frame serializer for WebSocket messages
​
session_timeout
int | None
default:"None"
Session timeout in seconds. If set, triggers timeout event when no activity is detected

​
Audio Configuration

​
audio_in_enabled
bool
default:false
Enable audio input from the WebRTC client
​
audio_in_passthrough
bool
default:"False"
When enabled, incoming audio frames are pushed downstream
​
audio_out_enabled
bool
default:"False"
Enable audio output capabilities
​
audio_out_sample_rate
int
default:"None"
Audio output sample rate in Hz
​
audio_out_channels
int
default:"1"
Number of audio output channels

​
Voice Activity Detection (VAD)

​
vad_analyzer
VADAnalyzer | None
default:"None"
Voice Activity Detection analyzer. You can set this to either SileroVADAnalyzer() or WebRTCVADAnalyzer(). SileroVADAnalyzer is the recommended option. Learn more about the SileroVADAnalyzer.

​
Basic Usage

from pipecat.transports.network.websocket_server import (
    WebsocketServerTransport,
    WebsocketServerParams
)
from pipecat.audio.vad.silero import SileroVADAnalyzer
from pipecat.pipeline.pipeline import Pipeline

# Configure transport
transport = WebsocketServerTransport(
    host="localhost",
    port=8765,
    params=WebsocketServerParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        add_wav_header=True,
        vad_analyzer=SileroVADAnalyzer(),
        session_timeout=180  # 3 minutes
    )
)

# Use in pipeline
pipeline = Pipeline([
    transport.input(),    # Handle incoming audio
    stt,          # Speech-to-text
    llm,          # Language model
    tts,          # Text-to-speech
    transport.output()    # Handle outgoing audio
])
Check out the Websocket Server example to see how to use this transport in a pipeline.

​
Event Callbacks

WebsocketServerTransport provides callbacks for handling client connection events. Register callbacks using the @transport.event_handler() decorator.

​
Connection Events

​
on_client_connected
async callback
Called when a client connects to the WebSocket server.Parameters:
  • transport: The WebsocketServerTransport instance
  • client: WebSocket client connection object
@transport.event_handler("on_client_connected")
async def on_client_connected(transport, client):
    logger.info(f"Client connected: {client.remote_address}")
    # Initialize conversation
    await task.queue_frames([LLMMessagesFrame(initial_messages)])
​
on_client_disconnected
async callback
Called when a client disconnects from the WebSocket server.Parameters:
  • transport: The WebsocketServerTransport instance
  • client: WebSocket client connection object
@transport.event_handler("on_client_disconnected")
async def on_client_disconnected(transport, client):
    logger.info(f"Client disconnected: {client.remote_address}")
​
on_session_timeout
async callback
Called when a session times out (if session_timeout is configured).Parameters:
  • transport: The WebsocketServerTransport instance
  • client: WebSocket client connection object
@transport.event_handler("on_session_timeout")
async def on_session_timeout(transport, client):
    logger.info(f"Session timeout for client: {client.remote_address}")
    # Handle timeout (e.g., send message, close connection)

​
Frame Types

​
Input Frames

​
InputAudioRawFrame
Frame
Raw audio data from the WebSocket client

​
Output Frames

​
OutputAudioRawFrame
Frame
Audio data to be sent to the WebSocket client

​
Notes

  • Supports real-time audio communication
  • Best suited for server-side applications
  • Handles WebSocket connection management
  • Provides voice activity detection
  • Supports session timeouts
  • Single client per server (new connections replace existing ones)
  • All callbacks are asynchronous