Documentation Index
Fetch the complete documentation index at: https://docs.spatius.ai/llms.txt
Use this file to discover all available pages before exploring further.
What is Direct Mode Integration?
Direct Mode Integration maps toDrivingServiceMode.sdk in SDK code. AvatarKit on the client establishes a WebSocket connection to Motion Server, sends avatar speech audio, receives motion data, and renders the avatar locally.
When to use
- You already have avatar speech audio — your own TTS, a TTS provider, or prerecorded audio.
- Smallest backend — your server only needs to mint Session Tokens; ASR, LLM, and TTS run wherever you already host them.
- Cross-platform — Web, iOS, Android, and Flutter clients use the same Direct Mode model.
Requirements
| Requirement | Description |
|---|---|
| App ID | Obtained from Spatius Studio. |
| Session Token | Issued from your backend (max 24 h validity). See Credentials. |
| Audio format | PCM16, mono, configurable sample rate (default 16 kHz). |
Authentication flow:The Session Token must be set before
start(). See the Session token API for backend implementation.Platform comparison
| Feature | Web | iOS | Android | Flutter |
|---|---|---|---|---|
| Package | @spatius/avatarkit | AvatarKit.xcframework / SPM | ai.spatius:avatarkit | spatius |
| Rendering | WebGL / WebGPU | Metal | Vulkan | Native iOS / Android rendering through Flutter |
| UI Framework | DOM Canvas | UIKit + SwiftUI wrapper | Android View + Compose wrapper | Flutter widget |
| Audio init | initializeAudioContext() in user gesture | Automatic | Automatic | Automatic |
| Build config | Vite plugin / Next.js wrapper required | Xcode linker flags | Gradle dependency | Flutter pub package + platform build setup |
Key concepts
Fallback mechanism
If the WebSocket connection fails within 15 seconds, the SDK enters audio-only fallback — audio continues to play without animation. Your audio playback remains uninterrupted even when Motion 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 continues playing remaining animation until finished, then automatically returns to idle (notified via onConversationState). Sending new audio after that starts a new round and interrupts any ongoing playback.
Next steps
Pick the platform you want to integrate on:Web
Direct Mode integration for the browser with
@spatius/avatarkit.iOS
Direct Mode integration for iOS with
AvatarKit.xcframework.Android
Direct Mode integration for Android with
ai.spatius:avatarkit.Flutter
Direct Mode integration for Flutter with the
spatius package.