Pipecat

Put BitHumanVideoService after your TTS service: the bot’s speech goes in, and lip-synced avatar video with the matching audio comes out.

Before you start

pipecat-bithuman is a community integration for Pipecat, maintained by bitHuman, not by the Pipecat team. The avatar renders inside your bot’s own process through the Python SDK, on your own machine. Your pipeline keeps its own speech-to-text, LLM and TTS services.

Install

python3 -m venv .venv
source .venv/bin/activate
pip install "pipecat-bithuman[expression-2]"

The package brings Pipecat (pipecat-ai 1.12.0 or newer) and the bitHuman Python SDK (bithuman) with it.

Authenticate

Set BITHUMAN_API_SECRET in the shell that runs the bot, or pass api_secret= to BitHumanVideoService. The service never logs the secret and removes it from error text. Name the avatar file with model_path=, or set BITHUMAN_MODEL_PATH.

The avatar opens on StartFrame and closes on EndFrame, CancelFrame or cleanup.

Run your first avatar

The package’s demo script sends a WAV file through a Pipecat pipeline as TTSAudioRawFrame chunks, as a TTS service would, and writes the avatar frames that come out to an MP4. In the virtual environment from Install:

export BITHUMAN_API_SECRET="<your API secret>"
git clone https://github.com/bithuman-product/pipecat-bithuman
cd pipecat-bithuman
curl -fL -o wise-pup.imx "https://api.bithuman.ai/v1/agent/A23WJF0199/model/download?model=expression-2"
curl -fsSLo speech.wav https://docs.bithuman.ai/samples/speech.wav
BITHUMAN_MODEL_PATH=wise-pup.imx python examples/render_demo.py speech.wav demo.mp4
# → prints the frame count and size, and demo.mp4 shows wise-pup speaking the sample

To see barge-in, add --interrupt-at 10 --repeat 2: the reply is interrupted after 10 s, and a new one follows. The 37-second demo in the repository is that run with wise-pup.

Performance

The avatar renders through the Python SDK inside your bot’s process. The Python SDK’s speed on each machine: