Skip to main content
A simple first example that works reliably.

​
Quick Start

1

Install

pip install bithuman --upgrade opencv-python sounddevice
2

Set environment

export BITHUMAN_API_SECRET="your_secret"
export BITHUMAN_MODEL_PATH="/path/to/model.imx"
export BITHUMAN_AUDIO_PATH="/path/to/audio.wav"  # optional
3

Run

python examples/avatar-with-audio-clip.py
View source code on GitHub
4

Controls

  • Press 1 — Play audio with avatar
  • Press 2 — Stop playback
  • 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 examples/avatar-with-audio-clip.py \
  --model /path/to/model.imx \
  --audio-file /path/to/audio.wav \
  --api-secret your_secret

# Use JWT token instead of API secret
python examples/avatar-with-audio-clip.py \
  --token your_jwt_token \
  --model /path/to/model.imx
OptionDescription
--modelPath to .imx model file
--audio-filePath to audio file
--api-secretYour bitHuman API secret
--tokenJWT token (alternative to API secret)
--insecureDisable SSL verification (dev only)

​
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