Skip to main content

​
Overview

ProtofaceVideoService renders Pipecat TTS output through a real-time Protoface video avatar. It consumes TTS audio and emits synchronized avatar video (OutputImageRawFrame) and audio (SpeechOutputAudioRawFrame) downstream. Use it with any Pipecat transport that supports audio and video output.

Source Repository

Source code, examples, and issues for the Protoface integration

PyPI Package

The pipecat-protoface package on PyPI

Protoface Documentation

Official Protoface documentation and guides

Protoface Platform

Create avatars and manage API access

​
Installation

This is a community-maintained package distributed separately from pipecat-ai: 
uv add pipecat-protoface
Install any Pipecat extras required by your chosen transport and AI services separately.

​
Prerequisites

​
Protoface Account Setup

Before using the Protoface video service, you need:
  1. Protoface API key: Get access through the Protoface Platform
  2. Protoface avatar ID: Create or select an avatar in the Protoface Platform and copy its ID
You’ll also need API keys for the Pipecat services used in your pipeline.

​
Required Environment Variables

  • PROTOFACE_API_KEY: Your Protoface API key
  • PROTOFACE_AVATAR_ID: Your Protoface avatar ID

​
Configuration

Constructor parameters for ProtofaceVideoService:
​
api_key
str
required
Protoface API key for authentication.
​
avatar_id
str
required
Protoface avatar ID for the hosted avatar session.
​
api_url
str
default:"https://api.protoface.com"
Protoface API URL. Most users can omit this.
​
max_duration_seconds
int
default:"None"
Maximum session duration in seconds.
​
metadata
Mapping
default:"None"
Metadata to attach when creating the Protoface session.
​
settings
ProtofaceVideoSettings
default:"None"
Advanced settings for buffering and client readiness. Most users can omit this.
For the latest examples and configuration options, see the source repository.

​
Usage

​
Basic Setup

import os

from pipecat_protoface import ProtofaceVideoService
from pipecat.pipeline.pipeline import Pipeline

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

pipeline = Pipeline([
    transport.input(),
    stt,
    context_aggregator.user(),
    llm,
    tts,
    protoface,  # Video avatar (emits synchronized audio/video)
    transport.output(),
    context_aggregator.assistant(),
])

​
Realtime Speech-to-Speech

For realtime speech-to-speech services, place ProtofaceVideoService after your realtime LLM service and before the output transport: 
pipeline = Pipeline([
    transport.input(),
    context_aggregator.user(),
    gemini_live,
    context_aggregator.assistant(),
    protoface,
    transport.output(),
])
See the example in the source repository for a complete WebRTC pipeline using Gemini Live.

​
Compatibility

Tested with Pipecat v1.4.0+ (Python 3.11+). Check the source repository for the latest compatibility notes and examples.