Skip to main content

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.

A session is one running instance of an Avatar in your app. It starts when you configure AvatarKit and ends when you close the connection and release the view. The client-side path is: 
Initialize -> Load Avatar -> Mount AvatarView -> Connect -> Cleanup
The first three steps are the same across modes. The connection step depends on whether you use Basic Mode, Custom Mode, or the LiveKit Plugin.

​
Initialize

AvatarSDK.initialize() sets process-wide AvatarKit configuration:
  • App ID and environment.
  • Audio format.
  • Driving mode.
  • Logging.
Call it before loading Avatars or creating views. The Session Token can be set before or after initialization, but it must be valid before the mode-specific connection starts.
Calling initialize() again updates configuration in place. It does not automatically close existing connections, unload Avatars, or destroy views. Use AvatarSDK.cleanup() only when you need a clean process-level reset.
→ Reference: Web AvatarSDK · iOS AvatarSDK · Android AvatarSDK

​
Load Avatar

Load the Avatar before you try to display it: 
Avatar ID -> AvatarManager.load() -> Avatar
Loading downloads and caches avatar assets. It does not open a connection to Motion Server and does not consume a Session Token. See Avatars for Avatar ID, AvatarManager, and cache behavior.

​
Mount AvatarView

Mount the loaded Avatar in an AvatarView. The view creates the render surface and owns the AvatarController for that surface. After mount:
  • The Avatar can display idle motion.
  • Your app can access the AvatarController.
  • Playback can start once the connection path is online and motion data arrives.
You do not construct AvatarController directly; it belongs to the view because it needs the same render context. → Reference: Web AvatarView · iOS AvatarView · Android AvatarView

​
Connect

Connect brings the path between avatar speech audio, Motion Server, and AvatarKit online. This is the step where modes differ.
ModeConnection ownerWhat your app does
Basic ModeAvatarKit on the client connects to Motion Server.Set a valid Session Token, then start the controller.
Custom ModeYour backend connects to Motion Server through the Spatius Server SDK.Start the backend session and deliver audio and motion data to AvatarKit through your transport.
LiveKit PluginYour agent worker starts the plugin; Motion Server publishes audio and motion data into the LiveKit room.Join the room from the client and let AvatarKit render from room data.
Do not treat controller.start() as the universal connection step. It is the Basic Mode client connection path. Custom Mode and LiveKit Plugin integrations bring the Motion Server connection online outside the client.
→ Reference: Web AvatarController.start · iOS AvatarController.start · Android AvatarController.start

​
Cleanup

Tear down in the reverse direction:
  1. Close the active connection for your mode.
  2. Destroy or unmount the AvatarView.
  3. Release cached Avatar assets only if nothing else is using them.
  4. Call AvatarSDK.cleanup() only for a full process-level reset.
On Android, tear the view down explicitly when the host activity or fragment is destroyed. Skipping this can leak GPU resources.
→ Reference: Web AvatarController.close · iOS AvatarController.close · Android AvatarController.close

​
What can go wrong

SymptomLikely cause
Avatar never appearsAvatar was not loaded, the view was not mounted, or rendering resources were released too early.
Connection fails immediatelyMissing, expired, or invalid Session Token in Basic Mode; server-side connection issue in Custom Mode or LiveKit Plugin.
Audio plays but avatar does not moveMotion data is not reaching AvatarKit, or the wrong transport path is online.
Resources leak after navigationView cleanup was skipped, especially on Android.

​
Go next

  • Avatars if the session is blocked before the view mounts.
  • Audio and Motion Data if the session is online and you need to deliver avatar speech audio and motion data.
  • State & Events if connection or playback state is failing at runtime.