SmallWebRTCTransport

A lightweight WebRTC transport for peer-to-peer audio and video communication in Pipecat

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:

# For audio-only pipelines
uv add "pipecat-ai[webrtc]"

# For pipelines with video support
uv add "pipecat-ai[webrtc-video]"

The webrtc extra provides audio and basic video support via aiortc. The webrtc-video extra adds OpenCV support for using SmallWebRTCTransport with video.

opencv-python-headless will be removed from the webrtc extra in 2.0.0. Video pipelines using SmallWebRTCTransport should start installing the new webrtc-video extra (pipecat-ai[webrtc-video]) instead.

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

Event	Description
on_client_connected	Client WebRTC connection established
on_client_disconnected	Client WebRTC connection closed
on_app_message	App 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:

Parameter	Type	Description
transport	SmallWebRTCTransport	The transport instance
webrtc_connection	SmallWebRTCConnection	The 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:

Parameter	Type	Description
transport	SmallWebRTCTransport	The transport instance
webrtc_connection	SmallWebRTCConnection	The 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:

Parameter	Type	Description
transport	SmallWebRTCTransport	The transport instance
message	Any	The message content
sender	str	The 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?

Scenario	STUN needed	TURN needed
Both peers on the same local network	No	No
Peers on different networks (Linux)	Yes	Usually not
Peers on different networks (macOS / strict NAT)	Yes	Yes
Docker on macOS (no --network=host)	Yes	Yes
Production deployment	Yes	Recommended

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

• Events Overview - Overview of all events in Pipecat
• Pipecat Development Runner’s Transport Utilities
• Client SDK Integration