WebSocketTransport enables a purely WebSocket based connection between clients and your Pipecat application. It implements bidirectional audio and video streaming using a WebSocket for real-time communication.

This transport is intended for lightweight implementations, particularly for local development and testing. It expects your Pipecat server to include the corresponding WebSocketTransport server-side implementation.

The WebSocketTransport is best suited for server-server 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. For more on WebRTC vs. Websocket communication, check out this article.

​
Usage

​
Basic Setup

import { PipecatClient } from "@pipecat-ai/client-js";
import {
  WebSocketTransport,
  ProtobufFrameSerializer,
} from "@pipecat-ai/websocket-transport";

const pcClient = new PipecatClient({
  transport: new WebSocketTransport ({
    serializer: new ProtobufFrameSerializer(),
    recorderSampleRate: 8000,
    playerSampleRate: 8000,
  }),
  enableCam: false, // Default camera off
  enableMic: true, // Default microphone on
  callbacks: {
    // Event handlers
  },
});

await pcClient.connect({
    endpoint: 'https://your-server/connect',
});

​
API Reference

​
Constructor Options

type WebSocketTransportOptions = {
  ws_url?: string;
  serializer?: WebSocketSerializer;
  recorderSampleRate?: number;
  playerSampleRate?: number;
};

​
Properties

​
TransportConnectionParams

The WebSocketTransport takes the same options as the constructor; WebSocketTransportOptions. Anything provided here will override the defaults set in the constructor. The ws_url is required to establish a connection.

pcClient.connect({
  ws_url: 'http://localhost:7860/ws'
});
// OR...
pcClient.connect({
  endpoint: 'https://your-server/connect', // returns { ws_url }
});

​
Methods

For most operations, you will not interact with the transport directly. Most methods have an equivalent in the PipecatClient and should be called from the PipecatClient. However, there is one transport-specific methods that you may need to call directly. When doing so, be sure to access your transport via the transport property of the PipecatClient instance.

​
handleUserAudioStream
method

If implementing your own serializer, you will need to pass the user audio stream to the transport via this method, which takes an ArrayBuffer of audio data.

transport.handleUserAudioStream(chunk.data);

​
Events

The transport implements the various PipecatClient event handlers.

​
Reconnection Handling

The WebSocketTransport does provide reconnection handling. If the WebSocket connection is lost, it will attempt to reconnect twice. If all reconnection attempts fail, the transport will gracefully disconnect.

​
More Information

WebSocket Demo

Basic Agent example using a WebSocket transport

Twilio Demo

Example using a WebSocket transport to simulate a Twilio connection to a bot

Source

WebSocketTransport

Package

@pipecat-ai/websocket-transport