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
| Requirement | Description |
|---|
| App ID | Obtained from Developer Platform |
| Session Token | Not required on the client side |
| AvatarKit Server SDK | Your backend must integrate with AvatarKit’s server SDK to generate messages |
SDK Mode vs Host Mode
| Aspect | SDK Mode | Host Mode |
|---|
| Network | Client SDK connects to AvatarKit server directly | Your app relays messages from AvatarKit Server SDK |
| Message Decoding | Handled internally | Handled internally (same) |
| Session Token | Required (client-side) | Not required (client-side) |
| Server SDK | Not needed | Required on your backend |
| Key Methods | send(), start(), close() | yieldAudioData(), yieldFramesData() |
| Use Case | Simplest integration | Custom networking / RTC relay |
Key Concepts
ConversationId Management
ConversationId links audio and animation messages for a single conversation session:
- Call
yieldAudioData() — returns a conversationId
- Use that
conversationId when calling yieldFramesData()
- Messages with a mismatched conversationId will be discarded
- 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
