bithuman

Run a bitHuman avatar on your own machine, in your own process.

pip install bithuman
DEMO=$(python -c 'import bithuman,os; print(os.path.join(os.path.dirname(bithuman.__file__), "assets", "demo_sample.wav"))')
python -m bithuman render sofia-ramirez "$DEMO"     # -> sofia-ramirez.mp4

Two arguments — an avatar and some audio — and a video you can play (with your API secret in BITHUMAN_API_SECRET; see the key). The avatar is a showcase name (python -m bithuman list), your agent's ten-character code (python -m bithuman list --mine; fetched once, which is free), or a file you already have. The audio above is 15 s of speech that ships with this package, so the first run needs nothing you do not already have. It is the same command line as the bithuman CLI: render <avatar> <audio> [-o out.mp4] [--limit N] [--json], list [--mine], and one sign-in (bithuman login) serves both.

In your own program it is the same two things. The command above fetched the avatar to ~/.cache/bithuman/showcase/:

import bithuman, os

speech = os.path.join(os.path.dirname(bithuman.__file__),
                      "assets", "demo_sample.wav")   # 15 s, ships in the wheel
avatar_file = os.path.expanduser("~/.cache/bithuman/showcase/sofia-ramirez.imx")

avatar = bithuman.open(avatar_file)
frames = 0
for image in avatar.render(speech):   # each image: (height, width, 3) uint8, RGB
    frames += 1
print(frames, "frames")

That is the whole thing: open an avatar, then render audio through it.

both families, the same two lines

An essence-2 avatar and an expression-2 avatar are opened and rendered by the code above, unchanged. Nothing you write says which one you have, and you do not have to know.

expression-2 needs one extra package on the machine:

pip install "bithuman[expression-2]"

Open an expression-2 avatar without it and the refusal says so, and says that line. Nothing else differs.

offline rendering, without 3 GB of CUDA you will never run

bithuman[offline] adds torch and onnxruntime. From PyPI's default index that resolves to the CUDA build of torch, and the extra costs 3.18 GB of wheels — 2.45 GB of it nvidia-*, cuda-* and triton that the offline route never executes. Install torch first from PyTorch's own selector — choose the Compute Platform without CUDA and run the one line it prints — and the same extra then resolves to 0.18 GB, with no CUDA wheel in the set at all (the extra asks for torch>=2.1, and any build satisfies it):

pip install "bithuman[offline]"      # after torch, from the line the selector printed

(Measured 2026-09-19 on Linux x86_64 with pip install --dry-run --report: 49 wheels / 3.18 GB from the default index alone, 30 wheels / 0.18 GB with PyTorch's CUDA-free index beside it. Use the default index only if you actually want CUDA.)

The surface — eight names

There is nothing else, and nothing to configure. This package runs the avatar on this machine, so there is no choice left about where or how it runs.

audio in

audio is 16 kHz mono, and it is either a buffer or a stream — the same call:

avatar.render(speech)                      # an audio file path
avatar.render(samples)                     # int16 or float32 in [-1, 1]
avatar.render(raw_bytes)                   # 16 kHz mono, signed 16-bit
avatar.render(microphone())                # any iterable of the above

frames out

Each frame is a (height, width, 3) uint8 array in RGB order, in order, at the avatar's own frame rate — which is a property of the avatar, not something to choose. (This line read "one per 40 ms of speech" until 2026-09-06, which was true of every avatar the package could open at the time and is not true of an expression-2 one.)

import cv2
for image in avatar.render(speech):
    cv2.imshow("avatar", image[:, :, ::-1])   # OpenCV wants BGR
    cv2.waitKey(1)

stopping early

Someone interrupting the avatar is "stop consuming and close the iterator":

images = avatar.render(speech)
for n, image in enumerate(images):
    if n == 50:                       # e.g. the user started talking
        images.close()
        break

releasing it

with frees everything at the end of the block; without it, the avatar is freed when it is garbage collected.

with bithuman.open(avatar_file) as avatar:
    for image in avatar.render(speech):
        frames += 1

The four refusals

Each one leads to a different fix, and none of them asks you to know anything about how we are built.

try:
    avatar = bithuman.open(avatar_file)
    for image in avatar.render(speech):
        pass
except bithuman.InvalidAvatar:
    ...   # fix the path or the code, or fetch the avatar again
except bithuman.NotSupported:
    ...   # use the cloud package, or another device
except bithuman.NotAuthorised:
    ...   # fix the credential
except bithuman.Failed:
    ...   # retry, then report it

Every one of them is an AvatarError, so except bithuman.AvatarError catches all four.

The key

Rendering is metered, and the key belongs in the environment rather than in your code:

export BITHUMAN_API_SECRET=...

Without one, render refuses with NotAuthorised before it hands you a frame. Get a key at https://www.bithuman.ai/developer/api-keys.

python -m bithuman also reads a .env file beside you, which is where a key usually already is. What is already in the environment always wins.

Where it runs

ffmpeg is used to read an audio file when it is on your PATH; when it is not, the decoder this package already installs reads the same file in this process, so it is not something to install first.

Two environment variables:

This package never puts a command on your PATH

pip install bithuman installs a library and nothing else — and python -m bithuman is why that costs you nothing: a module needs no script, cannot collide with one, and is there the moment pip finishes. The full bithuman command-line tool (a live avatar, a conversation) is a different artifact and is not installed with pip:

curl -fsSL https://raw.githubusercontent.com/bithuman-product/homebrew-bithuman/main/install.sh | sh
brew install bithuman-product/bithuman/bithuman-cli      # macOS, equivalently

That is an invariant, not an accident: a pip-installed command named bithuman would overwrite the one Homebrew put at the same path, and every check would still report success. tests/test_no_console_script.py fails if a release ever grows one — on every push and pull request (the source side, with three firing controls) and again inside each publish job, run directly against the wheels being uploaded. A directory that is declared and holds no bithuman wheel exits 2: a publish that cannot be graded is refused, not passed.

Using it from a LiveKit agent

The LiveKit integration is a separate package, livekit-plugins-bithuman, published by LiveKit out of github.com/livekit/agents. Install pillow beside it:

pip install livekit-plugins-bithuman pillow

That plugin imports PIL.Image at module scope and its published metadata does not declare pillow, so installing it on its own ends at ModuleNotFoundError: No module named 'PIL' the first time you import it. The metadata is upstream's, not ours — this line is the whole fix, and the deploy guide carries it too.

On Python 3.10 and 3.14 there is a second one, and pillow alone does not clear it. That plugin declares bithuman behind a python_version >= "3.11" and python_version < "3.14" marker, so on those two interpreters pip reports success and installs no bithuman at all — which takes cv2 with it, and the import dies there instead. This package publishes cp310 and cp314 wheels that install and import cleanly, so name it yourself:

pip install livekit-plugins-bithuman pillow bithuman     # Python 3.10 / 3.14

Both workarounds have an expiry: pillow and the dropped marker are already merged upstream in livekit/agents#7280 and are waiting on a plugin release. A release after that commit needs neither word.

Coming from 2.10.0?

3.0.0 is a clean break. Thirty-two names became eight, and fourteen error classes became four.

Frames are still (height, width, 3) uint8 arrays, still 25 per second, still in order.

2.10.0 is on PyPI forever and keeps resolving exactly as it does today. Pin bithuman<3 to stay on it.

Licence

Proprietary — this package carries the runtime. See LICENSE.