Pipecat

If your voice agent runs on Pipecat, pipecat-protoface adds a Protoface avatar as a video service. It starts a hosted Protoface session, consumes assistant audio from the pipeline, and emits synchronized audio and video frames to your output transport. If you’re not using Pipecat, Protoface also integrates with many more platforms and SDKs. See More Integrations. Official Pipecat-hosted docs are also available. Protoface maintains the official Pipecat community plugin.

Install

uv add pipecat-protoface

Install Pipecat extras for your transport, STT, LLM, TTS, or realtime model separately.

Basic usage

import os

from pipecat_protoface import ProtofaceVideoService

protoface = ProtofaceVideoService(
    api_key=os.environ["PROTOFACE_API_KEY"],
    avatar_id=os.environ["PROTOFACE_AVATAR_ID"],
)

Add protoface after TTS and before transport.output():

pipeline = Pipeline([
    transport.input(),
    stt,
    context_aggregator.user(),
    llm,
    tts,
    protoface,
    transport.output(),
    context_aggregator.assistant(),
])

After the pipeline starts, protoface emits synchronized avatar audio and video frames downstream.

Realtime speech-to-speech

For realtime speech-to-speech, put protoface after the realtime model and before the output transport:

pipeline = Pipeline([
    transport.input(),
    context_aggregator.user(),
    gemini_live,
    context_aggregator.assistant(),
    protoface,
    transport.output(),
])

Configuration

Set both variables in the Pipecat worker environment:

PROTOFACE_API_KEY: Authenticates calls to Protoface.
PROTOFACE_AVATAR_ID: Avatar to render. Start with av_stock_001 or use an ID from /v1/avatars.

ProtofaceVideoService options

Option	Purpose
`api_key`	Protoface API key.
`avatar_id`	Avatar to render. Use an ID from the dashboard or `/v1/avatars`.
`api_url`	Protoface API base URL. Defaults to `https://api.protoface.com`.
`max_duration_seconds`	Optional upper bound for the Protoface session.
`metadata`	Metadata attached to the Protoface session.
`settings`	Advanced buffering and client-readiness settings.

Lifecycle

ProtofaceVideoService starts a hosted Protoface session when the pipeline starts. Audio produced before the avatar session is ready is buffered, then streamed once the connection is available.

Compatibility

Tested with Pipecat v1.4.0+ and Python 3.11+. Check the plugin source for current examples and compatibility notes.

Pipecat docs

Service reference and examples in Pipecat’s docs.

Plugin source

Source code, examples, and issues.

Avatars

Choose the avatar ID for your app.

Get started

Integrations

Guides

Reference

Install

Basic usage

Realtime speech-to-speech

Configuration

ProtofaceVideoService options

Lifecycle

Compatibility

Next

Pipecat docs

Plugin source

Avatars

​Install

​Basic usage

​Realtime speech-to-speech

​Configuration

​ProtofaceVideoService options

​Lifecycle

​Compatibility

​Next

Pipecat docs

Plugin source

Avatars

Install

Basic usage

Realtime speech-to-speech

Configuration

ProtofaceVideoService options

Lifecycle

Compatibility

Next