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://github.com/bithuman-product/homebrew-bithuman.git", from: "2.19.0")

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

Conversation

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.

Performance

Measured on real hardware

Every configuration we publish for this platform renders faster than real time.

Seconds of avatar video rendered per second, Mac
Device	Essence 2	Expression 2
macOS · CLIApple M4	4.24× real time2026-09-27	8.4× real time2026-09-27
macOS · PythonApple M4	6.96× real time2026-09-25	8.45× real time2026-09-25
macOS · Swift packageApple M4	4.8× real time2026-09-24	8.85× real time2026-09-24

“× real time” is seconds of avatar video rendered per second of wall-clock time: end-to-end audio in to frame out, one session, unpaced; the slowest of three quiet runs at least ten minutes apart on the published release. Read from docs performance.json (generated 2026-09-27). How we measure →

Pricing

What it costs

What it costs to run an avatar in your app
Item	On the device (Essence 2, Expression 2)	bitHuman cloud avatar	Managed voice chat (all-inclusive)
Credits per minute of active session time	2	4	10
At top-up rates ($1 = 100 credits)	about $0.02	about $0.04	about $0.10

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

Rates from GET https://api.bithuman.ai/v1/pricing, as published on docs.bithuman.ai/pricing.

The full table, with a worked example Budget an app (docs)

Examples

Examples you can clone

Mac — Expression 2
One Swift command-line tool: speech in, lip-synced frames out, on your Mac.
Runs on
Mac (Apple silicon)
Conversation
No: it renders a speech file
Needs
API secret, Xcode 26
swift/macos-expression2 Walkthrough
Python quickstart
Open an avatar, play speech through it and watch it talk; conversation.py adds a voice conversation.
Runs on
Mac, Linux
Conversation
Yes, in conversation.py (with your own OpenAI key)
Needs
API secret
python/quickstart Walkthrough
CLI recipes
Render a video or run a live avatar from the terminal, with no code.
Runs on
Mac, Linux
Conversation
Yes, with bithuman run
Needs
bithuman login
api/cli Walkthrough