Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spatius.ai/llms.txt

Use this file to discover all available pages before exploring further.

Web Only: LiveKit integration of Spatius is currently web only.

LiveKit Agents demo with Spatius

Explore a reference implementation that shows how to build a LiveKit Agents voice avatar with Spatius across common stack choices.

​
How LiveKit + Spatius Work Together

The architecture:
  • LiveKit room handles transportation.
  • Agent worker runs your own voice agent configured with the Spatius LiveKit Plugin.
  • Motion Server takes agent audio, generates lip-sync avatar motion, and streams the motion data in-sync with audio back into the room.
  • AvatarKit SDK joins room and renders avatar motion + playback audio.

​
Frontend Installation

pnpm add @spatialwalk/avatarkit-rtc @spatialwalk/avatarkit
Spatius is not a video streaming service. Even when you use LiveKit as the transport layer and LiveKit Agents as the voice agent framework, no video frames are transported through LiveKit. Instead, Spatius sends lightweight motion data to the room. The client-side SDK renders that motion data into the avatar in the user’s browser, which is why your frontend needs @spatialwalk/avatarkit and @spatialwalk/avatarkit-rtc.

​
Frontend setup

1

Toolchain setup

We use WebAssembly to render avatar, setup your build toolchain to load wasm module correctly. See Toolchain Setup.
2

Want React components?

Yes → Use AvatarKit UI
3

Or else, use our JavaScript API to build your own UI.

Use JavaScript APIs when you want to own the UI and connection flow.
1

Initialize SDK

import { AvatarSDK, DrivingServiceMode } from '@spatialwalk/avatarkit'

await AvatarSDK.initialize('your-app-id', {
  drivingServiceMode: DrivingServiceMode.host,
})
2

Load Avatar & Create View

const avatar = await AvatarManager.shared.load('avatar-id')
const container = document.getElementById('avatar-container')!
const avatarView = new AvatarView(avatar, container)
3

Create Player with LiveKit Provider

import { AvatarPlayer, LiveKitProvider } from '@spatialwalk/avatarkit-rtc'

const provider = new LiveKitProvider()
const player = new AvatarPlayer(provider, avatarView, {
  logLevel: 'warning',
})
4

Connect to LiveKit Server

await player.connect({
  url: 'wss://your-livekit-server.com',
  token: 'your-livekit-token',
  roomName: 'room-name',
})
5

Start Voice Interaction

// Start microphone publishing
await player.startPublishing()

// Stop microphone
await player.stopPublishing()

// Disconnect when done
await player.disconnect()
Full SDK API reference here.

​
LiveKit Agents Plugin Installation

pip install livekit-plugins-spatialreal

​
Server setup

If you already use LiveKit Agents, add livekit-plugins-spatialreal to your agent worker. The plugin attaches to your AgentSession and sends TTS audio to Spatius; Motion Server publishes the resulting audio and motion data to the same LiveKit room. Configure the required environment variables:
  • Spatius: SPATIALREAL_API_KEY, SPATIALREAL_APP_ID, SPATIALREAL_AVATAR_ID
  • LiveKit: LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET
Then create an AvatarSession and start it with your agent session and room: 
from livekit.agents import AgentSession, JobContext
from livekit.plugins import spatialreal

async def entrypoint(ctx: JobContext):
    await ctx.connect()

    # Your existing agent session
    session = AgentSession(vad=vad, stt=stt, llm=llm, tts=tts)
    avatar = spatialreal.AvatarSession()
    await avatar.start(session, room=ctx.room)

    await session.start(agent=YourAgent(), room=ctx.room)
See the LiveKit Server guide for the full plugin flow, interruption behavior, and API links.