Spatius virtual avatar integration guide

Available inPython

Overview

Spatius provides realtime avatars that render on the client using 3D Gaussian splatting. You can use the open source Spatius integration for LiveKit Agents to add virtual avatars to your voice AI app.

Avatar: Clara

Unlike other avatar providers, Spatius renders on the client instead of publishing conventional avatar video. As a result, it can't preview in the Agent Console or the LiveKit Playground, and your frontend must use the Spatius client SDK to display the avatar. See Client-side rendering for details.

Installation

Install the plugin from PyPI:

uv add "livekit-agents[spatius]~=1.8"

Authentication

The Spatius plugin requires an API key and an app ID, both created in Spatius Studio . The API key is a server-side secret. Keep it on your backend and never expose it in client code.

Set the following in your .env file:

SPATIUS_API_KEY=<your-spatius-api-key>
SPATIUS_APP_ID=<your-spatius-app-id>

By default, the plugin resolves an ingress region through the Spatius bootstrap API. If resolution fails, it reuses the last region it resolved in the same process, or us-west if it hasn't resolved one yet. To pin a specific region instead, set SPATIUS_REGION in your .env file.

Avatar setup

The Spatius plugin requires an avatar ID, which selects the avatar character to load. Browse the available avatars in the Avatar Library and copy an avatar ID.

Set the ID as the SPATIUS_AVATAR_ID environment variable or pass it to the AvatarSession as the avatar_id parameter.

Usage

Use the Spatius plugin in an AgentSession. For example, you can use this avatar in the Voice AI quickstart.

from livekit import agents
from livekit.agents import AgentServer, AgentSession
from livekit.plugins import spatius

server = AgentServer()

@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: agents.JobContext):
    session = AgentSession(
        # ... stt, llm, tts, etc.
    )

    avatar = spatius.AvatarSession(
        avatar_id="...",  # ID of the Spatius avatar to use. See "Avatar setup" for details.
    )

    # Start the avatar and wait for it to join
    await avatar.start(session, room=ctx.room)

    # Start your agent session with the user
    await session.start(
        # ... room, agent, room_options, etc....
    )

To render the avatar for your users, integrate the Spatius client SDK in your frontend.

Check your TTS sample rate

The plugin sends Ogg Opus by default, which supports five sample rates. If your TTS runs at another rate, the avatar session raises a SpatiusException on start. See Audio format.

Client-side rendering

Spatius renders the avatar on the client rather than sending conventional server-rendered video. The avatar joins the room as a separate participant, but its video track carries motion data in otherwise black frames. A standard video renderer displays a black screen, so your frontend must use the Spatius client SDK and its LiveKit adapter to decode the track and render the avatar.

Because the Agent Console and the LiveKit Playground use a standard video renderer, they show a black frame instead of the avatar. Use a frontend that integrates the Spatius client SDK to see the avatar.

For a working implementation, see the Spatius client integration guide and the reference frontend .

Audio format

The plugin sends Ogg Opus to Spatius by default, which uses less bandwidth and adds less latency than raw PCM.

Ogg Opus encodes only at 8000, 12000, 16000, 24000, or 48000 Hz. Because sample_rate defaults to your TTS sample rate, a TTS running at another rate raises a SpatiusException when the avatar session starts. Rime defaults to 22050 Hz and Resemble to 44100 Hz, so either one hits this. To resolve the error, choose one of the following:

Pin sample_rate to one of the five supported rates.
Send raw PCM, which accepts any rate, with audio_format=spatius.AudioFormat.PCM_S16LE or SPATIUS_AUDIO_FORMAT=pcm_s16le.

Parameters

This section describes some of the available parameters. See the plugin reference for a complete list of all available parameters.

avatar_idstringEnv: SPATIUS_AVATAR_ID

ID of the Spatius avatar to use. Required if the environment variable isn't set. See Avatar setup for details.

regionstringDefault: autoEnv: SPATIUS_REGION

Spatius region to connect to. The auto value resolves a region through the Spatius bootstrap API. On failure it reuses the last region resolved in the same process, or us-west if there isn't one. Pass a concrete region such as us-west to pin one.

audio_formatAudioFormat | strDefault: spatius.AudioFormat.OGG_OPUSEnv: SPATIUS_AUDIO_FORMAT

Audio format sent to Spatius. Use spatius.AudioFormat.OGG_OPUS for Ogg Opus, which lowers bandwidth and latency on the hop to Spatius, or spatius.AudioFormat.PCM_S16LE for raw 16-bit PCM. The environment variable takes the underlying values ogg_opus and pcm_s16le.

sample_rateint

Audio sample rate in Hz. Defaults to the TTS sample rate, or 24000 when the plugin can't detect it. Ogg Opus accepts only five specific rates. See Audio format.

opus_frame_duration_msintDefault: 20

Opus frame duration in milliseconds. Accepts 10, 20, 40, or 60. Applies in Ogg Opus mode only.

opus_applicationstringDefault: audio

Opus encoder mode. Accepts audio, voip, or restricted_lowdelay. Applies in Ogg Opus mode only.

extra_paramsdict[str, str]

Additional session options forwarded verbatim to Spatius during the WebSocket handshake. Both keys and values must be strings. Spatius defines the supported keys, so check their documentation for what you can pass.

Additional resources

The following resources provide more information about using Spatius with LiveKit Agents.

Python package

The livekit-plugins-spatius package on PyPI.

Plugin reference

Reference for the Spatius avatar plugin.

GitHub repo

View the source or contribute to the LiveKit Spatius avatar plugin.

Spatius docs

Spatius's full documentation site.

Client integration guide

Render the Spatius avatar in your frontend.