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

# SpatialReal Avatar

> SpatialRealAvatarProcessor gives a Pipecat voice bot a real-time 3D avatar, rendered in the browser and kept in sync with the bot's audio.

> [!NOTE]
>
> **Community-maintained integration.** This service is built and
> maintained by
> [SpatialReal-ai](https://github.com/SpatialReal-ai)
> . Pipecat does not test or officially support it. Please report issues and
> request changes on the
> [source repository](https://github.com/SpatialReal-ai/pipecat-spatialreal)
> . Learn more about
> [community integrations](https://docs.pipecat.ai/api-reference/server/services/community-integrations.md)
> .

## Overview

`SpatialRealAvatarProcessor` gives a voice bot a [SpatialReal](https://www.spatialreal.ai/)
avatar. Place it right after the TTS service: it streams the bot's speech to SpatialReal for
facial animation, sends the animation to the browser as RTVI server messages, and releases the
audio in step with it. The avatar is rendered in the browser by the SpatialReal web SDK, so the
pipeline never carries video frames and the bot's audio keeps playing through your transport.

Works with Pipecat's Daily and LiveKit transports.

> [!WARNING]
>
> Your client must render the avatar with the SpatialReal web SDK
> (`@spatialreal/web-sdk` 1.0.0-beta.6 or newer). The pipeline sends no video,
> so a client without the SDK, such as Pipecat's prebuilt UI, plays the bot's
> voice but shows no avatar. See [Browser](#browser).

> [card] [Source Repository](https://github.com/SpatialReal-ai/pipecat-spatialreal)
>
> Source code, the example bot and browser page, and issues

> [card] [PyPI Package](https://pypi.org/project/pipecat-spatialreal/)
>
> The `pipecat-spatialreal` package on PyPI

> [card] [SpatialReal Pipecat Guide](https://docs.spatialreal.ai/avatar-integration/pipecat/overview)
>
> The bot, the web client and a complete example

> [card] [SpatialReal Studio](https://app.spatialreal.ai)
>
> Create an app, pick an avatar and get an API key

## Installation

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

```bash theme={null}
uv add pipecat-spatialreal
```

The browser renders the avatar with the SpatialReal web SDK (1.0.0-beta.6 or newer has the Pipecat
session):

```bash theme={null}
npm install @spatialreal/web-sdk@^1.0.0-beta.6
```

## Prerequisites

### SpatialReal Account Setup

1. **API key** and **app ID**: create an app in SpatialReal Studio
2. **Avatar ID**: pick an avatar and copy its ID
3. **Client**: a web app that renders the avatar with the SpatialReal web SDK

You'll also need API keys for the other Pipecat services in your pipeline. RTVI must be enabled
(Pipecat's default for `PipelineWorker`): the animation reaches the browser as RTVI server
messages.

### Required Environment Variables

* `SPATIALREAL_API_KEY`: your SpatialReal API key (server only)
* `SPATIALREAL_APP_ID`: your SpatialReal app ID
* `SPATIALREAL_AVATAR_ID`: the avatar to animate

The API key stays on the server: the browser gets a short-lived session token from your own
backend. The example bot in the repository includes a route that mints one.

## Configuration

Constructor parameters for `SpatialRealAvatarProcessor` (keyword arguments):

**api\_key** `str` *required*

SpatialReal API key.

**app\_id** `str` *required*

SpatialReal app ID.

**avatar\_id** `str` *required*

The avatar to animate. The browser must render the same avatar.

**environment** `str` (default: us-west)

The SpatialReal deployment to use. Most users can omit this.

**lead\_ms** `int` (default: 200)

How far ahead of real time the audio is released to the transport.

> [!NOTE]
>
> The repository's README lists every parameter, the browser-side setup and the
> known limitations.

## Usage

### Pipeline

```python theme={null}
import os

from pipecat.pipeline.pipeline import Pipeline
from pipecat_spatialreal import SpatialRealAvatarProcessor

avatar = SpatialRealAvatarProcessor(
    api_key=os.environ["SPATIALREAL_API_KEY"],
    app_id=os.environ["SPATIALREAL_APP_ID"],
    avatar_id=os.environ["SPATIALREAL_AVATAR_ID"],
)

pipeline = Pipeline([
    transport.input(),
    stt,
    user_aggregator,
    llm,
    tts,
    avatar,  # right after the TTS, before the transport's output
    transport.output(),
    assistant_aggregator,
])
```

### Browser

In the browser, create a SpatialReal session in Pipecat mode, hand it the bot's audio track and
every RTVI server message from your `PipecatClient`. The SDK plays the bot's voice itself, so do
not also attach the track to an `<audio>` element.

```javascript theme={null}
const session = await new SpatialReal({ appId }).createSession({
  avatarId,
  credential: sessionToken,
  container,
  pipecat: {},
});
await session.start();

const client = new PipecatClient({
  transport,
  enableMic: true,
  callbacks: {
    onTrackStarted: (track, participant) => {
      if (track.kind === "audio" && isBot(participant))
        session.setBotAudioTrack(track);
    },
    onServerMessage: (data) => session.handleServerMessage(data),
  },
});
```

See the [complete example](https://github.com/SpatialReal-ai/spatialreal-examples/tree/main/avatar-integration/pipecat)
(a bot and a web client) for a full Daily or LiveKit setup, and the
[web client guide](https://docs.spatialreal.ai/avatar-integration/pipecat/web-client) for each step.

## Compatibility

Tested with Pipecat v1.15.0 (Python 3.11+) on Daily and LiveKit. Check the
[source repository](https://github.com/SpatialReal-ai/pipecat-spatialreal) for
the latest compatibility notes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.