React Talking Head Avatar

A professional React component for interactive 3D talking head avatars with TTS, lip-sync, and gesture support.

Features

• 🎭 3D Avatar Rendering - Beautiful 3D avatar display with professional styling
• 🗣️ Text-to-Speech - Support for multiple TTS services (ElevenLabs, Azure, Google Cloud, Browser)
• 👄 Lip Sync - Realistic lip synchronization with speech
• 🎬 Gestures & Animations - Body movements and facial expressions
• 🎨 Customizable - Flexible configuration options
• 📱 Responsive - Works on desktop and mobile devices
• 🔧 TypeScript - Full TypeScript support

Installation

npm install react-talking-head-avatar

Quick Start

import React, { useRef } from 'react';
import TalkingHeadAvatar from 'react-talking-head-avatar';

const App = () => {
  const avatarRef = useRef(null);

  const avatarConfig = {
    avatarUrl: '/path/to/your/avatar.glb',
    ttsService: 'elevenlabs',
    ttsApiKey: 'your-api-key',
    ttsVoice: '21m00Tcm4TlvDq8ikWAM', // Rachel
    mood: 'happy',
    bodyMovement: 'gesturing'
  };

  const handleSpeak = () => {
    if (avatarRef.current) {
      avatarRef.current.speakText("Hello! I'm your talking avatar.");
    }
  };

  return (
    <div style={{ width: '400px', height: '500px' }}>
      <TalkingHeadAvatar
        ref={avatarRef}
        avatarConfig={avatarConfig}
        onAvatarReady={() => console.log('Avatar ready!')}
      />
      <button onClick={handleSpeak}>Speak</button>
    </div>
  );
};

export default App;

Configuration

AvatarConfig

| Property | Type | Default | Description | |----------|------|---------|-------------| | avatarUrl | string | /avatars/brunette.glb | Path to your 3D avatar GLB file | | avatarBody | 'M' | 'F' | 'F' | Avatar body type | | ttsService | 'elevenlabs' | 'azure' | 'google-cloud' | 'browser' | 'browser' | TTS service to use | | ttsApiKey | string | - | API key for TTS service | | ttsEndpoint | string | - | Custom TTS endpoint | | ttsVoice | string | - | Voice ID for TTS service | | ttsLang | string | 'en' | Language for TTS | | mood | string | 'neutral' | Avatar mood | | bodyMovement | string | 'idle' | Body movement type | | movementIntensity | number | 0.5 | Movement intensity (0-1) | | showFullAvatar | boolean | false | Show full body avatar |

API Methods

Access avatar methods through the ref:

const avatarRef = useRef(null);

// Speech
await avatarRef.current.speakText("Hello world!");
avatarRef.current.stopSpeaking();

// Mood and Movement
avatarRef.current.setMood("happy");
avatarRef.current.setBodyMovement("dancing");
avatarRef.current.setMovementIntensity(0.8);

// Gestures
await avatarRef.current.playGesture("wave");
avatarRef.current.stopGesture();

// Display
avatarRef.current.setShowFullAvatar(true);

TTS Services

ElevenLabs

const config = {
  ttsService: 'elevenlabs',
  ttsApiKey: 'your-elevenlabs-api-key',
  ttsVoice: '21m00Tcm4TlvDq8ikWAM' // Rachel
};

Azure Cognitive Services

const config = {
  ttsService: 'azure',
  ttsApiKey: 'your-azure-api-key',
  ttsEndpoint: 'https://your-region.tts.speech.microsoft.com/',
  ttsVoice: 'en-US-AriaNeural'
};

Google Cloud TTS

const config = {
  ttsService: 'google-cloud',
  ttsApiKey: 'your-google-api-key',
  ttsVoice: 'en-US-Wavenet-D'
};

Browser TTS (Default)

const config = {
  ttsService: 'browser',
  ttsVoice: 'Google US English'
};

Events

<TalkingHeadAvatar
  onAvatarReady={() => console.log('Avatar loaded!')}
  onError={(error) => console.error('Avatar error:', error)}
  onLoading={(progress) => console.log('Loading:', progress + '%')}
/>

Styling

The component accepts standard React styling props:

<TalkingHeadAvatar
  className="my-avatar"
  style={{ 
    width: '100%', 
    height: '500px',
    borderRadius: '12px'
  }}
/>

License

MIT

Support

For issues and feature requests, please visit our GitHub repository.