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

# AvatarKit Flutter SDK Reference

> AvatarKit Flutter SDK reference for Direct Mode, Backend Mode client feed, state callbacks, and demos.

## Installation

Add the Flutter package:

```yaml title="pubspec.yaml" theme={null}
dependencies:
  spatius: ^1.2.0
```

Then install dependencies:

```bash theme={null}
flutter pub get
```

The package supports iOS and Android Flutter apps.

## Import

```dart theme={null}
import 'package:spatius/avatar_kit.dart' hide ConnectionState, Transform;
```

## Initialize

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

```dart theme={null}
await AvatarSDK.initialize(
  appID: appId,
  configuration: Configuration(
    region: 'us-west',
    audioFormat: const AudioFormat(sampleRate: 16000),
    drivingServiceMode: DrivingServiceMode.direct,
    logLevel: LogLevel.all,
  ),
);

await AvatarSDK.setSessionToken(sessionToken);
```

Use `DrivingServiceMode.direct` for [Direct Mode](/direct-mode/overview). Use `DrivingServiceMode.backend` when your Flutter app receives encoded audio payloads and motion data payloads from a [Backend Mode](/backend-mode/overview).

## Load an avatar

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

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

For Direct Mode audio input, start the connection and send PCM chunks:

```dart theme={null}
await controller.start();
controller.send(audioBytes, end: isLastChunk);
```

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

For Backend Mode input, feed encoded audio payloads and motion data payloads received from your backend:

```dart theme={null}
final conversationId = await controller.yieldAudioData(audioBytes, end: isLastChunk);
controller.yieldAnimations(framesData, conversationID: conversationId);
```

## Demos

<CardGroup cols={2}>
  <Card title="Flutter Direct Mode demo" icon="github" href="https://github.com/spatius-ai/spatius-avatar-demo/tree/main/direct-mode/clients/flutter">
    Direct Mode sample with bundled PCM files.
  </Card>

  <Card title="Flutter Backend Mode demo" icon="github" href="https://github.com/spatius-ai/spatius-avatar-demo/tree/main/backend-mode/clients/flutter">
    Flutter client that talks to the Backend Mode reference server.
  </Card>
</CardGroup>