> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<CardGroup cols={2}>
  <Card title="LiveKitTransport API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.transports.livekit.transport.html">
    Pipecat's API methods for LiveKit integration
  </Card>

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/transports/transports-livekit.py">
    Complete LiveKit voice agent example
  </Card>

  <Card title="LiveKit Documentation" icon="book" href="https://docs.livekit.io/reference/">
    Official LiveKit API documentation and guides
  </Card>

  <Card title="LiveKit Cloud" icon="external-link" href="https://cloud.livekit.io/login">
    Sign up for hosted LiveKit service
  </Card>
</CardGroup>

## Installation

To use LiveKitTransport, install the required dependencies:

```bash theme={null}
uv add "pipecat-ai[livekit]"
```

## Prerequisites

### LiveKit Setup

Before using LiveKitTransport, you need:

1. **LiveKit Server**: Set up self-hosted or use [LiveKit Cloud](https://cloud.livekit.io/)
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

<ParamField path="url" type="str" required>
  LiveKit server URL to connect to (e.g., `wss://your-domain.livekit.cloud`).
</ParamField>

<ParamField path="token" type="str" required>
  Authentication token (JWT) for the LiveKit room.
</ParamField>

<ParamField path="room_name" type="str" required>
  Name of the LiveKit room to join.
</ParamField>

<ParamField path="params" type="LiveKitParams" default="LiveKitParams()">
  Transport configuration parameters. Inherits all parameters from
  [TransportParams](/api-reference/server/services/transport/transport-params).
</ParamField>

<ParamField path="input_name" type="str" default="None">
  Optional name for the input transport processor.
</ParamField>

<ParamField path="output_name" type="str" default="None">
  Optional name for the output transport processor.
</ParamField>

## 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](https://github.com/pipecat-ai/pipecat/blob/main/examples/transports/transports-livekit.py) 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.

```python theme={null}
@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.

```python theme={null}
@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.

```python theme={null}
@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 |

<Note>
  This is a **synchronous** event — the bot will not disconnect until all
  handlers complete. Keep handlers fast.
</Note>

#### on\_call\_state\_updated

Fired when the call state changes.

```python theme={null}
@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.

```python theme={null}
@transport.event_handler("on_first_participant_joined")
async def on_first_participant_joined(transport, participant_id):
    await task.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.

```python theme={null}
@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.

```python theme={null}
@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   |

<Note>
  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.
</Note>

#### on\_participant\_left

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

```python theme={null}
@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 |

```python theme={null}
@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.

```python theme={null}
@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](/api-reference/server/events/overview) - Overview of all events in Pipecat