Private, on-device visual agents

# pip install "bithuman[expression-2]"
# hello.py
import bithuman

with bithuman.open("A23WJF0199.imx") as avatar:         # an Essence 2 .imx or an Expression 2 .avatar — one call
    for image in avatar.render("demo_sample.wav"):     # (height, width, 3) uint8, RGB, at the avatar's own frame rate
        print(image.shape)                             # hand it to your display — OpenCV wants image[:, :, ::-1]

// build.gradle.kts: implementation("ai.bithuman:expression2-android:0.4.7")
import ai.bithuman.expression2.Expression2Avatar
import ai.bithuman.expression2.Expression2ModelStore
import ai.bithuman.expression2.Expression2Options
import android.content.Context
import android.graphics.Bitmap

/** [pcm16k] is 16 kHz mono float32 in [-1, 1] — one float per sample, not ShortArray. */
fun render(context: Context, agentCode: String, pcm16k: FloatArray, show: (Bitmap) -> Unit) {
    // Downloads the model the first time (~158 MB). Never on the main thread.
    val model = Expression2ModelStore(context).fetch(agentCode)

    Expression2Avatar.create(context, model, Expression2Options()).use { avatar ->
        val frame = avatar.newFrameBitmap()   // ARGB_8888, 416 x 720 — allocate once
        avatar.feed(pcm16k)                   // renders each complete 1.6 s chunk
        avatar.flushTail()                    // the padded tail is the last sentence
        while (true) {
            if (avatar.pull(frame) != null) { show(frame); continue }
            if (!avatar.hasPendingTail && avatar.queuedFrames == 0) break
        }
    }
}

// Package.swift: .package(url: "https://github.com/bithuman-product/homebrew-bithuman.git", from: "2.11.0")
import Expression2

let engine = try Expression2Engine.create(modelPath: avatarDirectory,        // the unpacked .avatar
                                          sharedEngineDir: sharedEngineDirectory)
engine.feed(samples)                       // [Float] PCM, 16 kHz mono
engine.flushTail()                         // at the end of an utterance

// Generation is asynchronous: pull() returns nil until a chunk lands, so poll.
var idleTicks = 0
while idleTicks < 100 {                    // 100 x 50 ms with nothing = done
    var got = false
    while let (frame, _) = engine.pull() { // frame: [UInt8], BGR, engine.width * engine.height * 3
        got = true
        show(frame)
    }
    if got { idleTicks = 0 } else { idleTicks += 1; try await Task.sleep(nanoseconds: 50_000_000) }
}