Video

This module implements Tavus as a sink transport layer

class pipecat.services.tavus.video.TavusVideoService(*, api_key, replica_id, persona_id='pipecat-stream', session, **kwargs)[source]

Bases: AIService

Service class that proxies audio to Tavus and receives both audio and video in return.

It uses the TavusTransportClient to manage the session and handle communication. When audio is sent, Tavus responds with both audio and video streams, which are then routed through Pipecat’s media pipeline.

In use cases such as with DailyTransport, this results in two distinct virtual rooms:

  • Tavus room: Contains the Tavus Avatar and the Pipecat Bot.

  • User room: Contains the Pipecat Bot and the user.

Parameters:

  • api_key (str) – Tavus API key used for authentication.

  • replica_id (str) – ID of the Tavus voice replica to use for speech synthesis.

  • persona_id (str) – ID of the Tavus persona. Defaults to “pipecat-stream” to use the Pipecat TTS voice.

  • session (aiohttp.ClientSession) – Async HTTP session used for communication with Tavus.

  • **kwargs – Additional arguments passed to the parent AIService class.

async setup(setup)[source]
Parameters:

setup (FrameProcessorSetup)

async cleanup()[source]
can_generate_metrics()[source]
Return type:

bool

async get_persona_name()[source]
Return type:

str

async start(frame)[source]

Start the AI service.

Called when the service should begin processing. Subclasses should override this method to perform service-specific initialization.

Parameters:

frame (StartFrame) – The start frame containing initialization parameters.

async stop(frame)[source]

Stop the AI service.

Called when the service should stop processing. Subclasses should override this method to perform cleanup operations.

Parameters:

frame (EndFrame) – The end frame.

async cancel(frame)[source]

Cancel the AI service.

Called when the service should cancel all operations. Subclasses should override this method to handle cancellation logic.

Parameters:

frame (CancelFrame) – The cancel frame.

async process_frame(frame, direction)[source]

Process frames and handle service lifecycle.

Automatically handles StartFrame, EndFrame, and CancelFrame by calling the appropriate lifecycle methods.

Parameters:

  • frame (Frame) – The frame to process.

  • direction (FrameDirection) – The direction of frame processing.