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.

​
What is Backend Mode with your own transport?

This is the Backend Mode Integration shape where your application owns the network connection between AvatarKit’s server-side SDK and the client. Your server sends encoded messages to your client, and the client SDK receives and decodes them internally for synchronized playback and rendering. SDK Reference pages cover the exact enum and method names for each platform.
Backend Mode with your own transport requires AvatarKit’s server-side SDK to generate the encoded messages. The data passed to yieldAudioData() and yieldFramesData() are encoded messages from the Server SDK — not raw audio or motion data you create yourself.

​
When to use

  • Custom network layer — you manage the connection between your client and AvatarKit’s server SDK yourself.
  • Third-party realtime transport — messages are relayed through a provider such as LiveKit. (See Backend Mode with LiveKit for that variant.)
  • Proxy architecture — your backend acts as a relay between the client and Motion Server.

​
Requirements

RequirementDescription
App IDObtained from Spatius Studio.
Session TokenNot required on the client side.
Spatius Server SDKYour backend must integrate with the Spatius Server SDK to generate messages.

​
Direct Mode vs Backend Mode (own transport)

AspectDirect ModeBackend Mode (own transport)
NetworkClient SDK connects to Motion Server directly.Your app relays messages from the Spatius Server SDK.
Message decodingHandled internally.Handled internally (same).
Session TokenRequired (client-side).Not required (client-side).
Spatius Server SDKNot needed.Required on your backend.
Key methodssend(), start(), close()yieldAudioData(), yieldFramesData()

​
Key Concepts

​
ConversationId Management

ConversationId links audio and encoded motion messages for a single conversation session:
  1. Call yieldAudioData() — returns a conversationId.
  2. Use that conversationId when calling yieldFramesData().
  3. Messages with a mismatched conversationId will be discarded.
Important: Always use the conversationId returned by yieldAudioData() when sending encoded motion messages. Mismatched IDs cause messages to be silently dropped.

​
Fallback Mechanism

If you provide empty motion data (empty array or undefined), the SDK automatically enters audio-only mode for that session. Once in audio-only mode, any subsequent motion data for that session is ignored — only audio continues playing.

​
Next steps

Browse all demos

Run the Backend Mode reference implementations for Web, iOS, Android, and Flutter.

Backend Mode with LiveKit

Reuse a LiveKit room as the downstream transport instead of your own WebSocket.