Talking Head Avatar

A professional, reusable React component for 3D avatars with advanced text-to-speech, lip-sync, and animation capabilities. Perfect for educational applications, virtual assistants, and interactive experiences.

Features

• 🎭 3D Avatar Rendering - High-quality GLTF/GLB avatar support
• 🗣️ Text-to-Speech - Multiple TTS services (Edge, Google, Azure, Browser)
• 👄 Automatic Lip-sync - Real-time mouth animation synchronized with speech
• 🎨 Rich Animations - Code-based and FBX animation support
• 🎮 Interactive Controls - Programmatic control via React refs
• 📱 Responsive Design - Full viewport coverage with no scrollbars
• 🔧 Highly Customizable - Extensive configuration options
• 📦 TypeScript Support - Full type definitions included
• 🎯 Production Ready - Optimized for performance and reliability

Installation

npm install @your-username/talking-head-avatar

Quick Start

import React, { useRef } from 'react';
import { TalkingHeadAvatar } from '@your-username/talking-head-avatar';

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

  const handleSpeak = () => {
    avatarRef.current?.speakText("Hello! I'm your AI assistant.");
  };

  return (
    <div>
      <TalkingHeadAvatar
        ref={avatarRef}
        avatarUrl="/path/to/your/avatar.glb"
        onReady={() => console.log('Avatar ready!')}
      />
      <button onClick={handleSpeak}>Make Avatar Speak</button>
    </div>
  );
}

Advanced Usage

Custom Configuration

import { TalkingHeadAvatar, createTalkingHeadConfig } from '@your-username/talking-head-avatar';

const customConfig = createTalkingHeadConfig({
  avatar: {
    url: "/avatars/my-avatar.glb",
    mood: "happy",
    bodyMovement: "gesturing",
    position: { x: 0, y: 0.5, z: 0 }
  },
  tts: {
    service: "edge",
    voice: "en-US-AriaNeural",
    timingAdjustment: 1.1
  },
  animations: {
    useFBXForTeaching: true,
    teachingAnimation: {
      fbx: "/animations/teaching.fbx"
    }
  }
});

function App() {
  return (
    <TalkingHeadAvatar
      config={customConfig}
      fbxAnimations={[
        "/animations/dance.fbx",
        "/animations/wave.fbx",
        "/animations/celebration.fbx"
      ]}
    />
  );
}

Programmatic Control

import React, { useRef, useEffect } from 'react';
import { TalkingHeadAvatar } from '@your-username/talking-head-avatar';

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

  useEffect(() => {
    const avatar = avatarRef.current;
    if (avatar) {
      // Set avatar mood
      avatar.setMood("excited");
      
      // Play animation
      avatar.playAnimation("dance");
      
      // Speak with lip-sync
      avatar.speakText("Welcome to our application!");
      
      // Set body movement
      avatar.setBodyMovement("gesturing");
    }
  }, []);

  return (
    <TalkingHeadAvatar
      ref={avatarRef}
      avatarUrl="/avatars/assistant.glb"
      onReady={(talkingHead) => {
        console.log('Avatar initialized:', talkingHead);
      }}
    />
  );
}

API Reference

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | config | Partial<TalkingHeadConfig> | {} | Avatar configuration object | | avatarUrl | string | - | Override avatar GLB/GLTF file path | | fbxAnimations | string[] | [] | Array of FBX animation file paths | | onReady | (talkingHead: any) => void | - | Callback when avatar is ready | | onError | (error: Error) => void | - | Error callback | | onLoading | (progress: number) => void | - | Loading progress callback | | className | string | - | CSS class name | | style | React.CSSProperties | - | Inline styles | | children | React.ReactNode | - | Child components |

Ref Methods

| Method | Parameters | Description | |--------|------------|-------------| | speakText | (text: string) => void | Make avatar speak with lip-sync | | stopSpeaking | () => void | Stop current speech | | setMood | (mood: string) => void | Set avatar mood | | setBodyMovement | (movement: string) => void | Set body movement animation | | playAnimation | (name: string, disablePositionLock?: boolean) => void | Play animation | | playReaction | (reaction: string) => void | Play reaction animation | | playCelebration | () => void | Play celebration animation | | playRandomDance | () => void | Play random dance animation | | setShowFullAvatar | (show: boolean) => void | Toggle full body mode | | setMovementIntensity | (intensity: number) => void | Set movement intensity (0-1) | | setTimingAdjustment | (adjustment: number) => void | Adjust lip-sync timing | | lockAvatarPosition | () => void | Lock avatar position | | unlockAvatarPosition | () => void | Unlock avatar position |

Configuration Types

interface TalkingHeadConfig {
  avatar: {
    url: string;
    body?: 'F' | 'M';
    mood?: 'happy' | 'neutral' | 'sad' | 'excited' | 'curious' | 'celebrating';
    ttsLang?: string;
    ttsService?: 'edge' | 'google' | 'azure' | 'browser';
    ttsVoice?: string;
    bodyMovement?: 'idle' | 'gesturing' | 'dancing' | 'walking' | 'excited' | 'happy';
    movementIntensity?: number;
    showFullAvatar?: boolean;
    showControls?: boolean;
    position?: { x?: number; y?: number; z?: number; };
  };
  tts: {
    service: 'edge' | 'google' | 'azure' | 'browser';
    voice: string;
    timingAdjustment?: number;
    voices?: Record<string, string>;
    endpoint?: string;
    apiKey?: string;
  };
  animations: {
    useFBXForTeaching?: boolean;
    teachingAnimation?: { fbx?: string; codeBased?: string; };
    feedbackAnimations?: { correct?: string; wrong?: string; };
    celebrationAnimations?: { lessonComplete?: string; curriculumComplete?: string; };
  };
  ui: {
    showProgressBar?: boolean;
    showStatusIndicators?: boolean;
    showControlButtons?: boolean;
    showVoiceSelector?: boolean;
    showTimingControls?: boolean;
    showTeachingModeToggle?: boolean;
    showFullBodyIndicator?: boolean;
    autoStartTeaching?: boolean;
  };
  curriculum: {
    maxRetries?: number;
    teachingDuration?: number;
    questionTransitionDelay?: number;
  };
}

Avatar Requirements

GLTF/GLB Files

• Must include morph targets for lip-sync
• Recommended bone structure for animations
• Optimized for web (compressed textures)

FBX Animations

• Compatible with avatar skeleton
• Include position and rotation tracks
• Optimized file sizes

Browser Support

• Chrome 80+
• Firefox 75+
• Safari 13+
• Edge 80+

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Documentation: Full Documentation

Changelog

v1.0.0

• Initial release
• 3D avatar rendering with GLTF/GLB support
• Text-to-speech with multiple services
• Automatic lip-sync
• Animation system (code-based and FBX)
• TypeScript support
• Comprehensive configuration options