Skip to main content

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

Tavus Transport API Reference

Pipecat’s API methods for Tavus platform integration

Example Implementation

Complete Tavus avatar conversation example

Tavus API Documentation

Tavus official API reference and replica creation

Client SDK Integration

Connect using Pipecat Client SDK with Daily transport

​
Installation

To use TavusTransport, install the required dependencies: 
pip install "pipecat-ai[tavus]"

​
Prerequisites

​
Tavus Platform Setup

Before using TavusTransport, you need:
  1. Tavus Account: Sign up at 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)
Use persona_id="pipecat-stream" to have Tavus use your Pipecat bot’s TTS voice instead of a Tavus persona voice.

​
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

​
bot_name
str
required
The name of the Pipecat bot instance.
​
session
aiohttp.ClientSession
required
An aiohttp session for making async HTTP requests to the Tavus API.
​
api_key
str
required
Tavus API key for authentication.
​
replica_id
str
required
ID of the Tavus replica model to use for voice generation.
​
persona_id
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.
​
params
TavusParams
default:"TavusParams()"
Transport configuration parameters.
​
input_name
str
default:"None"
Optional name for the input transport processor.
​
output_name
str
default:"None"
Optional name for the output transport processor.

​
TavusParams

Inherits from DailyParams with the following defaults changed:
​
audio_in_enabled
bool
default:"True"
Whether to enable audio input from participants.
​
audio_out_enabled
bool
default:"True"
Whether to enable audio output to participants.
​
microphone_out_enabled
bool
default:"False"
Whether to enable microphone output track.

​
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. See the complete example 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

EventDescription
on_client_connectedParticipant (non-avatar) connected to the session
on_client_disconnectedParticipant (non-avatar) disconnected from the session
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.

​
Connection Lifecycle

​
on_client_connected

Fired when a human participant connects to the session. The Tavus replica is filtered out from this event. 
@transport.event_handler("on_client_connected")
async def on_client_connected(transport, participant):
    print(f"Client connected: {participant}")
Parameters:
ParameterTypeDescription
transportTavusTransportThe transport instance
participantdictParticipant data from Daily (includes id, info with userName, etc.)

​
on_client_disconnected

Fired when a human participant disconnects from the session. 
@transport.event_handler("on_client_disconnected")
async def on_client_disconnected(transport, participant):
    print(f"Client disconnected: {participant}")
Parameters:
ParameterTypeDescription
transportTavusTransportThe transport instance
participantdictParticipant data from Daily

​
Additional Resources