# On-device avatar SDK for iOS and Android

URL: https://docs.bithuman.ai/start/on-device-avatar-sdk

> Render Essence 2 and Expression 2 avatars on iPhone, iPad, Mac and Android.

bitHuman's SDKs render a lip-synced avatar on the device in front of the user, with no render server. Essence 2 and Expression 2 render on iPhone, iPad and Mac with the [Swift package](https://docs.bithuman.ai/platforms/ios), on Android arm64 with the [Android SDK](https://docs.bithuman.ai/platforms/android), on macOS (Apple silicon) and Linux x86_64 / arm64 with the [CLI](https://docs.bithuman.ai/platforms/cli) and the [Python SDK](https://docs.bithuman.ai/platforms/python), and in a browser tab with [WebGPU](https://docs.bithuman.ai/platforms/web/webgpu).

Your app passes in 16 kHz mono speech from any voice stack and draws the frames, so the persona, the voice and the language model are yours to choose.

## Which model runs where

Essence 2 renders a photoreal person from one portrait; Expression 2 renders any character (people, animals, cartoons) from one portrait.

| Device | SDK | Essence 2 | Expression 2 |
|---|---|---|---|
| iPhone and iPad | [Swift package](https://docs.bithuman.ai/platforms/ios) (`Essence2Kit`, `Expression2`) | iOS 26 or newer, physical device | iOS 16 or newer; also runs in the Simulator |
| Mac (Apple silicon) | [Swift package](https://docs.bithuman.ai/platforms/macos), or the CLI and the Python SDK | yes; macOS 26 or newer with the Swift package | yes; macOS 13 or newer with the Swift package |
| Android arm64 | [Android SDK](https://docs.bithuman.ai/platforms/android) (`essence2-android`, `expression2-android`) | physical device, `minSdk 29` | physical device, `minSdk 26` |
| Android, iOS and macOS from Dart | [Flutter plugin](https://docs.bithuman.ai/platforms/flutter) | yes | yes |
| Linux x86_64 / arm64 | [CLI](https://docs.bithuman.ai/platforms/cli), [Python SDK](https://docs.bithuman.ai/platforms/python) | yes | yes |
| A browser tab | [web embed](https://docs.bithuman.ai/platforms/web/webgpu) with `render=local` (WebGPU) | yes | yes |

Essence 1 and Expression 1 are not available on phones or in the Swift package. Every model and every place, side by side: [Where each model runs](https://docs.bithuman.ai/models#where-each-model-runs).

## Install

Each install line below is the one on its platform page, which also covers authentication and the first frame.

### iPhone, iPad and Mac

```swift
// Package.swift (or Xcode → Add Package Dependencies)
.package(url: "https://gitlab.com/bithuman/sdk/homebrew-bithuman", from: "2.22.2")
```

Then attach the product your target uses: `Expression2` or `Essence2Kit`. The products and their deployment targets are on [iOS & iPadOS](https://docs.bithuman.ai/platforms/ios#install).

### Android

Each model is one Gradle dependency, from bitHuman's Maven repository at `maven.bithuman.ai`:

```kotlin
// settings.gradle.kts, in dependencyResolutionManagement { repositories { … } }
exclusiveContent {   // ai.bithuman resolves from bitHuman's repository only
    forRepository { maven { url = uri("https://maven.bithuman.ai") } }
    filter { includeGroup("ai.bithuman") }
}
// app/build.gradle.kts
implementation("ai.bithuman:expression2-android:0.6.2")
// or: implementation("ai.bithuman:essence2-android:0.10.3")
```

The full Gradle setup (`arm64-v8a`, legacy packaging, the API secret through `BuildConfig`) is on [Android](https://docs.bithuman.ai/platforms/android#install).

### Flutter

```yaml
dependencies:
  bithuman:
    git:
      url: https://gitlab.com/bithuman/sdk/homebrew-bithuman.git
      path: packages/flutter-plugin
      ref: flutter-plugin-v2.6.40
```

Then run `flutter pub get`. The Android settings the plugin needs are on [Flutter](https://docs.bithuman.ai/platforms/flutter#install).

### Linux and macOS

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install "bithuman[expression-2]"   # Expression 2
pip install "bithuman[essence-2]"      # Essence 2
```

```bash
# Linux, x86_64 or arm64 (Debian/Ubuntu); the download includes livekit-server
sudo apt install -y ffmpeg python3-venv
curl -fsSL https://install.bithuman.ai | sh
```

On macOS, install the CLI with Homebrew: [CLI](https://docs.bithuman.ai/platforms/cli#install).

### A browser tab

```html
<iframe src="https://www.bithuman.ai/embed/A23WJF0199?render=local" allow="microphone *"
        style="width:100%;height:600px;border:0"></iframe>
```

With `render=local` the tab checks the device first; if the device can't render the avatar in real time, the page says so and no session starts. Details: [WebGPU](https://docs.bithuman.ai/platforms/web/webgpu).

## Network and data

- **Online:** phones, Macs and browsers stay online. The Swift package, the Android SDK and the web embed check your credential when a session starts, and an on-device session keeps rendering through a network drop of up to 5 minutes.
- **In your app:** when the avatar renders in your app on the device and you use your own voice and language services, bitHuman receives usage metering only, never audio, video or conversation text.
- **In the browser:** with the web embed, the conversation runs on bitHuman's servers, even when the avatar renders in the tab.
- **First run:** each avatar downloads once, then stays on the device.
- **Devices:** Android, and Essence 2 on iPhone and iPad, need a physical device, not an emulator or the Simulator.

More on each: [On the device](https://docs.bithuman.ai/deploy/on-device).

## Speed

Every published configuration renders faster than real time. Measured on the device, including 10-minute held runs:

| Configuration | Hardware | Essence 2 | Expression 2 |
|---|---|---|---|
| iPhone · Swift package | iPhone 15 | 2.1× real time | 5.5× real time |
| Android | Samsung Galaxy S25+ | 2.0× real time | 2.4× real time |
| Web browser (WebGPU) | Chrome on Apple M5 | 4.0× real time | 2.4× real time |
| macOS · Swift package | Apple M4 iMac (Mac16,3, 10-core GPU) | 4.3× real time | 8.8× real time |

× real time: seconds of video rendered per second; 1.0× or more holds a live conversation ([method](https://docs.bithuman.ai/performance)).

The browser row is the engine's render speed in the tab, not the frame rate a visitor sees.

## Price

The SDKs need the Creator plan or higher. Rendering on the device bills a lower rate than the bitHuman cloud.

2 credits per minute for Essence 2 and Expression 2, about $0.02 a minute at the top-up rate of $1 = 100 credits. Billing: [How billing works](https://docs.bithuman.ai/pricing#how-billing-works). Every rate: [Pricing and credits](https://docs.bithuman.ai/pricing).