https://github.com/khaledalam/avatoon
React Three Fiber component for animated avatars with lip-sync and head motion.
https://github.com/khaledalam/avatoon
3d animation avatar avatars glb lip-sync npm npm-package r3f react three three-js threejs webgl
Last synced: 3 months ago
JSON representation
React Three Fiber component for animated avatars with lip-sync and head motion.
- Host: GitHub
- URL: https://github.com/khaledalam/avatoon
- Owner: khaledalam
- License: mit
- Created: 2025-05-07T11:11:59.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-09T06:32:12.000Z (about 1 year ago)
- Last Synced: 2025-10-16T00:03:34.329Z (8 months ago)
- Topics: 3d, animation, avatar, avatars, glb, lip-sync, npm, npm-package, r3f, react, three, three-js, threejs, webgl
- Language: HTML
- Homepage: https://www.npmjs.com/package/avatoon
- Size: 30.8 MB
- Stars: 4
- Watchers: 1
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 🧠 Avatoon
[![npm package][npm-img]][npm-url]
[![Build Status][build-img]][build-url]
[![Issues][issues-img]][issues-url]
[![Code Coverage][codecov-img]][codecov-url]
**Avatoon** is a lightweight React Three Fiber component for rendering animated 3D avatars with real-time viseme-driven lip-sync. It supports lifelike head movements, morph target control, and optional goal-based gestures (e.g., flexing, sleeping), making it ideal for voice assistants, interactive characters, or storytelling apps.
[demo video](https://youtu.be/9ODqu2EZvtw)
## ✨ Features
- 🎤 Real-time lip-sync using phoneme-viseme mapping
- 🧍 Subtle head motion animation while talking
- 🌐 GLTF model support via `useGLTF`
- ⚛️ Plug-and-play with React Three Fiber + Drei
- 🎯 Goal-based gestures like "Muscle" or "Sleep"
## 📦 Installation
```bash
npm install avatoon
```
## 🚀 Usage
```js
import { Avatoon } from "avatoon";
export default App = () => {
const visemeJson = {
visemes: [{
{ "time": 0, "viseme": "X" },
{ "time": 1.3, "viseme": "A" },
{ "time": 1.367, "viseme": "C" },
}],
audio_base64: '',
};
return (
console.log("Render Completed!")}
visemeJson={visemeJson}
/>
);
}
```
### To run example:
```bash
npm run example
```
## 🧩 API
### `Avatoon(props)`
| Prop | Type | Default | Description |
| --------------------- | ------------ | ------------ | ------------------------------------------------------ |
| `glbUrl` | `string` | *(required)* | URL to the `.glb` avatar file (T1 or T2) |
| `goal` | `string` | `"Normal"` | Goal-based motion preset: `"Muscle"`, `"Sleep"`, etc. |
| `onRenderComplete` | `() => void` | `undefined` | Callback fired when avatar finishes rendering |
| `visemeJson` | `VisemeData` | `undefined` | JSON structure for syncing visemes with audio playback |
| `showPlayVoiceButton` | `boolean` | `false` | If true, renders a play/stop voice button in the scene |
## 👤 Avatar Types
- T1 (Static Face - Realistic)
- Most photorealistic
- No facial morphing
- Lightweight
- 
- T2 (Blendshape Face - Expressive)
- Separate eyeballs and mouth
- Supports morph targets / ARKit visemes
- Slightly less realistic but animatable
- 
## 📘 Types
```ts
interface VisemeData {
visemes: Array<{ time: number; viseme: string | null }>;
audio_base64?: string;
}
```
## 🤝 Contribution
Pull requests are welcome! If you'd like to suggest improvements or fix issues, feel free to fork and submit.
## 🛡️ Author
**Khaled Alam**
📧 [khaledalam.net@gmail.com](mailto:khaledalam.net@gmail.com)
🌍 [Website](https://khaledalam.net/) | [LinkedIn](https://www.linkedin.com/in/khaledalam/) | [X(Twitter)](https://x.com/khaledalamxyz)
[build-img]:https://github.com/khaledalam/avatoon/actions/workflows/release.yml/badge.svg
[build-url]:https://github.com/khaledalam/avatoon/actions/workflows/release.yml
[npm-img]:https://img.shields.io/npm/v/avatoon
[npm-url]:https://www.npmjs.com/package/avatoon
[issues-img]:https://img.shields.io/github/issues/khaledalam/avatoon
[issues-url]:https://github.com/khaledalam/avatoon/issues
[codecov-img]:https://codecov.io/gh/khaledalam/avatoon/branch/main/graph/badge.svg
[codecov-url]:https://codecov.io/gh/khaledalam/avatoon