> ## Documentation Index
> Fetch the complete documentation index at: https://spatialwalk-6179c111.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Host Mode

> Self-managed networking with AvatarKit Server SDK

## 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.

```mermaid theme={null}
flowchart LR
    A["🖥️ AvatarKit<br/>Server SDK"] -->|Encoded Messages| B["Your App<br/>(Network Layer)"]
    B -->|yieldAudioData| C["AvatarKit<br/>Client SDK"]
    B -->|yieldFramesData| C
    C -->|Decode & Render| D["🖥️ Avatar Rendering"]
```

> [!WARNING]
>
> 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 [SpatialReal Studio](https://app.spatialreal.ai) |
| **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:

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

> [!WARNING]
>
> **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](https://github.com/spatialwalk/avatarkit-voice-agent-demo)**
>
> GitHub demo repository

> **[iOS Demo](https://github.com/spatialwalk/avatarkit-voice-agent-demo)**
>
> GitHub demo repository

> **[Android Demo](https://github.com/spatialwalk/avatarkit-voice-agent-demo)**
>
> GitHub demo repository


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.