SpatialReal Avatar

Community-maintained integration. This service is built and maintained by SpatialReal-ai. Pipecat does not test or officially support it. Please report issues and request changes on the source repository. Learn more about community integrations.

Overview

SpatialRealAvatarProcessor gives a voice bot a SpatialReal 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.

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.

Source Repository

Source code, the example bot and browser page, and issues

PyPI Package

The pipecat-spatialreal package on PyPI

SpatialReal Pipecat Guide

The bot, the web client and a complete example

SpatialReal Studio

Create an app, pick an avatar and get an API key

Installation

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

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):

npm install @spatialreal/web-sdk@^1.0.0-beta.6

Prerequisites

SpatialReal Account Setup

API key and app ID: create an app in SpatialReal Studio
Avatar ID: pick an avatar and copy its ID
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):

str

required

SpatialReal API key.

str

required

SpatialReal app ID.

str

required

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

str

default:"us-west"

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

int

default:"200"

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

The repository’s README lists every parameter, the browser-side setup and the known limitations.

Usage

Pipeline

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.

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 (a bot and a web client) for a full Daily or LiveKit setup, and the web client guide for each step.

Compatibility

Tested with Pipecat v1.15.0 (Python 3.11+) on Daily and LiveKit. Check the source repository for the latest compatibility notes.

Get Started

Standards

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

SpatialReal Avatar

Overview

Source Repository

PyPI Package

SpatialReal Pipecat Guide

SpatialReal Studio

Installation

Prerequisites

SpatialReal Account Setup

Required Environment Variables

Configuration

Usage

Pipeline

Browser

Compatibility

​Overview

Source Repository

PyPI Package

SpatialReal Pipecat Guide

SpatialReal Studio

​Installation

​Prerequisites

​SpatialReal Account Setup

​Required Environment Variables

​Configuration

​Usage

​Pipeline

​Browser

​Compatibility

Overview

Installation

Prerequisites

SpatialReal Account Setup

Required Environment Variables

Configuration

Usage

Pipeline

Browser

Compatibility