JavaScript / TypeScript SDK

A cloud client SDK for browser and Node — @bithuman/sdk talks to a served or cloud avatar over LiveKit. Preview.

Overview

@bithuman/sdk is the JavaScript / TypeScript client. It is not a local avatar engine — the engine runs on the server. The SDK talks to a self-hosted avatar server (started with bithuman-serve) or the bitHuman cloud over LiveKit and handles dispatch, the room join, audio push, and an async-iterator over avatar frames.

Warning This SDK is Preview (v0.1). Auth, dispatch, and the session lifecycle work today. Frame payloads coming through the LiveKit data channel are a placeholder in this release — treat frame.pixels as opaque bytes. v0.2 will subscribe to the avatar participant’s video track and yield real RGBA frames.

The API shape mirrors the Python SDK’s AsyncBithuman, so docs and examples translate 1:1.

Install

Note — not yet available. @bithuman/sdk is not published to npm (npm install @bithuman/sdk 404s today) and there is no public source package to build from yet — the SDK monorepo currently ships the Python and Swift rails only. The code on this page shows the shape the published client will take; track the changelog for the release. To build a browser or Node integration today, drive a served or cloud avatar over LiveKit — that is the same transport this client wraps.

When it ships, the install will be:

npm install @bithuman/sdk   # not available yet — see the note above

Auth: provide your API secret as apiSecret. Get one at Developer → API Keys.

Quick start

import { AsyncBithuman } from "@bithuman/sdk";

const avatar = await AsyncBithuman.create({
  apiSecret: process.env.BITHUMAN_API_SECRET!,
  avatarId: "modern-court-jester",
});

await avatar.pushAudio(audioChunk, { lastChunk: true });
for await (const frame of avatar.run()) {
  // render frame.pixels to canvas / save to disk (opaque bytes in v0.1)
}
await avatar.stop();

This is the cloud-client expression of the audio-streaming push/drain loop: push 16-bit PCM, iterate frames, stop.

What it does

A thin client over LiveKit. It handles:

/launch dispatch with your api-secret
LiveKit room join (browser and Node)
Audio push and end-of-speech signaling
An async-iterator over avatar frames

Because the engine runs server-side, you need a reachable bithuman-serve instance or a bitHuman cloud avatar. For self-hosting the server, see the deployment guides; for a managed avatar, see LiveKit.

Errors

Every exception extends BithumanError and carries a stable code and a docs URL. The hierarchy mirrors the Python SDK:

import { ModelNotFoundError, BithumanError } from "@bithuman/sdk";

try {
  await AsyncBithuman.create({ apiSecret, avatarId: "bad" });
} catch (e) {
  if (e instanceof BithumanError) {
    console.log(e.code);    // "model_not_found"
    console.log(e.docsUrl); // https://docs.bithuman.ai/api/errors#model_not_found
  }
}

BithumanError
- TokenError
  - TokenExpiredError, TokenValidationError, TokenRequestError
  - AccountStatusError (HTTP 402 / 403)
- ModelError
  - ModelNotFoundError, ModelLoadError, ModelSecurityError
- RuntimeNotReadyError

Examples

examples/browser/ — mic → avatar → canvas (bundler required)
examples/node/ — WAV file → avatar → frames on disk