Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.bithuman.ai/llms.txt

Use this file to discover all available pages before exploring further.

A simple first example that works reliably.

​
Quick Start

1

Install

pip install bithuman --upgrade sounddevice
The SDK includes opencv-python-headless automatically. Do not install opencv-python (full) separately — it conflicts with PyAV.
2

Set environment

export BITHUMAN_API_SECRET="your_secret"
export BITHUMAN_MODEL_PATH="/path/to/model.imx"
3

Run

git clone https://github.com/bithuman-product/bithuman-examples.git
cd bithuman-examples/essence-selfhosted
python quickstart.py --model /path/to/model.imx --audio-file speech.wav
View source code on GitHub
4

Controls

  • Press q — Quit

​
What It Does

  1. Loads your audio file (WAV, MP3, M4A supported)
  2. Creates synchronized avatar animation
  3. Shows real-time video in OpenCV window
  4. Plays audio through speakers with sounddevice
Key features:
  • Smooth audio playback with buffering
  • Real-time video display at 25 FPS
  • Keyboard controls for interaction
  • Supports multiple audio formats

​
Command Line Options

# Use specific files
python quickstart.py \
  --model /path/to/model.imx \
  --audio-file /path/to/audio.wav \
  --api-secret your_secret
OptionDescription
--modelPath to .imx model file
--audio-filePath to audio file (WAV, MP3, M4A)
--api-secretYour bitHuman API secret

​
Common Issues

ProblemSolution
No audio playingInstall sounddevice: pip install sounddevice. Try WAV format.
Avatar not loadingVerify BITHUMAN_API_SECRET and BITHUMAN_MODEL_PATH.
Video choppyClose other applications using GPU/CPU.
Controls not workingClick on the OpenCV window to focus it.

​
Technical Details

ComponentSpecification
Audio sample rate16kHz (auto-converted)
Audio channelsMono (stereo auto-converted)
Video resolution512x512 pixels
Frame rate25 FPS
Audio formatsWAV, MP3, M4A, FLAC

​
Next Steps

Live Microphone

Real-time interaction with your voice

AI Conversation

Full OpenAI voice chat with avatar