> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spatius.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Android SDK Reference

> Browse the Android AvatarKit SDK API reference.

## Installation

Use the latest standard release from [Maven Central](https://central.sonatype.com/artifact/ai.spatius/avatarkit). Compatibility-suffixed artifacts expose a reduced API and are not a drop-in replacement.

```kotlin title="build.gradle.kts" theme={null}
dependencies {
    implementation("ai.spatius:avatarkit:<latest-version>")
}
```

### AvatarSDK

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

```kotlin theme={null}
object AvatarSDK
```

##### Properties

<Accordion title="sessionToken">
  The session token used to authenticate avatars with Motion Server.

  ```kotlin theme={null}
  var sessionToken: String
  ```
</Accordion>

<Accordion title="userId">
  The user identifier.

  ```kotlin theme={null}
  var userId: String
  ```
</Accordion>

<Accordion title="version">
  Returns the version of AvatarKit.

  ```kotlin theme={null}
  val version: String
  ```
</Accordion>

##### Methods

<Accordion title="initialize(context, appId, configuration)">
  Initialize AvatarKit.

  ```kotlin theme={null}
  fun initialize(
      context: Context,
      appId: String,
      configuration: Configuration
  )
  ```

  **Parameters:**

  * `context`: Application context
  * `appId`: Your application identifier
  * `configuration`: The configuration for AvatarKit
</Accordion>

<Accordion title="isDeviceSupported()">
  Returns a Boolean value that indicates whether AvatarKit supports the current device.

  ```kotlin theme={null}
  suspend fun isDeviceSupported(): Boolean
  ```
</Accordion>

<Accordion title="setRenderQuality(quality)">
  Update the global rendering quality tier.

  ```kotlin theme={null}
  fun setRenderQuality(quality: RenderQuality)
  ```
</Accordion>

<Accordion title="setRenderResolutionCap(enabled, maxHeight)">
  Cap render backing-buffer height while preserving view layout size.

  ```kotlin theme={null}
  fun setRenderResolutionCap(enabled: Boolean, maxHeight: Int = 1440)
  ```
</Accordion>

<Accordion title="deviceScore()">
  Measures the device's computational performance for avatar rendering.

  ```kotlin theme={null}
  suspend fun deviceScore(): AvatarSDK.DeviceScore
  ```

  The result contains separate `cpuScore` and `gpuScore` values.
</Accordion>

### AvatarManager

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

```kotlin theme={null}
object AvatarManager
```

##### Methods

<Accordion title="initialize(context)">
  Initialize AvatarManager. Must be called before use.

  ```kotlin theme={null}
  fun initialize(context: Context)
  ```

  **Parameters:**

  * `context`: Application context
</Accordion>

<Accordion title="load(id, useCompressedModel, onProgress)">
  Loads an avatar by ID.

  ```kotlin theme={null}
  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.
</Accordion>

<Accordion title="clear(id)">
  Clears cached data for a specific avatar.

  ```kotlin theme={null}
  suspend fun clear(id: String)
  ```

  **Parameters:**

  * `id`: The avatar identifier to clear
</Accordion>

<Accordion title="clearAll()">
  Clears all cached avatar data.

  ```kotlin theme={null}
  suspend fun clearAll()
  ```
</Accordion>

<Accordion title="getCacheSize(id)">
  Gets the cache size for a specific avatar.

  ```kotlin theme={null}
  suspend fun getCacheSize(id: String): Long
  ```

  **Parameters:**

  * `id`: The avatar identifier

  **Returns:** The cache size in bytes.
</Accordion>

<Accordion title="getAllCacheSize()">
  Gets the total cache size for all avatars.

  ```kotlin theme={null}
  suspend fun getAllCacheSize(): Long
  ```

  **Returns:** The total cache size in bytes.
</Accordion>

### AvatarController

Real-time communication controller that handles connections, audio, and motion data.

```kotlin theme={null}
class AvatarController
```

##### Properties

<Accordion title="onConnectionState">
  Callback for connection state changes.

  ```kotlin theme={null}
  var onConnectionState: ((ConnectionState) -> Unit)?
  ```
</Accordion>

<Accordion title="onConversationState">
  Callback for conversation state changes.

  ```kotlin theme={null}
  var onConversationState: ((ConversationState) -> Unit)?
  ```
</Accordion>

<Accordion title="onError">
  Callback for error events.

  ```kotlin theme={null}
  var onError: ((AvatarError) -> Unit)?
  ```

  | Case | Description |
  | - | - |
  | `AvatarIDUnrecognized` | The avatar ID is not recognized. |
  | `SessionTokenInvalid` | The session token is invalid. |
  | `SessionTokenExpired` | The session token has expired. |
  | `FailedToFetchAvatarMetadata` | Failed to fetch avatar metadata. |
  | `InvalidAvatarMetadata` | The avatar metadata is invalid. |
  | `IncompatibleAvatarAsset` | The avatar asset format or version is incompatible. |
  | `FailedToDownloadAvatarAssets` | Failed to download avatar assets. |
  | `RenderNotSupported` | Rendering is not supported on this device (Vulkan is unavailable). Deterministic — tell the user rather than retry. |
  | `RenderInitFailed` | The renderer failed to initialize for another reason. |
  | `InsufficientBalance` | Insufficient balance. |
  | `SessionTimeout` | The session timed out. |
  | `ConcurrentLimitExceeded` | Concurrent connection limit exceeded. |
  | `InvalidAnimationData` | The animation data is invalid. |
  | `InvalidAudioInput` | The audio does not match `audioFormat.inputAudioFormat`. |
  | `ServerError` | The driving service returned an error. |
</Accordion>

<Accordion title="audioFormat">
  The audio format currently in effect for this view. Read-only; change it with `setAudioFormat()`. With Opus input, `sampleRate` reads 48000.

  ```kotlin theme={null}
  var audioFormat: AudioFormat
      private set
  ```
</Accordion>

<Accordion title="volume">
  Sets or gets the playback volume (0.0 to 1.0).

  ```kotlin theme={null}
  fun setVolume(volume: Float)
  fun getVolume(): Float
  ```
</Accordion>

##### Methods

<Accordion title="start()">
  Starts the avatar driving service connection.

  ```kotlin theme={null}
  fun start()
  ```
</Accordion>

<Accordion title="close()">
  Close connection.

  ```kotlin theme={null}
  fun close()
  ```
</Accordion>

<Accordion title="pause()">
  Pause Avatar playback.

  ```kotlin theme={null}
  fun pause()
  ```
</Accordion>

<Accordion title="resume()">
  Resume Avatar playback.

  ```kotlin theme={null}
  fun resume()
  ```
</Accordion>

<Accordion title="interrupt()">
  Stops playback and terminates the current conversation.

  ```kotlin theme={null}
  fun interrupt()
  ```
</Accordion>

<Accordion title="send(audioData, end)">
  Sends audio to the avatar driving service.

  For audio source and timing guidance, see [Audio](/concepts/audio).

  ```kotlin theme={null}
  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.
</Accordion>

<Accordion title="yieldAudioData(audioData, end)">
  Provides response audio received from your backend in Backend Mode.

  ```kotlin theme={null}
  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.
</Accordion>

<Accordion title="yieldFramesData(animations, conversationId)">
  Provides motion data payloads received from your backend in Backend Mode.

  ```kotlin theme={null}
  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.
</Accordion>

<Accordion title="setAudioFormat(sampleRate, opusBitrate, inputAudioFormat, opusUplinkEnabled)">
  Changes the audio format of this view without reinitializing the SDK. Only the parameters you pass change; `null` keeps the current value.

  ```kotlin theme={null}
  fun setAudioFormat(
      sampleRate: Int? = null,
      opusBitrate: Int? = null,
      inputAudioFormat: AudioCodec? = null,
      opusUplinkEnabled: Boolean? = null,
  )
  ```

  **Parameters:**

  * `sampleRate`: The new sample rate in Hz. Accepted: 8000, 16000, 22050, 24000, 32000, 44100, 48000.
  * `opusBitrate`: The new uplink Opus bitrate in bits/sec.
  * `inputAudioFormat`: The new codec of the audio you feed into the SDK.
  * `opusUplinkEnabled`: Whether the SDK compresses the Direct Mode uplink to Opus.

  Any change interrupts the current playback and, in Direct Mode, disconnects. Call `start()` to reconnect; audio you feed after the call is interpreted in the new format. The SDK recreates the `AudioTrack` for the next conversation automatically; no audio-side work is needed. Passing values identical to the current format does nothing.

  * Switching `inputAudioFormat` to `AudioCodec.OPUS` sets the sample rate to 48000. Switching back to `AudioCodec.PCM` keeps the current rate unless you pass `sampleRate` in the same call.
  * With PCM input at a rate the Opus uplink does not support (anything other than 8000, 16000, 24000, or 48000), the SDK sends raw PCM. Changing back to a supported rate restores the Opus uplink you requested.
  * An unsupported `sampleRate`, or a `sampleRate` passed with Opus input, logs an error and leaves the format unchanged. It is not reported through `onError`.
</Accordion>

### AvatarView

3D rendering view that automatically creates and manages AvatarController.

```kotlin theme={null}
class AvatarView : FrameLayout
```

##### Initializers

<Accordion title="constructor(context)">
  Creates a new avatar view.

  ```kotlin theme={null}
  constructor(context: Context)
  ```
</Accordion>

##### Properties

<Accordion title="controller">
  The controller for the avatar.

  ```kotlin theme={null}
  val controller: AvatarController
  ```
</Accordion>

<Accordion title="avatarTransform">
  Transform for Avatar position and scale within the view.

  ```kotlin theme={null}
  var avatarTransform: Transform
  ```
</Accordion>

##### Methods

<Accordion title="init(avatar, scope, audioFormat)">
  Initialize view with avatar.

  ```kotlin theme={null}
  fun init(
      avatar: Avatar,
      scope: CoroutineScope,
      audioFormat: AudioFormat = AudioFormat(16000)
  )
  ```

  **Parameters:**

  * `avatar`: The avatar to display
  * `scope`: Coroutine scope, usually obtained via `activity.lifecycleScope`
  * `audioFormat`: The audio format for this view. Defaults to 16 kHz PCM. Each view has its own format, so two views can run different sample rates. Change it later with `controller.setAudioFormat()`.
</Accordion>

<Accordion title="pauseRendering()">
  Pause rendering for this view.

  ```kotlin theme={null}
  fun pauseRendering()
  ```
</Accordion>

<Accordion title="resumeRendering()">
  Resume rendering for this view.

  ```kotlin theme={null}
  fun resumeRendering()
  ```
</Accordion>

<Accordion title="getBoundingRect()">
  Returns the rendered Avatar bounds when available.

  ```kotlin theme={null}
  fun getBoundingRect(): RectF?
  ```
</Accordion>

<Accordion title="dispose()">
  Clean up all resources. Should be called when no longer in use.

  ```kotlin theme={null}
  fun dispose()
  ```
</Accordion>

#### 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.

```kotlin theme={null}
@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](/concepts/avatar-background) for the shared cropping rules.

***

### Avatar

Avatar data class containing core avatar information.

```kotlin theme={null}
class Avatar
```

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

### Configuration

SDK configuration class.

```kotlin theme={null}
data class Configuration
```

##### Initializers

<Accordion title="Configuration(region, drivingServiceMode, logLevel, renderQuality)">
  Creates a new configuration with the specified parameters.

  ```kotlin theme={null}
  data class Configuration(
      val region: String = "auto",
      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.
  * `drivingServiceMode`: The driving service mode
  * `logLevel`: The log level
  * `renderQuality`: Render quality tier

  The audio format is set per view; see [`AvatarView.init`](#avatarview) and [AudioFormat](#audioformat).
</Accordion>

### AudioFormat

Audio format of an `AvatarView`. Pass it to `AvatarView.init(...)` and change it later with `controller.setAudioFormat()`.

```kotlin theme={null}
class AudioFormat
```

##### Initializers

<Accordion title="AudioFormat(sampleRate:opusBitrate:inputAudioFormat:opusUplinkEnabled:)">
  Creates a new audio format.

  ```kotlin theme={null}
  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 view 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. Applies to all audio fed to the view until you change it with `controller.setAudioFormat()`; 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.
</Accordion>

### DrivingServiceMode

Driving service modes for AvatarKit.

```kotlin theme={null}
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](/agora-convoai/client). |

### AudioCodec

Codec of the audio the host feeds into the SDK.

```kotlin theme={null}
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.

```kotlin theme={null}
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.

```kotlin theme={null}
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.

```kotlin theme={null}
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.

```kotlin theme={null}
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.

```kotlin theme={null}
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.

```kotlin theme={null}
sealed class LoadProgress
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.