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

# SDK Mode

> Server-driven avatar animation via WebSocket

## What is SDK Mode?

SDK Mode is the **default** integration mode. The SDK handles all network communication with AvatarKit servers automatically — you just send audio data, and the SDK takes care of fetching animation data, synchronizing playback, and rendering.

```mermaid theme={null}
flowchart LR
    A["🎤 Audio Input<br/>(PCM16 mono)"] -->|send| B["AvatarKit SDK"]
    B -->|WebSocket| C["AvatarKit Server"]
    C -->|Animation Data| B
    B --> D["🖥️ Avatar Rendering"]
```

## When to Use

* **Real-time audio input** — microphone or audio file playback driving an avatar
* **Simplest integration** — minimal code, SDK handles networking
* **Server-side processing** — animation data is generated by AvatarKit backend

## Requirements

| Requirement | Description |
| - | - |
| **App ID** | Obtained from [SpatialReal Studio](https://app.spatialreal.ai) |
| **Session Token** | Obtained from your backend server (max 24 hours validity) |
| **Audio Format** | PCM16, mono, configurable sample rate (default 16000 Hz) |

> [!NOTE]
>
> **Authentication Flow:**
>
> ```
> Your Client → Your Backend → AvatarKit Server → Session Token (24 hours max)
> ```
>
> The Session Token must be set before calling `start()`. See the platform-specific guides below for details.

## Platform Comparison

| Feature | Web | iOS | Android |
| - | - | - | - |
| **Package** | `@spatialwalk/avatarkit` | `AvatarKit.xcframework` / SPM | `ai.spatialwalk:avatarkit` |
| **Rendering** | WebGL / WebGPU | Metal | Vulkan |
| **UI Framework** | DOM Canvas | UIKit + SwiftUI wrapper | Android View + Compose wrapper |
| **Audio Init** | `initializeAudioContext()` in user gesture | Automatic | Automatic |
| **Build Config** | Vite plugin / Next.js wrapper required | Xcode linker flags | Gradle dependency |

## Key Concepts

### Fallback Mechanism

If the WebSocket connection fails within 15 seconds, the SDK automatically enters **audio-only fallback mode** — audio continues to play normally without animation. This ensures uninterrupted audio playback even when the server is unreachable.

### ConversationId

Every `send()` call returns a `conversationId` that identifies the current conversation round. When `end: true` is passed, it marks the end of audio input — the avatar will continue playing remaining animation until finished, then automatically return to idle (notified via `onConversationState`). Sending new audio after that starts a new round and interrupts any ongoing playback.

## Get Started

> **[Web](https://spatialwalk-6179c111.mintlify.site/guide/sdk-mode-web.md)**
>
> JavaScript / TypeScript

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

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


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