Skip to main content

​
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
The session token used to authenticate avatars with the AvatarKit Server.
var sessionToken: String
The user identifier.
var userId: String
Returns the version of AvatarKit.
val version: String
Methods
Initialize AvatarKit.
fun initialize(
    context: Context,
    appId: String,
    configuration: Configuration
)
Parameters:
  • context: Application context
  • appId: Your application identifier
  • configuration: The configuration for AvatarKit
Returns whether the current device meets the minimum requirements for avatar rendering.
suspend fun isDeviceSupported(): Boolean
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 AvatarManager. Must be called before use.
fun initialize(context: Context)
Parameters:
  • context: Application context
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.
Clears cached data for a specific avatar.
suspend fun clear(id: String)
Parameters:
  • id: The avatar identifier to clear
Clears all cached avatar data.
suspend fun clearAll()
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.
Gets the total cache size for all avatars.
suspend fun getAllCacheSize(): Long
Returns: The total cache size in bytes.
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
Callback for connection state changes.
var onConnectionState: ((ConnectionState) -> Unit)?
Callback for conversation state changes.
var onConversationState: ((ConversationState) -> Unit)?
Callback for error events.
var onError: ((AvatarError) -> Unit)?
The volume of playback (0.0 to 1.0).
var volume: Float
Methods
Starts the avatar driving service connection.
fun start()
Close connection.
fun close()
Stops playback and terminates the current conversation.
fun interrupt()
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.
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.
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
Creates a new avatar view.
constructor(context: Context)
Properties
The controller for the avatar.
val controller: AvatarController?
Transform for avatar content position and scale within the view.
var avatarTransform: Transform
Callback when the first frame is rendered.
var onFirstRendering: (() -> Unit)?
Methods
Initialize view with avatar.
fun init(avatar: Avatar, scope: CoroutineScope)
Parameters:
  • avatar: The avatar to display
  • scope: Coroutine scope, usually obtained via activity.lifecycleScope
Pause avatar rendering.
fun pauseRendering()
Resume avatar rendering.
fun resumeRendering()
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
PropertyTypeDescription
idStringThe avatar identifier.
pointCountIntThe avatar point count.

​
Configuration

SDK configuration class. 
data class Configuration
Initializers
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
CaseDescription
intlInternational environment.
cnChina environment.
testTest environment.

​
AudioFormat

Audio format configuration for AvatarKit. 
class AudioFormat
Initializers
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
CaseDescription
SDKThe SDK handles driving service internally.
HOSTThe host application handles driving service.

​
LogLevel

Log levels for AvatarKit. 
enum class LogLevel
CaseDescription
ALLLog all messages.
VERBOSELog verbose messages.
DEBUGLog debug messages.
INFOLog info messages.
WARNINGLog warning messages.
ERRORLog error messages.
OFFDisable logging.

​
ConnectionState

Connection state sealed class. 
sealed class ConnectionState
CaseDescription
ConnectingThe connection is being established.
ConnectedThe connection is active.
DisconnectedThe connection has been closed.
Failed(Exception)The connection failed with an exception.

​
ConversationState

Avatar conversation state enum. 
enum class ConversationState
CaseDescription
IdleIdle state, showing breathing animation.
PlayingThe avatar is playing audio/animation.
PausedPlayback is paused.

​
LoadProgress

Load progress sealed class. 
sealed class LoadProgress
CaseDescription
Downloading(Float)Downloading with progress (0-1).
CompletedLoading completed.
Failed(Throwable)Loading failed with error.