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

# TavusTransport

> Conversational AI applications with Tavus avatars using real-time audio/video streaming

## Overview

TavusTransport enables your Pipecat bot to join the same virtual room as a Tavus avatar and human participants. The transport integrates with the Tavus platform to create conversational AI applications where a Tavus avatar provides synchronized video and audio output while your bot handles the conversation logic.

When used, the Pipecat bot connects to a Daily room alongside the Tavus avatar and user. The bot receives audio input from participants, processes it through your pipeline, and sends TTS audio to the Tavus avatar for synchronized video rendering.

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

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/video-avatar/video-avatar-tavus-video-service.py">
    Complete Tavus avatar conversation example
  </Card>

  <Card title="Tavus API Documentation" icon="book" href="https://docs.tavus.io/api-reference/phoenix-replica-model/create-replica">
    Tavus official API reference and replica creation
  </Card>

  <Card title="Client SDK Integration" icon="link" href="/api-reference/client/js/transports/daily">
    Connect using Pipecat Client SDK with Daily transport
  </Card>
</CardGroup>

## Installation

To use TavusTransport, install the required dependencies:

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

## Prerequisites

### Tavus Platform Setup

Before using TavusTransport, you need:

1. **Tavus Account**: Sign up at [Tavus.io](https://tavus.io)
2. **API Key**: Generate a Tavus API key for authentication
3. **Replica ID**: Create or obtain a Tavus replica model ID
4. **Persona Configuration**: Set up a persona (optional, defaults to Pipecat TTS voice)

<Tip>
  Use `persona_id="pipecat-stream"` to have Tavus use your Pipecat bot's TTS
  voice instead of a Tavus persona voice.
</Tip>

### Required Environment Variables

* `TAVUS_API_KEY`: Your Tavus API key for authentication
* `TAVUS_REPLICA_ID`: ID of the Tavus replica model to use

## Key Features

* **Avatar Integration**: Seamlessly integrates Tavus avatars with Pipecat conversations
* **Synchronized Audio/Video**: Tavus avatar renders video synchronized with bot's TTS output
* **Multi-participant Rooms**: Supports bot, avatar, and human participants in the same session
* **Conversation Management**: Handles Tavus conversation lifecycle through API
* **Real-time Streaming**: Bidirectional audio streaming with video avatar output

## Configuration

### TavusTransport

<ParamField path="bot_name" type="str" required>
  The name of the Pipecat bot instance.
</ParamField>

<ParamField path="session" type="aiohttp.ClientSession" required>
  An aiohttp session for making async HTTP requests to the Tavus API.
</ParamField>

<ParamField path="api_key" type="str" required>
  Tavus API key for authentication.
</ParamField>

<ParamField path="replica_id" type="str" required>
  ID of the Tavus replica model to use for voice generation.
</ParamField>

<ParamField path="persona_id" type="str" default="pipecat-stream">
  ID of the Tavus persona. Defaults to `"pipecat-stream"`, which signals Tavus
  to use the Pipecat bot's TTS voice instead of a Tavus persona voice.
</ParamField>

<ParamField path="params" type="TavusParams" default="TavusParams()">
  Transport configuration parameters.
</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>

### TavusParams

Inherits from `DailyParams` with the following defaults changed:

<ParamField path="audio_in_enabled" type="bool" default="True">
  Whether to enable audio input from participants.
</ParamField>

<ParamField path="audio_out_enabled" type="bool" default="True">
  Whether to enable audio output to participants.
</ParamField>

<ParamField path="microphone_out_enabled" type="bool" default="False">
  Whether to enable microphone output track.
</ParamField>

## Usage

TavusTransport creates a three-way conversation between your Pipecat bot, a Tavus avatar, and human participants. The transport manages the Tavus API integration and Daily room connectivity automatically.

### How the conversation flow works

When the pipeline starts, TavusTransport handles room creation behind the scenes:

1. Calls the Tavus API to create a new conversation (using your `replica_id` and `persona_id`)
2. Tavus returns a `conversation_url`, which is a Daily room URL
3. The bot automatically joins this room
4. The Tavus avatar also joins the same room
5. A human participant can join the room using the same URL

The `conversation_url` is consumed internally by the transport. To retrieve the room URL (for example, to share it with a frontend client), use the `on_connected` event handler:

```python theme={null}
@transport.event_handler("on_connected")
async def on_connected(transport, data):
    room_name = data.get("callConfig", {}).get("roomName")
    conversation_url = f"https://tavus.daily.co/{room_name}"
    logger.info(f"Conversation URL: {conversation_url}")
```

<Tip>
  For local development, set the `TAVUS_SAMPLE_ROOM_URL` environment variable
  to skip the Tavus API call and use a pre-existing Daily room URL instead.
</Tip>

See the [complete example](https://github.com/pipecat-ai/pipecat/blob/main/examples/video-avatar/video-avatar-tavus-video-service.py) for a full implementation including:

* Tavus transport configuration
* Avatar and replica setup
* Pipeline integration with TTS
* Event handling for participant management

## Event Handlers

TavusTransport provides event handlers for participant connection lifecycle. Register handlers using the `@event_handler` decorator on the transport instance.

### Events Summary

| Event                    | Description                                            |
| ------------------------ | ------------------------------------------------------ |
| `on_connected`           | Bot connected to the room                              |
| `on_client_connected`    | Participant (non-avatar) connected to the session      |
| `on_client_disconnected` | Participant (non-avatar) disconnected from the session |

<Note>
  The Tavus replica participant is automatically filtered out from these events.
  Only human participant connections trigger the event handlers. The transport
  also automatically unsubscribes from the Tavus replica's microphone to prevent
  audio feedback.
</Note>

### Room Lifecycle

#### on\_connected

Fired when the bot connects to the Daily room. The `data` dict contains room configuration from Daily, including `callConfig` with the `roomName` field. This is useful for constructing the conversation URL that frontend clients need to join the session.

```python theme={null}
@transport.event_handler("on_connected")
async def on_connected(transport, data):
    # Extract the room name to build the conversation URL
    room_name = data.get("callConfig", {}).get("roomName")
    conversation_url = f"https://tavus.daily.co/{room_name}"
    logger.info(f"Conversation URL: {conversation_url}")
```

**Parameters:**

| Parameter   | Type             | Description                                                                                 |
| ----------- | ---------------- | ------------------------------------------------------------------------------------------- |
| `transport` | `TavusTransport` | The transport instance                                                                      |
| `data`      | `dict`           | Join event data from Daily. Contains `callConfig` (with `roomName`), participant info, etc. |

### Connection Lifecycle

#### on\_client\_connected

Fired when a human participant connects to the session. The Tavus replica is filtered out from this event.

```python theme={null}
@transport.event_handler("on_client_connected")
async def on_client_connected(transport, participant):
    print(f"Client connected: {participant}")
```

**Parameters:**

| Parameter     | Type             | Description                                                               |
| ------------- | ---------------- | ------------------------------------------------------------------------- |
| `transport`   | `TavusTransport` | The transport instance                                                    |
| `participant` | `dict`           | Participant data from Daily (includes `id`, `info` with `userName`, etc.) |

#### on\_client\_disconnected

Fired when a human participant disconnects from the session.

```python theme={null}
@transport.event_handler("on_client_disconnected")
async def on_client_disconnected(transport, participant):
    print(f"Client disconnected: {participant}")
```

**Parameters:**

| Parameter     | Type             | Description                 |
| ------------- | ---------------- | --------------------------- |
| `transport`   | `TavusTransport` | The transport instance      |
| `participant` | `dict`           | Participant data from Daily |

## Additional Resources

* [Events Overview](/api-reference/server/events/overview) - Overview of all events in Pipecat
* [Client SDK Integration](/api-reference/client/js/transports/daily)