Skip to main content

​
What is Backend Mode with your own transport?

This is the Backend Mode Integration shape where your application owns the network connection between the Server SDK and the client. Your server sends encoded audio payloads and motion data payloads to your client, and the client SDK receives and decodes them internally for synchronized playback and rendering. The Reference tab covers the exact enum and method names for each platform.
Backend Mode with your own transport requires the Server SDK to provide the encoded payloads. The data passed to yieldAudioData() and yieldFramesData() are encoded audio payloads and motion data payloads 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.
Server SDKYour backend must integrate with the Server SDK to provide payloads for clients.

​
Direct Mode vs Backend Mode (own transport)

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

​
Key Concepts

​
ConversationId Management

ConversationId links encoded audio payloads and motion data payloads 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 motion data payloads. Mismatched IDs cause payloads 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.