API Reference

Installation

build.gradle.kts

dependencies {
    implementation("ai.spatialwalk:avatarkit:1.0.0-beta49")
}

AvatarSDK

The core management class of the SDK, responsible for initialization and global configuration.

object AvatarSDK

Properties

sessionToken

The session token used to authenticate avatars with the AvatarKit Server.

var sessionToken: String

userId

The user identifier.

var userId: String

version

Returns the version of AvatarKit.

val version: String

Methods

initialize(context, appId, configuration)

Initialize AvatarKit.

fun initialize(
    context: Context,
    appId: String,
    configuration: Configuration
)

Parameters:

context: Application context
appId: Your application identifier
configuration: The configuration for AvatarKit

isDeviceSupported()

Returns whether the current device meets the minimum requirements for avatar rendering.

suspend fun isDeviceSupported(): Boolean

deviceScore()

Measures the device’s computational performance for avatar rendering.

suspend fun deviceScore(): DeviceScore

Returns: A DeviceScore containing cpuScore and gpuScore.

AvatarManager

Avatar resource manager, responsible for downloading, caching, and loading avatar data.

object AvatarManager

Methods

initialize(context)

Initialize AvatarManager. Must be called before use.

fun initialize(context: Context)

Parameters:

context: Application context

load(id, onProgress)

Loads an avatar by ID.

suspend fun load(
    id: String,
    onProgress: ((LoadProgress) -> Unit)? = null
): Avatar

Parameters:

id: The avatar identifier
onProgress: Optional progress callback

Returns: The loaded Avatar instance.

clear(id)

Clears cached data for a specific avatar.

suspend fun clear(id: String)

Parameters:

id: The avatar identifier to clear

clearAll()

Clears all cached avatar data.

suspend fun clearAll()

getCacheSize(id)

Gets the cache size for a specific avatar.

suspend fun getCacheSize(id: String): Long

Parameters:

id: The avatar identifier

Returns: The cache size in bytes.

getAllCacheSize()

Gets the total cache size for all avatars.

suspend fun getAllCacheSize(): Long

Returns: The total cache size in bytes.

getCacheStats()

Get cache statistics.

suspend fun getCacheStats(): CacheStats

Returns: A CacheStats object containing total entries, total size, and max size.

AvatarController

Real-time communication controller that handles WebSocket connections and audio/video data.

class AvatarController

Properties

onConnectionState

Callback for connection state changes.

var onConnectionState: ((ConnectionState) -> Unit)?

onConversationState

Callback for conversation state changes.

var onConversationState: ((ConversationState) -> Unit)?

onError

Callback for error events.

var onError: ((AvatarError) -> Unit)?

volume

The volume of playback (0.0 to 1.0).

var volume: Float

Methods

start()

Starts the avatar driving service connection.

fun start()

close()

Close connection.

fun close()

interrupt()

Stops playback and terminates the current conversation.

fun interrupt()

send(audioData, end)

Sends audio to the avatar driving service.

suspend fun send(audioData: ByteArray, end: Boolean = false): String

Parameters:

audioData: PCM16 (S16LE) mono audio data. Byte length must be even (2 bytes per sample).
end: Whether this is the end of the audio stream

Returns: A conversation ID string.

Audio data byte length must be even (2 bytes per sample). Odd-length data will cause a server-side validation error and WebSocket disconnect.

yield(audioData, end, audioFormat)

Yields audio from the host.

suspend fun yield(
    audioData: ByteArray,
    end: Boolean = false,
    audioFormat: AudioFormat? = null
): String

Parameters:

audioData: The audio data
end: Whether this is the end of the audio stream
audioFormat: The audio format (optional)

Returns: A conversation ID string.

yield(animations, conversationId)

Yields animations from the host. Returns whether the server has sent all animation data for this conversation.

fun yield(animations: List<ByteArray>, conversationId: String): Boolean

Parameters:

animations: List of animation data
conversationId: The request ID returned from yield audio

Returns: true if the server has sent all animation data (end signal received), false otherwise.

AvatarView

3D rendering view that automatically creates and manages AvatarController.

class AvatarView : FrameLayout

Initializers

constructor(context)

Creates a new avatar view.

constructor(context: Context)

Properties

controller

The controller for the avatar.

val controller: AvatarController?

avatarTransform

Transform for avatar content position and scale within the view.

var avatarTransform: Transform

onFirstRendering

Callback when the first frame is rendered.

var onFirstRendering: (() -> Unit)?

Methods

init(avatar, scope)

Initialize view with avatar.

fun init(avatar: Avatar, scope: CoroutineScope)

Parameters:

avatar: The avatar to display
scope: Coroutine scope, usually obtained via activity.lifecycleScope

pauseRendering()

Pause avatar rendering.

fun pauseRendering()

resumeRendering()

Resume avatar rendering.

fun resumeRendering()

dispose()

Release all resources. Call when the avatar view is no longer needed (e.g., in onDestroy).

fun dispose()

Avatar

Avatar data class containing core avatar information.

class Avatar

Property	Type	Description
`id`	`String`	The avatar identifier.
`pointCount`	`Int`	The avatar point count.

Configuration

SDK configuration class.

data class Configuration

Initializers

Configuration(environment, audioFormat, drivingServiceMode, logLevel)

Creates a new configuration with the specified parameters.

data class Configuration(
    val environment: Environment,
    val audioFormat: AudioFormat = AudioFormat(16000),
    val drivingServiceMode: DrivingServiceMode = DrivingServiceMode.SDK,
    val logLevel: LogLevel = LogLevel.INFO
)

Parameters:

environment: The environment to use
audioFormat: The audio format configuration
drivingServiceMode: The driving service mode
logLevel: The log level

Environment

Environment enum.

enum class Environment

Case	Description
`intl`	International environment.
`cn`	China environment.
`test`	Test environment.

AudioFormat

Audio format configuration for AvatarKit.

class AudioFormat

Initializers

AudioFormat(sampleRate:)

Creates a new audio format with the specified sample rate.

class AudioFormat(val sampleRate: Int)

Parameters:

sampleRate: The audio sample rate in Hz. Supported sample rates are: 8000, 16000, 22050, 24000, 32000, 44100, 48000.

DrivingServiceMode

Driving service modes for AvatarKit.

enum class DrivingServiceMode

Case	Description
`SDK`	The SDK handles driving service internally.
`HOST`	The host application handles driving service.

LogLevel

Log levels for AvatarKit.

enum class LogLevel

Case	Description
`ALL`	Log all messages.
`VERBOSE`	Log verbose messages.
`DEBUG`	Log debug messages.
`INFO`	Log info messages.
`WARNING`	Log warning messages.
`ERROR`	Log error messages.
`OFF`	Disable logging.

ConnectionState

Connection state sealed class.

sealed class ConnectionState

Case	Description
`Connecting`	The connection is being established.
`Connected`	The connection is active.
`Disconnected`	The connection has been closed.
`Failed(Exception)`	The connection failed with an exception.

ConversationState

Avatar conversation state enum.

enum class ConversationState

Case	Description
`Idle`	Idle state, showing breathing animation.
`Playing`	The avatar is playing audio/animation.
`Paused`	Playback is paused.

LoadProgress

Load progress sealed class.

sealed class LoadProgress

Case	Description
`Downloading(Float)`	Downloading with progress (0-1).
`Completed`	Loading completed.
`Failed(Throwable)`	Loading failed with error.

Client SDK

Server SDK

Installation

AvatarSDK

Properties

Methods

AvatarManager

Methods

AvatarController

Properties

Methods

AvatarView

Initializers

Properties

Methods

Avatar

Configuration

Initializers

Environment

AudioFormat

Initializers

DrivingServiceMode

LogLevel

ConnectionState

ConversationState

LoadProgress

​Installation

​AvatarSDK

Properties

Methods

​AvatarManager

Methods

​AvatarController

Properties

Methods

​AvatarView

Initializers

Properties

Methods

​Avatar

​Configuration

Initializers

​Environment

​AudioFormat

Initializers

​DrivingServiceMode

​LogLevel

​ConnectionState

​ConversationState

​LoadProgress

Installation

AvatarSDK

AvatarManager

AvatarController

AvatarView

Avatar

Configuration

Environment

AudioFormat

DrivingServiceMode

LogLevel

ConnectionState

ConversationState

LoadProgress