Common Issues
Supported Audio Format
Supported Audio Format
Spatius supports mono 16-bit PCM audio at multiple sample rates:
8000, 16000, 22050, 24000, 32000, 44100, and 48000 Hz.See Audio for configuration details.Avatar Playback Fallback Strategy
Avatar Playback Fallback Strategy
If the motion data is abnormal after passing in audio, the fallback playback strategy will be triggered:
- Audio plays normally
- Avatar remains in idle breathing state, or motion playback stops
Session token expired or invalid
Session token expired or invalid
Direct Mode only. Session Tokens have a limited lifetime. If you receive
sessionTokenExpired or sessionTokenInvalid on the Motion Server WebSocket, request a fresh Session Token from your backend and call AvatarSDK.setSessionToken() before reconnecting via controller.start(). RTC / Platform Integration / Backend Mode clients never see this error — they don’t open that WebSocket and don’t need a Session Token.Avatar assets fail to download
Avatar assets fail to download
Check your network connectivity and ensure the avatar ID is correct. If the issue persists, clear the local cache with
AvatarManager.clearAll() and retry. On iOS, Android, or Flutter, verify that your app has network permissions.Platform-Specific
Web: WASM module fails to load
Web: WASM module fails to load
AvatarKit Web uses WebAssembly for rendering. Your build tool must be configured to handle
.wasm files:- Vite: Use the AvatarKit Vite plugin.
- Next.js: Use the AvatarKit Next.js wrapper component.
Web: WebGL not supported
Web: WebGL not supported
AvatarKit requires WebGL 2.0. Ensure the browser supports it and hardware acceleration is enabled. Most modern browsers support WebGL 2.0 by default.
iOS: Metal rendering requirements
iOS: Metal rendering requirements
AvatarKit iOS uses Metal for GPU rendering. Metal is available on all devices running iOS 16+. The simulator does not support Metal — test on a physical device.
Android: Vulkan rendering requirements
Android: Vulkan rendering requirements
AvatarKit Android uses Vulkan for GPU rendering. Ensure the target device supports Vulkan 1.1+ (API 24+). Most devices from 2018 onwards support Vulkan.
LiveKit RTC client: version compatibility
LiveKit RTC client: version compatibility
The AvatarKit RTC client path requires
livekit-client at exactly version 2.16.1. Other versions may cause connection or audio routing issues.Performance Issues
Avatar Rendering Resolution Support
Avatar Rendering Resolution Support
Our avatar models don’t use the concept of resolution.We can reconstruct 4K resolution 3D avatar models, but this depends on the model’s point count.Fewer points result in less detail restoration, but all models can be rendered to the corresponding resolution on the client side.Metrics such as PSNR and LPIPS are typically used to measure the quality of detail restoration.
Can the SDK dynamically switch between different models based on device performance?
Can the SDK dynamically switch between different models based on device performance?
Not currently supported. Developers need to implement their own strategy for switching between different models based on device performance.