Embed a real-time talking avatar in your web app with one provider, one component, and one hook.
The React SDK lets your users talk to an AI avatar — or have the avatar speak text and audio you provide — directly in the browser. You add three things to your app and the SDK takes care of the live connection, the microphone, audio playback, and lip-sync.
If you haven't installed it yet, start with Installation, or follow the Quickstart for a step-by-step setup.
<AvatarProvider />Wrap your app once. It opens the connection and holds the session so every component below it can use the same avatar.
<Avatar />Displays the character and animates its mouth in time with speech. Drop it anywhere inside the provider and give it a size.
useAvatar()Control the avatar from your own UI: start and stop sessions, send text or audio, interrupt speech, and read live status.
useAvatarEvent()Run code when something happens — the session starts, the avatar speaks, an error occurs — with cleanup handled for you.
Pick the mode that matches what you're building. You set it once in your config; everything else works the same.
| Mode | What it does | Best for |
|---|---|---|
call | Two-way voice conversation in real time | Support agents, virtual companions |
tts | You send text, the avatar speaks it | Narration, scripted announcements |
audio | You send audio, the avatar lip-syncs to it | Custom voice providers, recordings |
player | Plays a clip you made ahead of time — no server | Landing pages, demos, cached replies |
See Modes for a full walkthrough of each one.
Beyond the three building blocks, the SDK ships a set of things you would otherwise build yourself. Each is off or sensibly defaulted, and each can be replaced with your own UI.
Every config object, hook return value, event, and error is fully typed, so you get autocomplete and type-checking as you build. Import types directly from the package:
TypeScript is optional, but recommended — the autocomplete on the config object alone saves a lot of trips to these docs.