macOS

The iPhone and iPad Swift package, in a Mac app or from a terminal with swift run.

Before you start

No device, provisioning profile or entitlement is needed to try it from a terminal.

Why render on the device.

Install

.package(url: "https://gitlab.com/bithuman/sdk/homebrew-bithuman", from: "2.20.5")
// then attach the product your target uses:
//   .product(name: "Expression2", package: "homebrew-bithuman")
//   .product(name: "Essence2Kit", package: "homebrew-bithuman")
//   .product(name: "Essence2", package: "homebrew-bithuman")

Authenticate

A Mac app built from Xcode’s App template turns on App Sandbox. Under Signing & Capabilities → App Sandbox, tick Outgoing Connections (Client), or the engines cannot check your secret.

Run your first avatar

The macOS Expression 2 example is one Swift file. Clone it, fetch the sample avatar, and run it:

git clone https://github.com/bithuman-product/bithuman-examples.git
cd bithuman-examples/swift/macos-expression2
./setup.sh                                 # the wise-pup avatar, the shared engine and a speech clip
export BITHUMAN_API_SECRET="<your API secret>"
swift run -c release MacOSExpression2

engine ready: 416x720, isReady=true
audio: 325451 samples, 20.34 s
generated 407 frames in … s -> out/first-frame.png

The core of Sources/main.swift:

// excerpt: swift/macos-expression2/Sources/main.swift
let engine = try Expression2Engine.create(
    avatarContainer: model.appendingPathComponent("agent.imx"),
    sharedEngineContainer: model.appendingPathComponent("shared-engine.imx"),
    stagingDir: model.appendingPathComponent("staged"))
// …
let started = Date()
engine.feed(samples)
engine.flushTail()
// …
var frames = 0, idleTicks = 0
while idleTicks < 100 {
    var got = false
    while let (frame, _) = engine.pull() {
        if frames == 0 {
            writePNG(frame, width: engine.width, height: engine.height,
                     to: out.appendingPathComponent("first-frame.png"))
        }
        frames += 1
        got = true
    }
    if got { idleTicks = 0 } else { idleTicks += 1; usleep(50_000) }
}

Essence 2 on a Mac

Essence 2 needs an M3 or newer Mac on macOS 26. The same Essence2Kit calls as on the iPhone render a file from a terminal tool: download the avatar in code, set pacing = .unpaced, and take the frames as fast as they render.

// excerpt: a terminal tool (swift run) with the Essence2Kit product;
// samples is a 16 kHz mono clip as [Float].
import Essence2Kit

Essence2Credential.set(ProcessInfo.processInfo.environment["BITHUMAN_API_SECRET"] ?? "")
let imxURL = try await Essence2Download.identity(agentCode: "A52DHS2219")   // sofia-ramirez
let engine = try await Essence2Engine.create(identity: imxURL)            // waits until the engine is ready
engine.pacing = .unpaced                     // a file render: frames as fast as they render

engine.feed(samples)                         // [Float], 16 kHz mono
engine.flushTail()                           // that is the whole reply
var speech = 0
for await frame in engine.frames() {
    if frame.isSpeech { speech += 1 }        // frame.bgr: B, G, R bytes, width * height * 3
    if frame.endsReply { break }             // the reply is over; idle frames follow
}
print("\(engine.width)x\(engine.height): \(speech) frames for \(Double(samples.count) / 16_000) s of audio")
engine.shutdown()

1080x1920: 375 frames for 14.997375 s of audio

Play with sound (8 seconds, captions)

Performance