Developers · Mac

A real-time avatar for Mac apps and desktop companions

Two ways in. The Swift package renders the avatar inside your Mac app. The bitHuman CLI runs a complete desktop companion, and with its local conversation brain (BITHUMAN_LOCAL=1), speech recognition, the language model and the voice all run on the Mac. The session still reports usage online.

From 12 October 2026, API and SDK use requires the Creator plan or higher.

First frame in the docs Get an API secret

Install

Swift package, in a Mac app

.package(url: "https://gitlab.com/bithuman/sdk/homebrew-bithuman", from: "2.20.5")

The bitHuman CLI, for a desktop companion

curl -fsSL https://install.bithuman.ai | sh

What you need: Xcode 26+, API secret · sign-in (from the docs)

Your first frame, step by step The full Mac guide

Add a conversation

The Swift package only renders, as on iPhone. For a complete desktop companion, the bitHuman CLI can run the whole conversation on the Mac.

The local conversation brain (CLI)
Speech recognition, the language model and the voice run on the Mac. It needs a one-time build and a model download on its first run; the docs give the steps and the size.
Local conversation brain
Your own services, in a Swift app
The Swift package takes 16 kHz mono speech from any voice stack and returns frames, as on iPhone.
Resample speech to 16 kHz

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.

Requirements

A Mac with Apple silicon; Intel Macs are not supported.
Essence 2 in the Swift package needs a newer Mac and macOS than Expression 2; the docs list both floors.
A sandboxed Mac app needs the Outgoing Connections (Client) entitlement, or the engines cannot check your API secret.