Android SDK Reference

Installation

Use the latest standard release from Maven Central. Compatibility-suffixed artifacts expose a reduced API and are not a drop-in replacement.

build.gradle.kts

dependencies {
    implementation("ai.spatius:avatarkit:<latest-version>")
}

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 Motion 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 a Boolean value that indicates whether AvatarKit supports the current device.

suspend fun isDeviceSupported(): Boolean

setRenderQuality(quality)

Update the global rendering quality tier.

fun setRenderQuality(quality: RenderQuality)

setRenderResolutionCap(enabled, maxHeight)

Cap render backing-buffer height while preserving view layout size.

fun setRenderResolutionCap(enabled: Boolean, maxHeight: Int = 1440)

deviceScore()

Measures the device’s computational performance for avatar rendering.

suspend fun deviceScore(): AvatarSDK.DeviceScore

The result contains separate cpuScore and gpuScore values.

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, useCompressedModel, onProgress)

Loads an avatar by ID.

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

Parameters:

id: The avatar identifier
useCompressedModel: Load the smaller compressed model variant
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.

AvatarController

Real-time communication controller that handles connections, audio, and motion 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

Sets or gets the playback volume (0.0 to 1.0).

fun setVolume(volume: Float)
fun getVolume(): Float

Methods

start()

Starts the avatar driving service connection.

fun start()

close()

Close connection.

fun close()

pause()

Pause Avatar playback.

fun pause()

resume()

Resume Avatar playback.

fun resume()

interrupt()

Stops playback and terminates the current conversation.

fun interrupt()

send(audioData, end)

Sends audio to the avatar driving service.For audio source and timing guidance, see Audio.

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

Parameters:

audioData: The audio data to send
end: Whether this is the end of the audio stream

Returns: A conversation ID string.

yieldAudioData(audioData, end)

Provides response audio received from your backend in Backend Mode.

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

Parameters:

audioData: The audio data
end: Whether this is the end of the audio stream

Returns: A conversation ID string.

yieldFramesData(animations, conversationId)

Provides motion data payloads received from your backend in Backend Mode.

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

Parameters:

animations: List of encoded motion data payloads
conversationId: The identifier returned by the matching yieldAudioData() call

Returns: Whether the payload completed the current conversation.

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 position and scale within the view.

var avatarTransform: Transform

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 rendering for this view.

fun pauseRendering()

resumeRendering()

Resume rendering for this view.

fun resumeRendering()

getBoundingRect()

Returns the rendered Avatar bounds when available.

fun getBoundingRect(): RectF?

dispose()

Clean up all resources. Should be called when no longer in use.

fun dispose()

Render over an Avatar Background

Download the optional 16:9 background from Spatius Studio and add it as a drawable resource. In Compose, place the background Image and AvatarView in the same Box. AvatarView renders on a transparent surface by default, so the background shows through.

@Composable
fun AvatarStage(
    avatar: Avatar,
    scope: CoroutineScope,
) {
    Box(
        modifier = Modifier
            .fillMaxWidth()
            .aspectRatio(16f / 9f)
            .clipToBounds(),
    ) {
        Image(
            painter = painterResource(R.drawable.avatar_background),
            contentDescription = null,
            contentScale = ContentScale.Crop,
            modifier = Modifier.fillMaxSize(),
        )

        AndroidView(
            factory = { context ->
                AvatarView(context).also { avatarView ->
                    avatarView.init(avatar, scope)
                }
            },
            modifier = Modifier.fillMaxSize(),
        )
    }
}

For square or portrait display windows, center this 16:9 stage inside a clipped outer container. See Avatar Background for the shared cropping rules.

Avatar

Avatar data class containing core avatar information.

class Avatar

Property	Type	Description
`id`	`String`	The avatar identifier.
`isFromCache`	`Boolean`	Whether the avatar was loaded from cache.

Configuration

SDK configuration class.

data class Configuration

Initializers

Configuration(region, audioFormat, drivingServiceMode, logLevel, renderQuality)

Creates a new configuration with the specified parameters.

data class Configuration(
    val region: String = "auto",
    val audioFormat: AudioFormat = AudioFormat(16000),
    val drivingServiceMode: DrivingServiceMode = DrivingServiceMode.DIRECT,
    val logLevel: LogLevel = LogLevel.OFF,
    val renderQuality: RenderQuality = RenderQuality.ULTRA
)

Parameters:

region: The region to connect to. Defaults to "auto": the SDK selects the closest serving region at initialization and reuses the cached choice on later launches. Pass "us-west", "ap-northeast", or "cn-beijing" to force that region. If automatic selection cannot be reached, the SDK falls back to a default region and continues initializing.
audioFormat: The audio format configuration
drivingServiceMode: The driving service mode
logLevel: The log level
renderQuality: Render quality tier

AudioFormat

Audio format configuration for AvatarKit.

class AudioFormat

Initializers

AudioFormat(sampleRate:opusBitrate:inputAudioFormat:opusUplinkEnabled:)

Creates a new audio format.

class AudioFormat(
    sampleRate: Int,
    val opusBitrate: Int = 48000,
    val inputAudioFormat: AudioCodec = AudioCodec.PCM,
    val opusUplinkEnabled: Boolean = true,
)

Parameters:

sampleRate: The audio sample rate in Hz. Supported sample rates are: 8000, 16000, 22050, 24000, 32000, 44100, 48000. Not used when inputAudioFormat is AudioCodec.OPUS: Opus always decodes at 48 kHz, so the session runs at 48000.
inputAudioFormat: The codec of the audio you feed into the SDK via send or yieldAudioData. AudioCodec.PCM (default) for raw PCM16, AudioCodec.OPUS for Opus. Fixed for the whole session; audio that does not match is reported as AvatarError.InvalidAudioInput.
opusUplinkEnabled: Whether the SDK compresses the direct mode uplink to Opus. On by default, which reduces the upload to roughly an eighth at the cost of encoding on the client. Set false to keep a raw PCM uplink. Not used in BACKEND mode, which has no uplink, or with Opus input, which is already compressed. With PCM input, sampleRate must be 8000, 16000, 24000, or 48000; on any other rate the SDK logs a warning and sends raw PCM instead of failing to initialize.
opusBitrate: Target bitrate in bits/sec for the uplink the SDK encodes. Defaults to 48000. Higher means better quality and a larger upload.

DrivingServiceMode

Driving service modes for AvatarKit.

enum class DrivingServiceMode

Case	Description
`DIRECT`	The SDK handles the Motion Server connection directly.
`BACKEND`	The host application provides response audio and motion data.
`RTC`	The avatar is driven through the companion RTC SDK, `ai.spatius:avatarkit-rtc`. It does not connect to a channel by itself; see Agora Convo AI Client.

AudioCodec

Codec of the audio the host feeds into the SDK.

enum class AudioCodec

Case	Description
`PCM`	Raw PCM16, mono. The default.
`OPUS`	Opus. Decoded to PCM locally; in Direct Mode, forwarded upstream unchanged.

RenderQuality

Render quality tiers for AvatarKit.

enum class RenderQuality

Case	Description
`STANDARD`	Lower rendering cost.
`HIGH`	Balanced quality and rendering cost.
`ULTRA`	Highest quality. Default.

FrameStarvationMode

Controls playback behavior when motion data cannot keep up with the audio clock.

enum class FrameStarvationMode

Case	Description
`AUDIO_INDEPENDENT`	Audio keeps playing while motion data catches up. Default.
`STRICT_SYNC`	Audio pauses when motion data runs out and resumes when new motion data arrives.

LogLevel

Log levels for AvatarKit.

enum class LogLevel

Case	Description
`ALL`	Log all 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.

Reference Overview

Client SDKs

Server SDKs

Session Token API

Regions & Endpoints

Error Handling

Android SDK Reference

Installation

AvatarSDK

Properties

Methods

AvatarManager

Methods

AvatarController

Properties

Methods

AvatarView

Initializers

Properties

Methods

Render over an Avatar Background

Avatar

Configuration

Initializers

AudioFormat

Initializers

DrivingServiceMode

AudioCodec

RenderQuality

FrameStarvationMode

LogLevel

ConnectionState

ConversationState

LoadProgress

​Installation

​AvatarSDK

Properties

Methods

​AvatarManager

Methods

​AvatarController

Properties

Methods

​AvatarView

Initializers

Properties

Methods

​Render over an Avatar Background

​Avatar

​Configuration

Initializers

​AudioFormat

Initializers

​DrivingServiceMode

​AudioCodec

​RenderQuality

​FrameStarvationMode

​LogLevel

​ConnectionState

​ConversationState

​LoadProgress

Installation

AvatarSDK

AvatarManager

AvatarController

AvatarView

Render over an Avatar Background

Avatar

Configuration

AudioFormat

DrivingServiceMode

AudioCodec

RenderQuality

FrameStarvationMode

LogLevel

ConnectionState

ConversationState

LoadProgress