Skip to main content

​
Overview

SmallWebRTCTransport enables peer-to-peer (“serverless”) WebRTC connections between clients and your Pipecat application. It implements bidirectional audio, video and data channels using WebRTC for real-time communication. This transport is open source and self-contained, with no dependencies on any other infrastructure.
For detailed notes on how to decide between using the SmallWebRTCTransport or other WebRTC transports like the DailyTransport, see this post.

SmallWebRTC Transport API Reference

Transport methods and configuration options

SmallWebRTC Connection API Reference

Connection management and signaling methods

Example Implementation

Complete peer-to-peer voice agent example

WebRTC Documentation

Official WebRTC protocol documentation

​
Installation

To use SmallWebRTCTransport, install the required dependencies: 
uv add "pipecat-ai[webrtc]"

​
Prerequisites

​
WebRTC Application Setup

Before using SmallWebRTCTransport, you need:
  1. Signaling Server: Implement WebRTC offer/answer exchange (required)
  2. Client Implementation: Set up WebRTC client for browser or application use
  3. ICE Configuration: Configure STUN/TURN servers for NAT traversal (optional for local networks) — see ICE Servers Configuration
  4. Development Runner: Use Pipecat’s development runner for quick setup (recommended)
No API keys are required since this is a peer-to-peer transport implementation. For production deployments across different networks, you may need to configure STUN/TURN servers for NAT traversal.

​
Configuration Options

  • Development Runner: Automatic server infrastructure and web interface (recommended)
  • Manual Implementation: Custom signaling server for advanced use cases
  • ICE Servers: STUN/TURN configuration for network traversal
  • Media Configuration: Audio/video parameters and format handling

​
Key Features

  • Serverless Architecture: Direct peer-to-peer connections with no intermediate servers
  • Production Ready: Heavily tested and used in Pipecat examples
  • Bidirectional Media: Full-duplex audio and video streaming
  • Data Channels: Application messaging and signaling support
  • Development Tools: Built-in development runner with web interface

​
Configuration

​
SmallWebRTCTransport

​
webrtc_connection
SmallWebRTCConnection
required
The underlying WebRTC connection handler that manages signaling and peer connections.
​
params
TransportParams
required
Transport configuration parameters for audio, video, and VAD settings.
​
input_name
str
default:"None"
Optional name for the input transport processor.
​
output_name
str
default:"None"
Optional name for the output transport processor.

​
Usage

SmallWebRTCTransport requires both a signaling server for WebRTC handshake and your Pipecat bot implementation. The easiest approach is using Pipecat’s development runner which handles all server infrastructure automatically. See the complete examples for full implementations including:
  • Development runner setup with automatic web interface
  • Manual signaling server implementation
  • WebRTC client integration
  • ICE server configuration for production deployment

​
Event Handlers

SmallWebRTCTransport provides event handlers for client connection lifecycle and application messaging. Register handlers using the @event_handler decorator on the transport instance.

​
Events Summary

EventDescription
on_client_connectedClient WebRTC connection established
on_client_disconnectedClient WebRTC connection closed
on_app_messageApp message received from client

​
Connection Lifecycle

​
on_client_connected

Fired when a client establishes a WebRTC peer connection. 
@transport.event_handler("on_client_connected")
async def on_client_connected(transport, webrtc_connection):
    print("Client connected")
Parameters:
ParameterTypeDescription
transportSmallWebRTCTransportThe transport instance
webrtc_connectionSmallWebRTCConnectionThe WebRTC connection object

​
on_client_disconnected

Fired when a client’s WebRTC peer connection is closed. 
@transport.event_handler("on_client_disconnected")
async def on_client_disconnected(transport, webrtc_connection):
    print("Client disconnected")
Parameters:
ParameterTypeDescription
transportSmallWebRTCTransportThe transport instance
webrtc_connectionSmallWebRTCConnectionThe WebRTC connection object

​
Messaging

​
on_app_message

Fired when an application message is received from a client through the WebRTC data channel. 
@transport.event_handler("on_app_message")
async def on_app_message(transport, message, sender):
    print(f"Message from {sender}: {message}")
Parameters:
ParameterTypeDescription
transportSmallWebRTCTransportThe transport instance
messageAnyThe message content
senderstrThe sender’s peer connection ID

​
ICE Servers Configuration

WebRTC uses ICE (Interactive Connectivity Establishment) to find the best network path between two peers. ICE relies on two types of helper servers:
  • STUN (Session Traversal Utilities for NAT) — Helps a client discover its public IP address and port when it’s behind a NAT device. WebRTC uses this information to attempt a direct peer-to-peer connection.
  • TURN (Traversal Using Relays around NAT) — A relay fallback used when a direct connection isn’t possible due to strict NATs or firewalls. All media traffic is routed through the TURN server in this case.
ICE servers are optional for local network development but become important as soon as peers are on different networks.

​
When do you need ICE servers?

ScenarioSTUN neededTURN needed
Both peers on the same local networkNoNo
Peers on different networks (Linux)YesUsually not
Peers on different networks (macOS / strict NAT)YesYes
Docker on macOS (no --network=host)YesYes
Production deploymentYesRecommended

​
Server-side configuration

Pass ICE servers when creating SmallWebRTCConnection. You can provide simple URL strings or full IceServer objects (an alias for aiortc’s RTCIceServer): 
from pipecat.transports.smallwebrtc.connection import SmallWebRTCConnection, IceServer

webrtc_connection = SmallWebRTCConnection(
    ice_servers=[
        IceServer(urls=["stun:stun.l.google.com:19302"]),
        IceServer(
            urls=["turn:your-turn-server.example.com:3478"],
            username="your-username",
            credential="your-password",
        ),
    ]
)
In production, WebRTC applications must run over HTTPS. Browsers block WebRTC access to microphone and camera on insecure origins.

​
Advanced Configuration

​
PIPECAT_SCTP_MAX_CHUNK_SIZE

Controls the maximum SCTP DATA-chunk payload size (in bytes) used by aiortc’s data channel. The default is 1100. 
PIPECAT_SCTP_MAX_CHUNK_SIZE=1100
This is a process-global setting due to an aiortc limitation — all SmallWebRTC connections in the same process share the same value.
When to lower it Lower this value if the data channel silently stalls on your network. This happens when aiortc’s internal default produces UDP datagrams larger than your path’s MTU. Each chunk carries roughly 105 bytes of SCTP + DTLS + UDP + IP overhead, so a 1200-byte chunk results in a ~1305-byte datagram. This exceeds the 1280-byte MTU common on:
  • IPv6 paths
  • Tailscale overlays
  • Many consumer VPNs
When the datagram is too large the kernel drops it with EMSGSIZE. aiortc retransmits at the same size and the channel stalls indefinitely. Setting PIPECAT_SCTP_MAX_CHUNK_SIZE=1100 produces ~1205-byte datagrams, which fits any path with MTU ≥ 1210. When to raise it Only raise it if you are on a controlled LAN with MTU 1500 and are sending large data-channel messages where extra fragmentation matters. Values above 1200 are unsafe on most internet paths.

​
Additional Resources