Docs index: /llms.txt · every page as Markdown: add .md

‹ Platforms

Build a Flutter app

Stream audio into a Flutter avatar and show its frames in your app.

Integrate into your app

The avatar is a Texture in your widget tree. Pass engine: every time, 'expression2' or 'essence2': leave it out and the plugin loads Expression 2 (plugin 2.6.36 and newer). On Android the first argument to load is the agent code; the plugin downloads the avatar and keeps it.

import 'package:bithuman/bithuman.dart';

final avatar = await BithumanAvatar.load(
  'A23WJF0199',            // on Android, the agent code
  engine: 'expression2',   // 'expression2' (the default) or 'essence2'; pass it every time
  apiSecret: secret,
);

Texture(textureId: avatar.textureId);        // the avatar in your layout

await avatar.audioStart(enableMic: false);   // the speaker; required on iOS and macOS
await avatar.playSpeakerPCM(chunk);          // Uint8List, 24 kHz mono PCM16: heard, and the lips follow
await avatar.notifyTurnEnd();                // after the reply's last chunk
await avatar.interrupt();                    // cut the current reply
await avatar.dispose();                      // release the engine
JobCall
Show the avatarTexture(textureId: avatar.textureId); frameWidth and frameHeight give its size
Start the speakeraudioStart(enableMic: false), once, before the first chunk
Play your speechplaySpeakerPCM(Uint8List), 24 kHz mono PCM16, chunk by chunk; the same audio drives the lips
End a replynotifyTurnEnd() after the last chunk, so the last word is not clipped
Know it is readyisReady, or await avatar.ready; audio sent before it is dropped
Interrupt the replyinterrupt()
StopaudioStop(), then dispose()
Pick the modelengine: 'expression2' or engine: 'essence2' (default 'expression2'; pass it every time)

A voice conversation instead of your own audio: BithumanRealtimeSession(apiKey: secret, avatar: avatar, model: 'gpt-realtime-mini') from package:bithuman/bithuman_realtime.dart connects the avatar to bitHuman’s realtime relay with your API secret, billed 10 credits a minute with the avatar included. Show spokenTranscriptStream as captions and handle errorStream (Flutter errors).

Complete example

The avatar_chat app is a complete voice conversation with idle motion and interruption, in one layout for every platform. From plugin 2.6.20 its voice session connects through bitHuman’s realtime relay with your API secret; no token is minted.

Platform notes

  • Android build settings: the plugin needs minSdk 29 whichever model you use, arm64-v8a only, and useLegacyPackaging = true (Install).
  • Your own voice pipeline: any speech your stack produces works: resample it to 24 kHz mono PCM16 and send it through playSpeakerPCM, as above. pushAudio is not the call for this: on iOS and macOS it moves the lips with no sound (on Android it plays from plugin 2.6.36).
  • Sign-out: call BithumanAvatar.clearCredentials() when an account signs out (plugin 2.6.36 or newer). The engines forget the secret, and on Android every load still running ends with load_cancelled. On iOS and macOS, set the Expression 2 agent folder again (setExpression2AgentDir) before the next load that needs one.
  • Errors: what load throws and why a voice session ends are on Flutter errors.
  • Captions: with the plugin’s realtime session, show spokenTranscriptStream rather than botTranscriptStream. It releases the agent’s words as they are heard, so the caption keeps pace with the voice; each event holds the reply’s caption so far, and a cut reply ends with only the words heard (plugin 2.6.27 or newer).
  • iOS and macOS (Apple silicon) builds: run the plugin’s scripts/bootstrap.sh once (it downloads the published engines and checks their sha256; for a git dependency the plugin’s folder is packages/flutter-plugin under ~/.pub-cache/git/homebrew-bithuman-…) and raise the deployment targets (platform :ios, … in ios/Podfile, platform :osx, … in macos/Podfile, and the Runner targets to match). Each model has its own minimum: Expression 2 renders on iOS 18 and macOS 15 and later, so an app that renders it sets iOS 18.0 and macOS 15.0; Essence 2 needs iOS 26 and macOS 26. Below a model’s minimum, load fails with unsupported and names it (Flutter errors). The pod itself builds from iOS 16.4 and macOS 14.0. Nothing is installed with Homebrew: from plugin 2.6.39 the app links the plugin’s own ONNX Runtime, so do not add another ONNX Runtime to it.
  • Versions: each plugin tag fixes the Android SDK versions it uses. The current tag and its line are on Downloads & versions.

Reference