LiveKit Transport

Overview

LiveKitTransport provides real-time audio and video communication capabilities using LiveKit’s open-source WebRTC platform. It supports bidirectional audio streaming, video output, 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

Installation

To use LiveKitTransport, install the required dependencies:

uv add "pipecat-ai[livekit]"

Prerequisites

LiveKit Setup

Before using LiveKitTransport, you need:

LiveKit Server: Set up self-hosted or use LiveKit Cloud
API Credentials: Generate API key and secret from your LiveKit project
Room Management: Create rooms using LiveKit API or SDK
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

str

required

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

str

required

Authentication token (JWT) for the LiveKit room.

str

required

Name of the LiveKit room to join.

LiveKitParams

default:"LiveKitParams()"

Transport configuration parameters. See LiveKitParams below. Inherits all parameters from TransportParams.

str

default:"None"

Optional name for the input transport processor.

str

default:"None"

Optional name for the output transport processor.

LiveKitParams

Video output publishes a single "pipecat-video" camera track when video_out_enabled is set (mirroring how audio output always publishes one "pipecat-audio" microphone track). The track is sized using video_out_width/video_out_height and publishes each frame in its own format, which must be "RGB", "RGBA", "BGRA" or "ARGB"; frames in other formats are dropped and an error is logged. video_out_framerate governs how often frames are drawn. Per-destination video routing (multiple named output tracks, as supported by Daily’s camera_out_enabled/register_video_destination) is not yet implemented for LiveKit. video_out_codec selects the published video codec ("VP8", "H264", "VP9", "AV1" or "H265"); LiveKit picks one when unset.

bool

default:"True"

Receive each participant’s audio as its own stream of UserAudioRawFrames tagged with their identity. All of these streams enter the pipeline through the one input transport, so a pipeline that runs a single STT and VAD should only receive one of them. When False, the participants’ audio is mixed into a single real-time stream of InputAudioRawFrames.

int

default:"1000"

Buffer size of the outgoing audio source, in milliseconds. LiveKit’s default is 1000 ms.

int | None

default:"None"

Maximum bitrate of the published video track, in bits per second. When set, video_out_framerate is also sent as the track’s maximum framerate. LiveKit chooses the encoding from the track resolution when unset.

Video input

With video_in_enabled, a participant’s camera ("camera") and screen share ("screenVideo") are received separately, and each UserImageRawFrame carries its source in transport_source. Without video_in_sources, every frame of every video track is passed on. With it, only the listed sources are, each at its own framerate (see TransportParams). A UserImageRequestFrame is answered with the next frame of the requested source, so image-request tools such as fetch_user_image work with LiveKit. A request for a source the participant isn’t sending, for a source not listed in video_in_sources (when it is set) and not captured with capture_participant_video(), or one still waiting when the participant stops sending it or leaves, completes with an error result. Without video_in_enabled=True, no frames are received, so a request waits until the participant stops sending the source or leaves. capture_participant_video(participant_id, framerate=30, video_source="camera", *, on_request_only=False) is a coroutine that captures a source at a framerate and takes precedence over video_in_sources. A framerate of None passes on every frame, and on_request_only=True passes on frames only to answer image requests. Get the participant_id with transport.get_client_id(client). Passing framerate=0 is deprecated since 1.13.0; use on_request_only=True.

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

Frames

Sent to the transport:

Frame	Fields	Effect
`LiveKitOutputTransportMessageFrame`	`message`, `participant_id` (optional)	Sends `message` on the data channel after the audio queued before it, to the participant with that identity or, without one, to the whole room
`LiveKitOutputTransportMessageUrgentFrame`	`message`, `participant_id` (optional)	Sends `message` the same way, at once
`OutputDTMFFrame`	`button` or `buttons`	Sends a SIP DTMF tone. Only the first of `buttons` is sent

A dict message is sent as JSON. A plain OutputTransportMessageFrame goes to the whole room. Pushed by the transport:

Frame	Fields	Meaning
`LiveKitInputTransportMessageFrame`	`message`, `participant_id`	A data channel message that parsed as a JSON object, the one `on_app_message` receives. Pushed upstream and downstream

from pipecat.transports.livekit.transport import LiveKitOutputTransportMessageFrame

await worker.queue_frame(
    LiveKitOutputTransportMessageFrame(message={"type": "status"}, participant_id="user-1")
)

Methods

The room exists once the pipeline starts. Before that, these methods raise Exception.

get_participants()

def get_participants() -> list[str]

Returns the LiveKit identities of the remote participants in the room.

get_participant_metadata()

async def get_participant_metadata(participant_id: str) -> dict

Returns a participant’s id (identity), name, and metadata as a dict, or an empty dict when no participant in the room has that identity.

set_metadata()

async def set_metadata(metadata: str)

Sets the bot’s own participant metadata in the room.

mute_participant()

async def mute_participant(participant_id: str)

Stops the bot receiving a participant’s audio. The participant isn’t muted for anyone else in the room.

unmute_participant()

async def unmute_participant(participant_id: str)

Resumes the bot receiving a participant’s audio after mute_participant().

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_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_client_connected`	A participant connected (alias)
`on_client_disconnected`	A participant disconnected (alias)
`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_app_message`	JSON app message received
`on_data_received`	Data message received
`on_active_speaker_changed`	Loudest speaker in the room changed
`on_dtmf_event`	SIP DTMF tone received (telephony)

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.

Participants

Participant IDs in LiveKitTransport are LiveKit identities (the identity field set when creating access tokens), not session IDs. Methods like get_participants(), get_participant_metadata(), mute_participant(), and unmute_participant() all use identities, as do all participant-related event handlers.

on_first_participant_joined

Fired when the first participant (other than the bot) joins the room, or is already in it when the bot connects. It fires again for the next participant after the room empties. 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 LiveKit identity

on_participant_connected

Fired when a participant connects to the room, and for each participant already in the room when the bot connects.

@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 LiveKit identity

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 LiveKit identity

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 LiveKit identity
`reason`	`str`	Reason for leaving (e.g., `"disconnected"`)

on_client_connected / on_client_disconnected

Transport-agnostic aliases that fire alongside on_participant_connected and on_participant_disconnected respectively, for compatibility with other transports. The handler receives the participant as a dict, with the LiveKit identity under "id".

@transport.event_handler("on_client_connected")
async def on_client_connected(transport, client):
    print(f"Client connected: {client['id']}")

Media Tracks

Track subscription events fire when audio or video tracks from participants are subscribed or unsubscribed. All receive (transport, participant_id), where participant_id is the participant’s LiveKit identity.

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_app_message

Fired when a data channel message parses as a JSON object. on_data_received fires for the same packet with the raw bytes.

@transport.event_handler("on_app_message")
async def on_app_message(transport, message, participant_id):
    print(f"Message from {participant_id}: {message}")

Parameters:

Parameter	Type	Description
`transport`	`LiveKitTransport`	The transport instance
`message`	`dict`	The parsed JSON message
`participant_id`	`str` \| `None`	The sender’s LiveKit identity, or `None` for server SDK-sent packets

on_data_received

Fired when data is received through LiveKit’s data channel. The sender is None for packets sent by a server SDK, which LiveKit delivers unattributed.

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

Parameters:

Parameter	Type	Description
`transport`	`LiveKitTransport`	The transport instance
`data`	`bytes`	The raw data received
`participant_id`	`str` \| `None`	The sender’s LiveKit identity, or `None` for server SDK-sent packets

Active Speaker

on_active_speaker_changed

Fired when the room’s loudest speaker changes. The bot can be the active speaker while it talks.

@transport.event_handler("on_active_speaker_changed")
async def on_active_speaker_changed(transport, participant):
    print(f"Active speaker: {participant['id']}")

Parameters:

Parameter	Type	Description
`transport`	`LiveKitTransport`	The transport instance
`participant`	`dict`	Contains `id`, the speaker’s LiveKit identity

Telephony

on_dtmf_event

Fired when a SIP DTMF tone is received from a participant (available when using LiveKit with SIP/PSTN calls). The transport automatically pushes an InputDTMFFrame downstream, so DTMFAggregator works with LiveKit telephony.

@transport.event_handler("on_dtmf_event")
async def on_dtmf_event(transport, data):
    digit = data.get("digit")
    print(f"DTMF digit received: {digit}")

Parameters:

Parameter	Type	Description
`transport`	`LiveKitTransport`	The transport instance
`data`	`dict`	DTMF data with keys `tone`/`digit` (str), `code` (int), and `participant_id` (str, the LiveKit identity, or `None` when the packet carries no participant)

The transport pushes InputDTMFFrame automatically, so you only need this handler for custom DTMF logic. Use DTMFAggregator to collect digits into sequences.

Additional Resources

Events Overview - Overview of all events in Pipecat

​Overview

LiveKitTransport API Reference

Example Implementation

LiveKit Documentation

LiveKit Cloud

​Installation

​Prerequisites

​LiveKit Setup

​Required Environment Variables

​Key Features

​Configuration

​LiveKitTransport

​LiveKitParams

​Video input

​Usage

​Frames

​Methods

​get_participants()

​get_participant_metadata()

​set_metadata()

​mute_participant()

​unmute_participant()

​Event Handlers

​Events Summary

​Room Lifecycle

​on_connected

​on_disconnected

​on_before_disconnect

​Participants

​on_first_participant_joined

​on_participant_connected

​on_participant_disconnected

​on_participant_left

​on_client_connected / on_client_disconnected

​Media Tracks

​Messaging

​on_app_message

​on_data_received

​Active Speaker

​on_active_speaker_changed

​Telephony

​on_dtmf_event

​Additional Resources

Overview

Installation

Prerequisites

LiveKit Setup

Required Environment Variables

Key Features

Configuration

LiveKitTransport

LiveKitParams

Video input

Usage

Frames

Methods

get_participants()

get_participant_metadata()

set_metadata()

mute_participant()

unmute_participant()

Event Handlers

Events Summary

Room Lifecycle

on_connected

on_disconnected

on_before_disconnect

Participants

on_first_participant_joined

on_participant_connected

on_participant_disconnected

on_participant_left

on_client_connected / on_client_disconnected

Media Tracks

Messaging

on_app_message

on_data_received

Active Speaker

on_active_speaker_changed

Telephony

on_dtmf_event

Additional Resources