> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Protoface

> Real-time video avatars for conversational AI

export const CommunityMaintained = ({maintainer, maintainerUrl, repo}) => <Note>
    <strong>Community-maintained integration.</strong> This service is built and
    maintained by{" "}
    <a href={maintainerUrl} target="_blank" rel="noreferrer">
      {maintainer}
    </a>
    . Pipecat does not test or officially support it. Please report issues and
    request changes on the{" "}
    <a href={repo} target="_blank" rel="noreferrer">
      source repository
    </a>
    . Learn more about{" "}
    <a href="/api-reference/server/services/community-integrations">
      community integrations
    </a>
    .
  </Note>;

<CommunityMaintained maintainer="protoface-ai" maintainerUrl="https://github.com/protoface-ai" repo="https://github.com/protoface-ai/protoface-plugin-pipecat" />

## 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.

<CardGroup cols={2}>
  <Card title="Source Repository" icon="github" href="https://github.com/protoface-ai/protoface-plugin-pipecat">
    Source code, examples, and issues for the Protoface integration
  </Card>

  <Card title="PyPI Package" icon="cube" href="https://pypi.org/project/pipecat-protoface/">
    The `pipecat-protoface` package on PyPI
  </Card>

  <Card title="Protoface Documentation" icon="book" href="https://docs.protoface.com">
    Official Protoface documentation and guides
  </Card>

  <Card title="Protoface Platform" icon="key" href="https://protoface.com">
    Create avatars and manage API access
  </Card>
</CardGroup>

## Installation

This is a community-maintained package distributed separately from `pipecat-ai`:

```bash theme={null}
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](https://protoface.com)
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`:

<ParamField path="api_key" type="str" required>
  Protoface API key for authentication.
</ParamField>

<ParamField path="avatar_id" type="str" required>
  Protoface avatar ID for the hosted avatar session.
</ParamField>

<ParamField path="api_url" type="str" default="https://api.protoface.com">
  Protoface API URL. Most users can omit this.
</ParamField>

<ParamField path="max_duration_seconds" type="int" default="None">
  Maximum session duration in seconds.
</ParamField>

<ParamField path="metadata" type="Mapping" default="None">
  Metadata to attach when creating the Protoface session.
</ParamField>

<ParamField path="settings" type="ProtofaceVideoSettings" default="None">
  Advanced settings for buffering and client readiness. Most users can omit
  this.
</ParamField>

<Note>
  For the latest examples and configuration options, see the [source
  repository](https://github.com/protoface-ai/protoface-plugin-pipecat).
</Note>

## Usage

### Basic Setup

```python theme={null}
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:

```python theme={null}
pipeline = Pipeline([
    transport.input(),
    context_aggregator.user(),
    gemini_live,
    context_aggregator.assistant(),
    protoface,
    transport.output(),
])
```

See the
[example](https://github.com/protoface-ai/protoface-plugin-pipecat/blob/master/examples/video_service.py)
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](https://github.com/protoface-ai/protoface-plugin-pipecat) for the
latest compatibility notes and examples.