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.

LiveKit Agents Integration is a Platform Integration. Use it when your voice agent runs in LiveKit Agents and you want livekit-plugins-spatius to connect that agent worker to Motion Server. The package attaches to your agent and pipes agent audio to Motion Server; Motion Server publishes lip-synced audio and motion data back into the same LiveKit room. LiveKit Agents is the platform integration; the RTC Adapter (@spatius/avatarkit-rtc) is the Web client adapter that renders the avatar stream from the LiveKit room. The LiveKit room itself is the transport.
Web Only: The current AvatarKit RTC client demo path targets Web. LiveKit ships iOS and Android client SDKs, but Spatius does not yet provide iOS or Android demos for this path.

​
Architecture

  • LiveKit room handles transport.
  • Agent worker runs your voice agent with livekit-plugins-spatius attached.
  • Motion Server generates motion data from the agent audio and publishes the synchronized audio + motion stream back into the room.
  • AvatarKit RTC client joins the room and renders the avatar.
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. Spatius sends lightweight motion data; @spatius/avatarkit renders the avatar locally in the browser.

​
Frontend installation

pnpm add @spatius/avatarkit-rtc @spatius/avatarkit

​
Frontend setup

1

Toolchain setup

Configure your build tool to load the AvatarKit WebAssembly assets. See Toolchain Setup.
2

Pick a UI path

  • For drop-in React components, use AvatarKit UI.
  • To own the UI and connection flow yourself, use the JavaScript API below.
3

JavaScript API (custom UI)

1

Initialize SDK

import { AvatarSDK, DrivingServiceMode } from '@spatius/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 '@spatius/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 RTC client API reference: LiveKit Agents Client.

​
LiveKit Agents plugin installation

pip install livekit-plugins-spatius

​
Server setup

If you already use LiveKit Agents, add livekit-plugins-spatius to your agent worker. The package attaches to your AgentSession and pipes TTS audio to Spatius; Motion Server publishes the resulting audio and motion data to the same LiveKit room. Required environment variables:
  • Spatius: SPATIUS_API_KEY, SPATIUS_APP_ID, SPATIUS_AVATAR_ID
  • Optional region: SPATIUS_REGION defaults to us-west
  • LiveKit: LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET
Create an AvatarSession and start it with your agent session and room: 
from livekit.agents import AgentSession, JobContext
from livekit.plugins import spatius

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

    session = AgentSession(vad=vad, stt=stt, llm=llm, tts=tts)
    avatar = spatius.AvatarSession()
    await avatar.start(session, room=ctx.room)

    await session.start(agent=YourAgent(), room=ctx.room)
See the LiveKit Agents Integration Server guide for the full livekit-plugins-spatius flow, interruption behavior, and API links.

​
Next steps

Server

Add livekit-plugins-spatius to your LiveKit Agents worker.

Client

Render the avatar in your Web app with @spatius/avatarkit-rtc.