Run a talking avatar on your laptop

4 steps

1. Check your laptop

   Laptop	Use	Check
   Linux on x86_64 or arm64	the CLI or the Python SDK	uname -sm
   macOS 14 or newer on Apple silicon	the CLI or the Python SDK	uname -sm prints Darwin arm64
   Windows 11 on x86_64	the Python SDK on Windows; the CLI on Windows renders in the cloud	python -c "import platform; print(platform.system(), platform.machine())" prints Windows AMD64

   Intel Macs and Windows on Arm have no package.

   Expected

   One row that matches your laptop.

   Done: step 1

2. Install and sign in

   On Linux or macOS, install the CLI and sign in:

   # Linux, x86_64 or arm64 (Debian/Ubuntu)
   sudo apt install -y ffmpeg python3-venv
   curl -fsSL https://install.bithuman.ai | sh
   # macOS (Apple silicon): also installs ffmpeg, livekit-server and Python
   brew tap bithuman/bithuman https://gitlab.com/bithuman/sdk/homebrew-bithuman && brew install bithuman/bithuman/bithuman-cli
   
   bithuman login            # opens a browser and stores a credential for this device
   bithuman account          # exit 0 when signed in

   On Windows 11, in PowerShell:

   python -m venv .venv
   .venv\Scripts\Activate.ps1
   pip install "bithuman[expression-2]"
   $env:BITHUMAN_API_SECRET = "<your API secret>"

   Expected

   bithuman account exits 0 on Linux or macOS; on Windows, pip finishes with no error.

   Done: step 2

3. Render the sample and time it

   On Linux or macOS:

   curl -fsSLo speech.wav https://docs.bithuman.ai/samples/speech.wav
   time bithuman render wise-pup speech.wav -o out.mp4
   # → out.mp4: 416×720, 300 frames, 15.0 s

   On Windows 11:

   curl.exe -fL -o wise-pup.imx "https://api.bithuman.ai/v1/agent/A23WJF0199/model/download?model=expression-2"
   curl.exe -fsSLo speech.wav https://docs.bithuman.ai/samples/speech.wav
   Measure-Command { python -c "import bithuman; bithuman.open('wise-pup.imx').render('speech.wav', out_mp4='out.mp4')" }

   The sample is 15 seconds of speech. Run the render twice, because the first run also downloads the avatar. A second run that takes less than 15 seconds means your laptop renders Expression 2 faster than real time. For the photoreal model, render sofia-ramirez the same way.

   Expected

   out.mp4: wise-pup speaking the sample, 416×720, with its lips in sync.

   Done: step 3

4. Talk to it live

   On Linux or macOS, bithuman run starts a local LiveKit server, a voice agent and the avatar, then opens the page in your browser. It needs Python 3.11 or newer for its voice agent:

   bithuman run wise-pup
   # → open the printed http://127.0.0.1:8088/<CODE> and allow the microphone

   The voice runs on OpenAI Realtime, with your OPENAI_API_KEY or on your bitHuman account (voice settings). For a conversation that also runs on the laptop, use the local conversation brain: BITHUMAN_LOCAL=1 bithuman run sofia-ramirez. On Windows, stream audio into AsyncBithuman from your own code (Python: Integrate into your app).

   Expected

   Say "hi": the avatar answers out loud with its lips in sync, and stops when you talk over it.

   Done: step 4

All steps done. Next: make it your own.