Voice agent

A voice avatar on your own computer, with LiveKit running locally.

Everything except the voice model runs on your computer. LiveKit is an open-source real-time audio and video server: the voice agent and the avatar join one of its rooms, and your browser joins too. Here it is the stock livekit-server, OpenAI Realtime listens, thinks and speaks on your own OPENAI_API_KEY, and the bitHuman avatar renders on your CPU — no GPU needed.

The avatar name picks the model: wise-pup is Expression 2, sofia-ramirez is Essence 2, or pass your own agent code or avatar file. You need two secrets: your bitHuman API secret (both models refuse to render without it) and OPENAI_API_KEY.

A voice agent on your machine. Your browser, a local livekit-server and the agent all run on your machine; the agent renders the avatar from the reply's voice, and the API secret stays in its process. The agent sends your speech to OpenAI Realtime with your key, and sends bitHuman a credential check and usage reports with no audio, video, images or conversation text.

Use the CLI for a talking avatar with no code, Python for your own agent code, or the Python voice conversation for a desktop window with no LiveKit server.

With the CLI

The CLI starts livekit-server, the voice agent and the avatar, then opens its page in your browser.

# macOS (Apple silicon): installs livekit-server too
brew tap bithuman/bithuman https://gitlab.com/bithuman/sdk/homebrew-bithuman && brew install bithuman/bithuman/bithuman-cli
# Linux x86_64 or arm64: the download includes livekit-server
sudo apt install -y ffmpeg python3-venv            # Ubuntu/Debian; macOS gets both from brew
curl -fsSL https://install.bithuman.ai | sh

bithuman login                                   # opens your browser; in CI, export BITHUMAN_API_SECRET instead
export OPENAI_API_KEY="<your OpenAI key>"
bithuman run wise-pup                            # Expression 2; `bithuman run sofia-ramirez` for Essence 2

Expected output:

      http://127.0.0.1:8088/WISEPUP
  Opening your browser… (Ctrl-C to stop.)

The first run downloads the avatar and sets up the voice agent, which takes a minute or two and needs Python 3.11 or newer. Allow the microphone and say “hi”: the avatar answers, lip-synced, and stops when you talk over it. The voice settings are on CLI.

Pick the avatar

bithuman run <value>, or BITHUMAN_AVATAR=<value> in the Python example’s .env:

Value	You get
`wise-pup`	Expression 2, a sample avatar
`sofia-ramirez`	Essence 2, a sample avatar
your agent code, e.g. `A24EKJ8433`	your own avatar, downloaded with your API secret
a path to an avatar file	a file you already have

Configuration

The Python example reads these from .env:

Variable	Default	What it does
`BITHUMAN_MASTER_SECRET`	—	Your API secret, passed to the plugin explicitly. Rendering is metered on it. It is named `BITHUMAN_MASTER_SECRET`, never `BITHUMAN_API_SECRET`, so the plugin cannot find it and copy it into the room; `agent.py` refuses to start while `BITHUMAN_API_SECRET` is set.
`OPENAI_API_KEY`	—	Your OpenAI key.
`BITHUMAN_AVATAR`	`wise-pup`	Which avatar (table above).
`BITHUMAN_REALTIME_MODEL`	`gpt-realtime-2.1-mini`	The OpenAI Realtime model.
`BITHUMAN_VOICE`	`coral`	Any OpenAI Realtime voice.
`BITHUMAN_INSTRUCTIONS`	a short assistant prompt	The agent’s system prompt.
`LIVEKIT_URL`, `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET`	`ws://localhost:7880`, `devkey`, `secret`	Your LiveKit server (`livekit-server --dev`).

Cost: session time, talking or idle, bills bitHuman credits; OpenAI bills your own key (Pricing). Stops mid-sentence when you talk over it: Barge-in. Something wrong: Troubleshooting.