Skip to main content

​
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 (LiveKit, Agora, etc.)
  • Proxy architecture — your backend acts as a relay between the client and AvatarKit server

​
Requirements

RequirementDescription
App IDObtained from SpatialReal Studio
Session TokenNot required on the client side
AvatarKit Server SDKYour backend must integrate with AvatarKit’s server SDK to generate messages

​
SDK Mode vs Host Mode

AspectSDK ModeHost Mode
NetworkClient SDK connects to AvatarKit server directlyYour app relays messages from AvatarKit Server SDK
Message DecodingHandled internallyHandled internally (same)
Session TokenRequired (client-side)Not required (client-side)
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