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.

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:

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

JavaScript / TypeScript

iOS Demo

Use the GitHub demo as the iOS guide

Android Demo

Use the GitHub demo as the Android guide