AvatarKit Flutter SDK Reference

Installation

Add the Flutter package:

pubspec.yaml

dependencies:
  spatius_avatarkit: ^1.3.3

Then install dependencies:

flutter pub get

The package supports iOS and Android Flutter apps.

Import

import 'package:spatius_avatarkit/spatius_avatarkit.dart';

Initialize

Initialize AvatarKit once before loading avatars or creating an avatar view.

await AvatarSDK.initialize(
  appID: appId,
  configuration: Configuration(
    audioFormat: const AudioFormat(sampleRate: 16000),
    drivingServiceMode: DrivingServiceMode.direct,
    logLevel: LogLevel.all,
  ),
);

await AvatarSDK.setSessionToken(sessionToken);

Use DrivingServiceMode.direct for Direct Mode. Use DrivingServiceMode.backend when your Flutter app receives encoded audio payloads and motion data payloads from a Backend Mode. initialize fails fast when appID is missing, rather than returning silently. Get an App ID from app.spatius.ai.

Configuration

Field	What it does
`region`	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`	See AudioFormat below.
`drivingServiceMode`	`direct` or `backend`, as described above.
`logLevel`	SDK log verbosity.

AudioFormat

const AudioFormat({
  int sampleRate = 16000,
  AudioCodec inputAudioFormat = AudioCodec.pcm,
  bool opusUplinkEnabled = true,
  int opusBitrate = 48000,
})

Field	What it does
`sampleRate`	Sample rate in Hz. Supported: 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` / `yieldAudioData`. `AudioCodec.pcm` (default) for raw PCM16, `AudioCodec.opus` for Opus. Fixed for the whole session. Direct Mode only.
`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.

Audio that does not match the declared inputAudioFormat is reported through AvatarController.onError as AvatarError.invalidAudioInput.

Load an avatar

final avatar = await AvatarManager.shared.load(
  id: avatarId,
  onProgress: (progress) {
    // Update loading UI.
  },
);

Render and control playback

The Flutter view creates an AvatarController when the platform view is ready. Keep that controller and use it for lifecycle, state, and audio operations.

void onAvatarViewCreated(AvatarController controller) {
  controller.onConnectionState = (state, errorMessage) {
    // Observe Direct Mode connection state.
  };

  controller.onConversationState = (state) {
    // Observe avatar playback state.
  };

  controller.onError = (error) {
    // Log or surface AvatarError.
  };
}

Render over an Avatar Background

Download the optional 16:9 background from Spatius Studio, add it to your Flutter assets, and declare it in pubspec.yaml.

flutter:
  assets:
    - assets/avatar-background.webp

Place the background and AvatarWidget in the same Stack, with the image first.

AspectRatio(
  aspectRatio: 16 / 9,
  child: ClipRect(
    child: Stack(
      fit: StackFit.expand,
      children: [
        Image.asset(
          'assets/avatar-background.webp',
          fit: BoxFit.cover,
        ),
        AvatarWidget(
          avatar: avatar,
          onPlatformViewCreated: onAvatarViewCreated,
        ),
      ],
    ),
  ),
)

For square or portrait display windows, center this 16:9 stage inside a clipped outer widget. See Avatar Background for the shared cropping rules. For Direct Mode audio input, start the connection and send PCM chunks:

await controller.start();
controller.send(audioBytes, end: isLastChunk);

For audio source and timing guidance, see Audio. For Backend Mode input, feed encoded audio payloads and motion data payloads received from your backend:

final conversationId = await controller.yieldAudioData(audioBytes, end: isLastChunk);
controller.yieldAnimations(framesData, conversationID: conversationId);

The per-call audioFormat parameter of yieldAudioData is deprecated and ignored. The format comes from Configuration.audioFormat passed to initialize. Drop the argument if you still pass it; it will be removed in a future release. The iOS and Android SDKs have already removed theirs.

Reference Overview

Client SDKs

Server SDKs

Session Token API

Regions & Endpoints

Error Codes

AvatarKit Flutter SDK Reference

Installation

Import

Initialize

Configuration

AudioFormat

Load an avatar

Render and control playback

Render over an Avatar Background

Demos

Flutter Direct Mode demo

Flutter Backend Mode demo

​Installation

​Import

​Initialize

​Configuration

​AudioFormat

​Load an avatar

​Render and control playback

​Render over an Avatar Background

​Demos

Flutter Direct Mode demo

Flutter Backend Mode demo

Installation

Import

Initialize

Configuration

AudioFormat

Load an avatar

Render and control playback

Render over an Avatar Background

Demos