Client Lifecycle

AvatarKit follows a four-stage lifecycle: Initialize → Load → Connect → Cleanup. Each stage maps to a core component.

Overview

Stage	Component	What happens
Initialize	`AvatarSDK`	Configures app ID, environment, audio format, and driving mode. Must be called once before any other API.
Load	`AvatarManager`	Downloads and caches avatar assets. Returns an `Avatar` instance.
Render	`AvatarView`	Creates the rendering surface and its associated `AvatarController`.
Connect	`AvatarController`	Opens a WebSocket to the driving service. The avatar begins responding to audio.

Stage 1: Initialize

Call AvatarSDK.initialize() once at app startup. This sets global configuration that all subsequent operations depend on.

Web
iOS
Android

await AvatarSDK.initialize({
  appId: 'YOUR_APP_ID',
  audioFormat: { channelCount: 1, sampleRate: 16000 },
  drivingServiceMode: 'sdk',
});

AvatarSDK.initialize(
    appID: "YOUR_APP_ID",
    configuration: Configuration(
        environment: .intl,
        audioFormat: AudioFormat(sampleRate: 16000),
        drivingServiceMode: .sdk,
        logLevel: .warning
    )
)

AvatarSDK.initialize(
    context = applicationContext,
    appId = "YOUR_APP_ID",
    configuration = Configuration(
        environment = Environment.Intl,
        audioFormat = AudioFormat(16000),
        drivingServiceMode = DrivingServiceMode.SDK,
        logLevel = LogLevel.INFO
    )
)

Set AvatarSDK.sessionToken before connecting. The token authenticates your session with the driving service.

Stage 2: Load Avatar

Use AvatarManager to download and cache avatar assets. Loading is asynchronous and supports progress tracking.

Web
iOS
Android

const avatar = await AvatarManager.load('AVATAR_ID', (progress) => {
  console.log('Loading:', progress);
});

let avatar = try await AvatarManager.shared.load(id: "AVATAR_ID") { progress in
    print("Loading: \(progress)")
}

val avatar = AvatarManager.load("AVATAR_ID") { progress ->
    Log.d("Avatar", "Loading: $progress")
}

Loaded assets are cached locally. Subsequent loads for the same avatar ID skip the download. Use AvatarManager.clear(id:) or clearAll() to manage cache.

Stage 3: Render

Create an AvatarView with the loaded avatar. The view automatically creates an AvatarController you can access to manage the connection and send audio.

Web
iOS
Android

const avatarView = new AvatarView(avatar, containerElement);
const controller = avatarView.controller;

let avatarView = AvatarView(avatar: avatar)
let controller = avatarView.controller

val avatarView = AvatarView(context)
avatarView.init(avatar, lifecycleScope)
val controller = avatarView.controller

Stage 4: Connect and Interact

Call controller.start() to open the WebSocket connection. Once connected, send audio with controller.send() (SDK Mode) or controller.yield() (Host Mode).

Call controller.interrupt() to stop the current playback immediately. Call controller.close() when done.

Cleanup

Clean up resources when the avatar is no longer needed.

Web
iOS
Android

avatarView.dispose();

// AvatarView automatically releases resources when removed from the view hierarchy.
// No explicit cleanup call needed.

avatarView.dispose()

On Web and Android, always call avatarView.dispose() when the view is no longer needed. On iOS, resources are released automatically when the view is deallocated.

Getting Started

Concepts

SpatialReal Studio

Resources

Overview

Stage 1: Initialize

Stage 2: Load Avatar

Stage 3: Render

Stage 4: Connect and Interact

Cleanup

​Overview

​Stage 1: Initialize

​Stage 2: Load Avatar

​Stage 3: Render

​Stage 4: Connect and Interact

​Cleanup

Overview

Stage 1: Initialize

Stage 2: Load Avatar

Stage 3: Render

Stage 4: Connect and Interact

Cleanup