Protoface

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:

Protoface API key: Get access through the Protoface Platform
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:

str

required

Protoface API key for authentication.

str

required

Protoface avatar ID for the hosted avatar session.

str

default:"https://api.protoface.com"

Protoface API URL. Most users can omit this.

int

default:"None"

Maximum session duration in seconds.

Mapping

default:"None"

Metadata to attach when creating the Protoface session.

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.

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

Overview

Source Repository

PyPI Package

Protoface Documentation

Protoface Platform

Installation

Prerequisites

Protoface Account Setup

Required Environment Variables

Configuration

Usage

Basic Setup

Realtime Speech-to-Speech

Compatibility

​Overview

Source Repository

PyPI Package

Protoface Documentation

Protoface Platform

​Installation

​Prerequisites

​Protoface Account Setup

​Required Environment Variables

​Configuration

​Usage

​Basic Setup

​Realtime Speech-to-Speech

​Compatibility

Overview

Installation

Prerequisites

Protoface Account Setup

Required Environment Variables

Configuration

Usage

Basic Setup

Realtime Speech-to-Speech

Compatibility