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.

​
What is Host Mode?

In Host Mode, your application manages the network connection to AvatarKit’s server-side SDK. Your server sends encoded messages to your client, and the client SDK receives and decodes them internally for synchronized playback and rendering.
Host Mode requires AvatarKit’s server-side SDK to generate the encoded messages. The data passed to yieldAudioData() and yieldFramesData() are encoded messages from the server SDK — not raw audio or animation data you create yourself.

​
When to Use

  • Custom network layer — you manage the connection between your client and AvatarKit’s server SDK yourself
  • RTC integration — messages are relayed through a real-time communication server such as LiveKit
  • Proxy architecture — your backend acts as a relay between the client and Motion Server

​
Requirements

RequirementDescription
App IDObtained from Spatius Studio
Session TokenNot required on the client side
Spatius Server SDKYour backend must integrate with the Spatius Server SDK to generate messages

​
Basic Mode vs Host Mode

AspectBasic ModeHost Mode
NetworkClient SDK connects to Motion Server directlyYour app relays messages from the Spatius Server SDK
Message DecodingHandled internallyHandled internally (same)
Session TokenRequired (client-side)Not required (client-side)
Spatius Server SDKNot neededRequired on your backend
Key Methodssend(), start(), close()yieldAudioData(), yieldFramesData()
Use CaseSimplest integrationCustom networking / RTC relay

​
Key Concepts

​
ConversationId Management

ConversationId links audio and animation messages for a single conversation session:
  1. Call yieldAudioData() — returns a conversationId
  2. Use that conversationId when calling yieldFramesData()
  3. Messages with a mismatched conversationId will be discarded
  4. Use getCurrentConversationId() to retrieve the current active session ID
Important: Always use the conversationId returned by yieldAudioData() when sending animation messages. Mismatched IDs cause messages to be silently dropped.

​
Fallback Mechanism

If you provide empty animation data (empty array or undefined), the SDK automatically enters audio-only mode for that session. Once in audio-only mode, any subsequent animation data for that session is ignored — only audio continues playing.

​
Get Started

Web Demo

GitHub demo repository

iOS Demo

GitHub demo repository

Android Demo

GitHub demo repository