LiveKitTransport

WebRTC transport implementation using LiveKit for real-time audio communication

Overview

LiveKitTransport provides real-time audio communication capabilities using LiveKit’s open-source WebRTC platform. It supports bidirectional audio streaming, data messaging, participant management, and room event handling for conversational AI applications with the flexibility of self-hosted or cloud infrastructure.

LiveKitTransport API Reference

Pipecat’s API methods for LiveKit integration

Example Implementation

Complete LiveKit voice agent example

LiveKit Documentation

Official LiveKit API documentation and guides

LiveKit Cloud

Sign up for hosted LiveKit service

Installation

To use LiveKitTransport, install the required dependencies:

uv add "pipecat-ai[livekit]"

Prerequisites

LiveKit Setup

Before using LiveKitTransport, you need:

1. LiveKit Server: Set up self-hosted or use LiveKit Cloud
2. API Credentials: Generate API key and secret from your LiveKit project
3. Room Management: Create rooms using LiveKit API or SDK
4. Access Tokens: Generate JWT tokens for room authentication

Required Environment Variables

• LIVEKIT_API_KEY: Your LiveKit API key for authentication
• LIVEKIT_API_SECRET: Your LiveKit API secret for token generation
• LIVEKIT_URL: Your LiveKit server URL (wss://your-domain.livekit.cloud)

Key Features

• Open Source: Self-hosted or cloud-hosted WebRTC infrastructure
• Multi-participant Support: Handle multiple participants in rooms
• Data Channels: Real-time messaging alongside audio streams
• Room Management: Dynamic participant and room lifecycle management
• Flexible Deployment: Self-hosted or managed cloud options

Configuration

LiveKitTransport

url · str · required

LiveKit server URL to connect to (e.g., wss://your-domain.livekit.cloud).

token · str · required

Authentication token (JWT) for the LiveKit room.

room_name · str · required

Name of the LiveKit room to join.

params · LiveKitParams · default: "LiveKitParams()"

Transport configuration parameters. Inherits all parameters from TransportParams.

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

LiveKitTransport connects your Pipecat bot to LiveKit rooms where it can communicate with participants through audio and data channels. The transport handles room joining, participant events, and media streaming automatically.

See the complete example for a full implementation including:

• LiveKit room creation and token generation
• Transport configuration with participant management
• Pipeline integration with audio processing
• Event handling for room lifecycle management

Event Handlers

LiveKitTransport provides event handlers for room lifecycle, participant management, and media track events. Register handlers using the @event_handler decorator on the transport instance.

Events Summary

Event	Description
on_connected	Connected to the room
on_disconnected	Disconnected from the room
on_before_disconnect	About to disconnect (sync)
on_call_state_updated	Call state changed
on_first_participant_joined	First participant joined
on_participant_connected	A participant connected
on_participant_disconnected	A participant disconnected
on_participant_left	A participant left
on_audio_track_subscribed	Audio track subscribed
on_audio_track_unsubscribed	Audio track unsubscribed
on_video_track_subscribed	Video track subscribed
on_video_track_unsubscribed	Video track unsubscribed
on_data_received	Data message received

Room Lifecycle

on_connected

Fired when the bot successfully connects to the LiveKit room.

@transport.event_handler("on_connected")
async def on_connected(transport):
    print("Connected to LiveKit room")

Parameters:

Parameter	Type	Description
transport	LiveKitTransport	The transport instance

on_disconnected

Fired when the bot disconnects from the room.

@transport.event_handler("on_disconnected")
async def on_disconnected(transport):
    print("Disconnected from LiveKit room")

Parameters:

Parameter	Type	Description
transport	LiveKitTransport	The transport instance

on_before_disconnect

Fired synchronously just before the bot disconnects from the room. Use this for cleanup that must happen before disconnection.

@transport.event_handler("on_before_disconnect")
async def on_before_disconnect(transport):
    print("About to disconnect...")

Parameters:

Parameter	Type	Description
transport	LiveKitTransport	The transport instance

This is a synchronous event — the bot will not disconnect until all handlers complete. Keep handlers fast.

on_call_state_updated

Fired when the call state changes.

@transport.event_handler("on_call_state_updated")
async def on_call_state_updated(transport, state):
    print(f"Call state: {state}")

Parameters:

Parameter	Type	Description
transport	LiveKitTransport	The transport instance
state	str	The new call state

Participants

on_first_participant_joined

Fired when the first participant (other than the bot) joins the room. This is commonly used to start the conversation.

@transport.event_handler("on_first_participant_joined")
async def on_first_participant_joined(transport, participant_id):
    await worker.queue_frame(TTSSpeakFrame("Hello! How can I help you today?"))

Parameters:

Parameter	Type	Description
transport	LiveKitTransport	The transport instance
participant_id	str	The participant’s ID

on_participant_connected

Fired when a participant connects to the room.

@transport.event_handler("on_participant_connected")
async def on_participant_connected(transport, participant_id):
    print(f"Participant connected: {participant_id}")

Parameters:

Parameter	Type	Description
transport	LiveKitTransport	The transport instance
participant_id	str	The participant’s ID

on_participant_disconnected

Fired when a participant disconnects from the room.

@transport.event_handler("on_participant_disconnected")
async def on_participant_disconnected(transport, participant_id):
    print(f"Participant disconnected: {participant_id}")

Parameters:

Parameter	Type	Description
transport	LiveKitTransport	The transport instance
participant_id	str	The participant’s ID

When a participant disconnects, both on_participant_disconnected and on_participant_left fire. The on_participant_left event includes a "disconnected" reason for compatibility with other transports.

on_participant_left

Fired when a participant leaves the room. This is a transport-agnostic event that fires alongside on_participant_disconnected.

@transport.event_handler("on_participant_left")
async def on_participant_left(transport, participant_id, reason):
    print(f"Participant left: {participant_id} ({reason})")

Parameters:

Parameter	Type	Description
transport	LiveKitTransport	The transport instance
participant_id	str	The participant’s ID
reason	str	Reason for leaving (e.g., "disconnected")

Media Tracks

Track subscription events fire when audio or video tracks from participants are subscribed or unsubscribed. All receive (transport, participant_id).

Event	Description
on_audio_track_subscribed	Audio track from a participant was subscribed
on_audio_track_unsubscribed	Audio track from a participant was unsubscribed
on_video_track_subscribed	Video track from a participant was subscribed
on_video_track_unsubscribed	Video track from a participant was unsubscribed

@transport.event_handler("on_audio_track_subscribed")
async def on_audio_track_subscribed(transport, participant_id):
    print(f"Audio track subscribed for: {participant_id}")

Messaging

on_data_received

Fired when data is received from a participant through LiveKit’s data channel.

@transport.event_handler("on_data_received")
async def on_data_received(transport, data, participant_id):
    print(f"Data from {participant_id}: {data.decode()}")

Parameters:

Parameter	Type	Description
transport	LiveKitTransport	The transport instance
data	bytes	The raw data received
participant_id	str	The sender’s participant ID

Additional Resources

• Events Overview - Overview of all events in Pipecat