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.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 |
| Session Token | Obtained from your backend server (max 24 hours validity) |
| Audio Format | PCM16, mono, configurable sample rate (default 16000 Hz) |
Authentication Flow: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
Everysend() 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
JavaScript / TypeScript
iOS Demo
Use the GitHub demo as the iOS guide
Android Demo
Use the GitHub demo as the Android guide