video

Tavus video service implementation for avatar-based video generation.

This module implements Tavus as a sink transport layer, providing video avatar functionality through Tavus’s streaming API.

class pipecat.services.tavus.video.TavusVideoSettings(model: str | None | _NotGiven = <factory>, extra: dict[str, Any]=<factory>)[source]

Bases: ServiceSettings

Settings for the Tavus video service.

class pipecat.services.tavus.video.TavusVideoService(*, api_key: str, replica_id: str, persona_id: str = 'pipecat-stream', session: ClientSession, settings: TavusVideoSettings | None = None, **kwargs)[source]

Bases: AIService

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

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

In use cases with DailyTransport, this creates two distinct virtual rooms:

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

  • User room: Contains the Pipecat Bot and the user

Settings

alias of TavusVideoSettings

__init__(*, api_key: str, replica_id: str, persona_id: str = 'pipecat-stream', session: ClientSession, settings: TavusVideoSettings | None = None, **kwargs) → None[source]

Initialize the Tavus video service.

Parameters:

  • api_key – Tavus API key used for authentication.

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

  • persona_id – ID of the Tavus persona. Defaults to “pipecat-stream” for Pipecat TTS voice.

  • session – Async HTTP session used for communication with Tavus.

  • settings – Runtime-updatable settings. Tavus has no model concept, so this is primarily used for the extra dict.

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

async setup(setup: FrameProcessorSetup)[source]

Set up the Tavus video service.

Parameters:

setup – Frame processor setup configuration.

async cleanup()[source]

Clean up the service and release resources.

can_generate_metrics() → bool[source]

Check if this service can generate processing metrics.

Returns:

True, as Tavus service supports metrics generation.

async get_persona_name() → str[source]

Get the name of the current persona.

Returns:

The persona name from the Tavus client.

async start(frame: StartFrame)[source]

Start the Tavus video service.

Parameters:

frame – The start frame containing initialization parameters.

async stop(frame: EndFrame)[source]

Stop the Tavus video service.

Parameters:

frame – The end frame.

async cancel(frame: CancelFrame)[source]

Cancel the Tavus video service.

Parameters:

frame – The cancel frame.

async process_frame(frame: Frame, direction: FrameDirection)[source]

Process frames through the service.

Parameters:

  • frame – The frame to process.

  • direction – The direction of frame processing.