Android reference

How to use these classes in an app is on Android. Signatures are Kotlin; name: Type = … has a default.

Both SDKs are Kotlin-first. The Expression 2 classes live in ai.bithuman.expression2. The Essence 2 names in ai.bithuman.essence2 are Kotlin type aliases of classes in ai.bithuman.elevate, the package that stack traces and logcat show; for example Essence2MeteringRefused is ai.bithuman.elevate.MeteringRefused. Java code imports the ai.bithuman.elevate classes.

Essence 2

Generated from ai.bithuman:essence2-android:0.9.5 as published on maven.bithuman.ai. minSdk 29, ABIs arm64-v8a. Classes not listed here are internal and can change.

Import: import ai.bithuman.essence2.*. Not in that package yet, so import it by name: import ai.bithuman.elevate.Essence2Options. Essence2StoreException.Code is a nested class, which a type alias does not reach, so import it by name: import ai.bithuman.elevate.Essence2StoreException.Code.

Essence2Avatar

class Essence2Avatar : AutoCloseable
    val height: Int
    val lastFrameIndex: Long
    val skippedFrames: Long
    val targetFrames: Int
    val width: Int
    fun available(): Int
    fun checkRender()
    fun close()
    fun endOfAudio()
    fun feed(pcm16le: ByteArray, offset: Int = …, count: Int = …)
    fun feed(samples: FloatArray, offset: Int = …, count: Int = …)
    fun idle(dst: ByteBuffer): Boolean
    fun idleHardwareBuffer(): Essence2HardwareFrame?
    fun newFrameBuffer(): ByteBuffer
    fun pull(dst: ByteBuffer): Boolean
    fun pullHardwareBuffer(): Essence2HardwareFrame?
    fun resetAudio(startFrame: Int = …, forward: Boolean = …, wrap: Boolean = …)
    fun setPlayoutPosition(samples16k: Long)
    fun useHardwareBuffers(slots: Int = …)
    companion object
        const val W2V_MEMBER: String = "w2v_ess_fp16_v1.onnx"
        @JvmStatic fun create(bundleDir: File, options: Essence2Options, w2v: File? = …, threads: Int = …, frames: Essence2Frames? = …): Essence2Avatar
        @JvmStatic fun create(bundleDir: File, w2v: File? = …, threads: Int = …, frames: Essence2Frames? = …): Essence2Avatar

Essence2HardwareFrame

class Essence2HardwareFrame : AutoCloseable
    val buffer: HardwareBuffer
    fun close()

Essence2Credential

object Essence2Credential
    @JvmStatic fun set(apiSecret: String?)

Essence2ModelStore

class Essence2ModelStore
    constructor(context: Context, rootDir: File = …, cacheBudgetBytes: Long = …, urlResolver: Essence2UrlResolver = …)
    val cacheBudgetBytes: Long
    val rootDir: File
    val urlResolver: Essence2UrlResolver
    var bundleLinks: Boolean
    var downloadParallel: Int
    var keepAliveInBackground: Boolean
    var revalidateInBackground: Boolean
    var revalidateMinIntervalMs: Long
    fun bytesOnDisk(): Long
    fun cached(code: String): Essence2Bundle?
    fun cached(code: String, options: Essence2Options): Essence2Bundle?
    fun evict(code: String): Boolean
    fun fetch(code: String, force: Boolean = …, cancelled: AtomicBoolean? = …, progress: Essence2ProgressListener? = …): Essence2Bundle
    fun fetch(code: String, options: Essence2Options, force: Boolean = …, cancelled: AtomicBoolean? = …, progress: Essence2ProgressListener? = …): Essence2Bundle
    fun listCached(): List<Essence2ModelStore.CachedIdentity>
    fun verifyDeep(code: String): Boolean
    fun verifyDeep(code: String, options: Essence2Options): Boolean
    companion object
        const val BUNDLE_MANIFEST: String = "manifest.json"
        const val DEFAULT_DOOR_URL: String = "https://api.bithuman.ai"
        const val STORE_MANIFEST: String = "android_store.v1.json"
        @Deprecated("Member names are the engine's; the store resolves them itself. No replacement is needed.")
        val DEFAULT_MEMBERS: Map<String, String>

Essence2MeteredDoorResolver

class Essence2MeteredDoorResolver : Essence2UrlResolver, Essence2RequestHeaders
    constructor(credential: String, base: String = …)
    fun headers(): Map<String, String>
    fun url(code: String, memberName: String): String

Essence2PublicMirrorResolver

class Essence2PublicMirrorResolver : Essence2UrlResolver
    constructor(base: String = …)
    fun url(code: String, memberName: String): String

Essence2UrlResolver

fun interface Essence2UrlResolver
    fun url(code: String, memberName: String): String

Essence2Bundle

class Essence2Bundle
    val code: String
    val dir: File
    val options: Essence2Options

Essence2Options

data class Essence2Options
    constructor(outputHeight: Int = …)
    val outputHeight: Int
    // data class: copy, componentN, equals, hashCode and toString as Kotlin generates them
    companion object
        const val HD_720: Int = 720
        const val NATIVE: Int = 0

Essence2ProgressListener

fun interface Essence2ProgressListener
    fun onProgress(memberName: String, bytesDone: Long, bytesTotal: Long)

Essence2RequestHeaders

interface Essence2RequestHeaders
    fun headers(): Map<String, String>

Essence2Metering

object Essence2Metering
    var apiBaseUrl: String?
    @Deprecated("Use Essence2Credential.set(secret): one setter covers the download door and the meter.")
    var apiSecret: String?
    @Deprecated("Enforcement is unconditional since 0.5.7; this property is ignored.")
    var enforce: Boolean?
    var installId: String?
    var stateDir: File?
    @Deprecated("The unmetered escape was removed in 0.5.7; this property is ignored.")
    var unmetered: Boolean?

Essence2MeteringRefused

class Essence2MeteringRefused : IllegalStateException

Essence2StoreException

class Essence2StoreException : RuntimeException
    constructor(message: String, cause: Throwable? = …)
    constructor(message: String, cause: Throwable?, code: Essence2StoreException.Code)
    val retriable: Boolean
    val code: Essence2StoreException.Code
    enum class Code
        NETWORK_TRANSIENT, OFFLINE, AUTH, NOT_FOUND, OUTDATED, CORRUPT, REFUSED, CANCELLED, STORAGE, INVALID_ARGUMENT, UNKNOWN
        val retriable: Boolean

Essence2RenderFailed

class Essence2RenderFailed : IllegalStateException
    constructor(message: String, detail: String)
    val detail: String

Essence2BorrowRefused

class Essence2BorrowRefused : IllegalStateException
    constructor(message: String)

Expression 2

Generated from ai.bithuman:expression2-android:0.6.1 as published on maven.bithuman.ai. minSdk 26, ABIs arm64-v8a. Classes not listed here are internal and can change.

Import: import ai.bithuman.expression2.*.

Expression2Avatar

class Expression2Avatar : AutoCloseable
    val accelerator: Accelerator
    val acceleratorNote: String
    val backends: List<Expression2Backend>
    val frameBytes: Int
    val hasPendingTail: Boolean
    val height: Int
    val idleLoop: Expression2IdleLoop?
    val initMs: Double
    val isReady: Boolean
    val model: Expression2Model
    val options: Expression2Options
    val overlapActive: Boolean
    val pendingAudioSlices: Int
    val queuedFrames: Int
    val stepHistoryInputIndex: Int
    val width: Int
    val idleLoopUnavailableReason: String?
    fun beginSegment()
    fun close()
    fun feed(samples: FloatArray, offset: Int = …, count: Int = …)
    fun flushTail(trimSamples: Long = …)
    fun newFrameBitmap(): Bitmap
    fun newFrameBuffer(): ByteBuffer
    fun pull(dst: Bitmap): Expression2Frame?
    fun pull(dst: ByteBuffer): Expression2Frame?
    fun pump()
    fun resetState(clearFrames: Boolean = …)
    companion object
        const val FRAMES_PER_SECOND: Int = 20
        const val FRAME_HEIGHT: Int = 720
        const val FRAME_WIDTH: Int = 416
        const val SAMPLE_RATE: Int = 16000
        @JvmStatic fun create(context: Context, model: Expression2Model, options: Expression2Options = …): Expression2Avatar
        @JvmStatic fun warmUp(context: Context, model: Expression2Model, options: Expression2Options = …): Expression2Avatar

Expression2Credential

object Expression2Credential
    @JvmStatic fun set(apiSecret: String?)

Expression2ModelStore

class Expression2ModelStore
    constructor(context: Context, rootDir: File = …, cacheBudgetBytes: Long = …, urlResolver: Expression2ModelStore.UrlResolver = …, preferAndroidMember: Boolean = …)
    val cacheBudgetBytes: Long
    val preferAndroidMember: Boolean
    val rootDir: File
    val urlResolver: Expression2ModelStore.UrlResolver
    var revalidateInBackground: Boolean
    var revalidateMinIntervalMs: Long
    fun bytesOnDisk(): Long
    fun cached(code: String): Expression2Model?
    fun evict(code: String): Boolean
    fun fetch(code: String, force: Boolean = …, cancelled: AtomicBoolean? = …, progress: Expression2ModelStore.ProgressListener? = …): Expression2Model
    fun listCached(): List<Expression2ModelStore.CachedIdentity>
    fun verifyDeep(code: String): Boolean
    companion object
        const val ANDROID_BLOCK: String = "android"
        const val DEFAULT_DOOR_URL: String = "https://api.bithuman.ai"
        const val MANIFEST: String = "web_manifest.json"
        val CANON: String
        val IDLE: String
        val MODEL: String
        val REQUIRED: List<String>

Expression2ModelStore.MeteredDoorResolver

class Expression2ModelStore.MeteredDoorResolver : Expression2ModelStore.UrlResolver, Expression2ModelStore.RequestHeaders
    constructor(credential: String = …, base: String = …)
    fun headers(): Map<String, String>
    fun url(code: String, memberName: String): String

Expression2ModelStore.PublicMirrorResolver

class Expression2ModelStore.PublicMirrorResolver : Expression2ModelStore.UrlResolver
    constructor(base: String = …)
    fun url(code: String, memberName: String): String

Expression2ModelStore.UrlResolver

fun interface Expression2ModelStore.UrlResolver
    fun url(code: String, memberName: String): String

Expression2ModelStore.ProgressListener

fun interface Expression2ModelStore.ProgressListener
    fun onProgress(memberName: String, bytesDone: Long, bytesTotal: Long)

Expression2Model

class Expression2Model
    val canon: File
    val code: String?
    val combinedModel: File?
    val contextCacheDir: File?
    val identityModel: File?
    val idleClip: File?
    val isSplit: Boolean
    val modelBytes: Long
    val sharedEncModel: File?
    fun toString(): String
    companion object
        const val CANON_BYTES: Long = 299520
        @JvmStatic fun combined(modelPath: File, canonPath: File, code: String? = …, contextCacheDir: File? = …, idleClipPath: File? = …): Expression2Model
        @JvmStatic fun split(sharedEncPath: File, identityPath: File, canonPath: File, code: String? = …, contextCacheDir: File? = …): Expression2Model

Expression2Options

data class Expression2Options
    constructor(accelerator: Accelerator = …, routing: Routing? = …, threads: Int = …, qnnOptions: String = …, contextCacheDir: File? = …, disableContextCache: Boolean = …, maxQueuedFrames: Int = …, extraDspSearchPaths: List<String> = …, overlapDecoder: Boolean? = …)
    val accelerator: Accelerator
    val contextCacheDir: File?
    val disableContextCache: Boolean
    val extraDspSearchPaths: List<String>
    val maxQueuedFrames: Int
    val overlapDecoder: Boolean?
    val qnnOptions: String
    val threads: Int
    // data class: copy, componentN, equals, hashCode and toString as Kotlin generates them
    companion object
        const val DEFAULT_QNN_OPTIONS: String = "backend_type:htp;htp_precision:1;htp_performance_mode:6"
        const val QNN_DELEGATE_SO: String = "libQnnTFLiteDelegate.so"
        const val QNN_OPTIONS_ADRENO_FP32: String = "backend_type:gpu;gpu_precision:0"
        const val QNN_OPTIONS_HEXAGON_BURST: String = "backend_type:htp;htp_precision:1;htp_performance_mode:6;htp_optimization_strategy:1"

Expression2Metering

object Expression2Metering
    var apiBaseUrl: String?
    @Deprecated("Use Expression2Credential.set(secret): one setter covers the download door and the meter.")
    var apiSecret: String?
    var installId: String?
    var stateDir: File?

Expression2Frame

data class Expression2Frame
    constructor(index: Long, presentationTimeUs: Long, audioSample: Long = …, isSpeech: Boolean = …)
    val audioSample: Long
    val index: Long
    val isSpeech: Boolean
    val presentationTimeSeconds: Double
    val presentationTimeUs: Long
    // data class: copy, componentN, equals, hashCode and toString as Kotlin generates them

Expression2IdleLoop

class Expression2IdleLoop : AutoCloseable
    val height: Int
    val width: Int
    val frameCount: Int
    val lastIndex: Int
    val wraps: Int
    fun close()
    fun next(dst: Bitmap): Int

Expression2Exception

class Expression2Exception : RuntimeException
    constructor(message: String, cause: Throwable? = …)

Accelerator

enum class Accelerator
    AUTO, NPU, CPU

Expression2Backend

data class Expression2Backend
    constructor(modelPath: String, device: Device, modelLoadMs: Double, interpreterCreateMs: Double, qnnContextCacheWasWarm: Boolean, qnnContextCacheBytesBefore: Long, qnnContextCacheBytesAfter: Long)
    val device: Device
    val interpreterCreateMs: Double
    val modelLoadMs: Double
    val modelPath: String
    val qnnContextCacheBytesAfter: Long
    val qnnContextCacheBytesBefore: Long
    val qnnContextCacheWasWarm: Boolean
    var decWarmupDec8Ms: Double
    var decWarmupFirstMs: Double
    var decWarmupSecondMs: Double
    var qnnColdCompileMs: Double
    var qnnContextSerialized: Boolean
    var qnnPersistMs: Double
    var qnnRestoreDegraded: Boolean
    // data class: copy, componentN, equals, hashCode and toString as Kotlin generates them

Device

enum class Device
    CPU, NPU, REFERENCE

See also

• Android — install it, get a model, render your first frame
• Examples: Expression 2 · Essence 2
• Pricing — what a render costs, and what refuses without an API secret
• Performance — measured frame rates for every platform