> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talking-avatar.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# TalkingAvatar

> The Open Source 3D talking avatar: loads a .glb avatar and lip syncs it to any audio in the browser.

```js theme={null}
import { TalkingAvatar, DEFAULT_MODEL_URL } from "@interviewflowai/talking-avatar";
```

## new TalkingAvatar(options)

```js theme={null}
const avatar = new TalkingAvatar({
  container: document.getElementById("avatar"),
  avatarUrl: "https://example.com/avatar.glb",
});
```

**container** `HTMLElement` *required*

The element the avatar fills. It needs a width and height; the canvas follows its size.

**avatarUrl** `string` *required*

Your `.glb` avatar. See [3D avatars](https://docs.talking-avatar.dev/open-source/avatars.md).

**morphTargets** `Record\<string, string | string[]\>`

Your avatar's morph names, if they aren't the standard ones. See [Other morph names](https://docs.talking-avatar.dev/open-source/avatars.md#other-morph-names).

**modelUrl** `string` (default: DEFAULT\_MODEL\_URL)

Where to load `viseme-model.bin` from. See [Self-host the model](https://docs.talking-avatar.dev/open-source/self-hosting-the-model.md).

**streamDelayMs** `number` (default: 150)

Delay before an attached stream plays. Lower means less latency and rougher lip sync.

**onError** `(error: Error) =\> void` (default: console.error)

Errors from background work (avatar loading, stream analysis).

## Members

| Member | Returns | Description |
| - | - | - |
| `ready` | `Promise<void>` | Resolves when the first avatar is on screen; rejects if it fails to load. |
| `setAvatar(url, morphTargets?)` | `Promise<void>` | Loads a different avatar. Resolves when it's on screen. |
| `attachStream(stream)` | `Promise<void>` | Plays and lip syncs a `MediaStream`. Replaces any attached stream. Rejects if it has no audio track. |
| `detachStream()` | `void` | Stops the attached stream. It doesn't stop the source track. |
| `speak(audio)` | `Promise<void>` | Plays and lip syncs a clip (a URL string, `ArrayBuffer` or `Blob`). Resolves when it ends or is stopped. |
| `stopSpeaking()` | `void` | Stops the current clip. |
| `setStatus(status)` | `void` | Behaviour while not speaking: `"listening"` (default) or `"thinking"`. Speaking is detected from the audio. |
| `dispose()` | `void` | Releases the canvas, WebGL resources and audio. The instance can't be reused. |

## DEFAULT\_MODEL\_URL

`string`: this package version's copy of the model on jsDelivr.

## Example

```js theme={null}
const avatar = new TalkingAvatar({
  container: document.getElementById("avatar"),
  avatarUrl: "/avatar.glb",
  modelUrl: "/sdk/viseme-model.bin",
  onError: console.error,
});

await avatar.ready;

document.getElementById("play").onclick = async () => {
  avatar.setStatus("thinking");
  const audio = await fetch("/api/tts?text=Hello").then((r) => r.blob());
  await avatar.speak(audio);
  avatar.setStatus("listening");
};

// When you remove this view:
// avatar.dispose();
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.