# Run a talking avatar on your laptop

URL: https://docs.bithuman.ai/build/how-to/laptop-avatar

> Render a lip-synced avatar on a Linux, Mac or Windows laptop's processor.

## What you'll build

Install the bitHuman CLI on a Linux laptop (x86_64 or arm64) or an Apple silicon Mac, sign in, and run `bithuman render wise-pup speech.wav -o out.mp4` for a video or `bithuman run wise-pup` to talk to it. Essence 2 and Expression 2 render on the laptop; on Linux they need no GPU. On Windows 11 x86_64, the Python package renders both on the CPU.

The published speed was measured on a desktop CPU and an Apple M4, not on a laptop, so the steps time your own machine:

| Configuration | Hardware | Essence 2 | Expression 2 |
|---|---|---|---|
| Linux · CLI · CPU only (no GPU) | Intel Core i7-13700F (x86_64) | 2.0× real time | 2.2× real time |
| macOS · Python | Apple M4 | 6.9× real time | 8.4× real time |
| Windows · Python · CPU only (no GPU) | Intel Core i7-13700F (x86_64), 8 threads | 1.2× real time | 1.0× real time |

× real time: seconds of video rendered per second; 1.0× or more holds a live conversation ([method](https://docs.bithuman.ai/performance)).

You need an [API secret](https://docs.bithuman.ai/start/api-secret) or a bitHuman sign-in, on the Creator plan or higher.

## Steps

### Check your laptop

| Laptop | Use | Check |
|---|---|---|
| Linux on x86_64 or arm64 | the [CLI](https://docs.bithuman.ai/platforms/cli) or the [Python SDK](https://docs.bithuman.ai/platforms/python) | `uname -sm` |
| macOS 14 or newer on Apple silicon | the CLI or the Python SDK | `uname -sm` prints `Darwin arm64` |
| Windows 11 on x86_64 | the [Python SDK on Windows](https://docs.bithuman.ai/platforms/windows); the CLI on Windows renders in the cloud | `python -c "import platform; print(platform.system(), platform.machine())"` prints `Windows AMD64` |

Intel Macs and Windows on Arm have no package.

Expected:

One row that matches your laptop.

### Install and sign in

On Linux or macOS, install the CLI and sign in:

```bash
# Linux, x86_64 or arm64 (Debian/Ubuntu)
sudo apt install -y ffmpeg python3-venv
curl -fsSL https://install.bithuman.ai | sh
# macOS (Apple silicon): also installs ffmpeg, livekit-server and Python
brew tap bithuman/bithuman https://gitlab.com/bithuman/sdk/homebrew-bithuman && brew install bithuman/bithuman/bithuman-cli

bithuman login            # opens a browser and stores a credential for this device
bithuman account          # exit 0 when signed in
```

On Windows 11, in PowerShell:

```powershell
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install "bithuman[expression-2]"
$env:BITHUMAN_API_SECRET = "<your API secret>"
```

Expected:

`bithuman account` exits 0 on Linux or macOS; on Windows, `pip` finishes with no error.

### Render the sample and time it

On Linux or macOS:

```bash
curl -fsSLo speech.wav https://docs.bithuman.ai/samples/speech.wav
time bithuman render wise-pup speech.wav -o out.mp4
# → out.mp4: 416×720, 300 frames, 15.0 s
```

On Windows 11:

```powershell
curl.exe -fL -o wise-pup.imx "https://api.bithuman.ai/v1/agent/A23WJF0199/model/download?model=expression-2"
curl.exe -fsSLo speech.wav https://docs.bithuman.ai/samples/speech.wav
Measure-Command { python -c "import bithuman; bithuman.open('wise-pup.imx').render('speech.wav', out_mp4='out.mp4')" }
```

The sample is 15 seconds of speech. Run the render twice, because the first run also downloads the avatar. A second run that takes less than 15 seconds means your laptop renders Expression 2 faster than real time. For the photoreal model, render `sofia-ramirez` the same way.

Expected:

`out.mp4`: `wise-pup` speaking the sample, 416×720, with its lips in sync.

### Talk to it live

On Linux or macOS, `bithuman run` starts a local LiveKit server, a voice agent and the avatar, then opens the page in your browser. It needs Python 3.11 or newer for its voice agent:

```bash
bithuman run wise-pup
# → open the printed http://127.0.0.1:8088/<CODE> and allow the microphone
```

The voice runs on OpenAI Realtime, with your `OPENAI_API_KEY` or on your bitHuman account ([voice settings](https://docs.bithuman.ai/platforms/cli/voice#voice-settings)). For a conversation that also runs on the laptop, use the [local conversation brain](https://docs.bithuman.ai/platforms/cli/local-brain): `BITHUMAN_LOCAL=1 bithuman run sofia-ramirez`. On Windows, stream audio into `AsyncBithuman` from your own code ([Python: Integrate into your app](https://docs.bithuman.ai/platforms/python/app#integrate-into-your-app)).

Expected:

Say "hi": the avatar answers out loud with its lips in sync, and stops when you talk over it.

## How it works

*Diagram: Your servers (self-hosted).* Self-hosted, the avatar renders on your own Mac or Linux machine and its audio and video stay there. The conversation runs where you choose: the CLI's local conversation brain, your own services, or bitHuman's. For the rendering, bitHuman receives a credential check, the avatar download and usage reports with no audio, video, images or conversation text.

The avatar renders on the laptop, from the audio to the frames, so its audio and video stay there. A session checks your credential when it starts, keeps rendering through a network drop of up to 5 minutes, and sends usage reports with no audio, video, images or conversation text. Rendering on your own hardware bills at the self-hosted rate ([pricing](https://docs.bithuman.ai/pricing)).

## Make it your own

- **Your own avatar:** [create one](https://docs.bithuman.ai/build/create-avatar) from a portrait, then `bithuman pull <AGENT_CODE>` and render it the same way.
- **Your own words:** any audio file `ffmpeg` reads, from a recording or a text-to-speech tool: [Talking video](https://docs.bithuman.ai/build/talking-video).
- **A screen that runs all day:** a Linux PC with no GPU: [CPU only (no GPU)](https://docs.bithuman.ai/deploy/cpu).

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| `bithuman render` exits with code 77 | no credential | run `bithuman login`, or export `BITHUMAN_API_SECRET` |
| `pip` finds no wheel on Windows | 32-bit Python, Windows on Arm, or Python outside 3.10–3.14 | install 64-bit Python 3.10–3.14 on an x86_64 PC |
| `'curl' is not recognized` in PowerShell | `curl` in Windows PowerShell 5.1 is an alias | type `curl.exe`, as above |
| The second render takes longer than the speech | the laptop's processor is slower than the measured hardware | render files with `bithuman render`, or use the [bitHuman cloud](https://docs.bithuman.ai/deploy/cloud) for live sessions |

More on [CLI: Troubleshooting](https://docs.bithuman.ai/platforms/cli/troubleshooting).