@marcosremar/talking-head-avatar

A React component for rendering interactive 3D avatars with integrated chat, voice recognition, and lip-sync capabilities.

Features

• 🎭 3D Avatar with facial expressions and animations
• 🎤 Voice input support with Voice Activity Detection
• 💬 Text and voice chat integration
• 👄 Real-time lip-sync animation
• 🎨 Customizable themes and styling
• 📱 Mobile-friendly and responsive

Installation

npm install @marcosremar/talking-head-avatar

or

yarn add @marcosremar/talking-head-avatar

Quick Start

import { TalkingHeadAvatar } from '@marcosremar/talking-head-avatar';

function App() {
  return (
    <div style={{ width: '100%', height: '600px' }}>
      <TalkingHeadAvatar 
        apiUrl="https://your-backend-api.com"
        initialMessage="Hello! How can I help you today?"
      />
    </div>
  );
}

Advanced Usage

With Custom Configuration

import { TalkingHeadProvider, Avatar, UI } from '@marcosremar/talking-head-avatar';
import { Canvas } from '@react-three/fiber';

function App() {
  return (
    <TalkingHeadProvider 
      config={{
        apiUrl: 'https://your-api.com',
        assetsUrl: 'https://your-cdn.com/assets',
        theme: 'dark',
        onError: (error) => console.error('Avatar error:', error)
      }}
    >
      <div style={{ width: '100%', height: '600px' }}>
        <Canvas>
          <Avatar />
        </Canvas>
        <UI />
      </div>
    </TalkingHeadProvider>
  );
}

Using Hooks

import { TalkingHeadProvider, useTalkingHead } from '@marcosremar/talking-head-avatar';

function ChatInterface() {
  const { sendMessage, sendVoiceMessage, loading, messages } = useTalkingHead();
  
  const handleSendMessage = async () => {
    const response = await sendMessage('Hello!');
    console.log('Avatar response:', response);
  };
  
  return (
    <div>
      <button onClick={handleSendMessage} disabled={loading}>
        Send Message
      </button>
    </div>
  );
}

Props

TalkingHeadAvatar

| Prop | Type | Default | Description | |------|------|---------|-------------| | apiUrl | string | http://localhost:4001 | Backend API URL | | assetsUrl | string | /models | URL for 3D model assets | | initialMessage | string | - | Initial message from avatar | | onMessage | function | - | Callback when avatar sends a message | | onError | function | - | Error handler | | theme | string | 'light' | Theme ('light' or 'dark') | | cameraZoom | boolean | false | Enable camera zoom | | showControls | boolean | true | Show UI controls | | enableVoice | boolean | true | Enable voice input | | className | string | '' | Additional CSS classes | | style | object | {} | Additional inline styles |

Backend Requirements

The component expects a backend API with the following endpoints:

• POST /chat - Text chat endpoint
• POST /voice-chat - Voice chat endpoint

Expected Response Format

{
  "message": "Avatar's response text",
  "audio": "base64_encoded_audio",
  "lipsync": {
    "mouthCues": [
      { "start": 0, "end": 0.1, "value": "A" }
    ]
  },
  "facialExpression": "smile",
  "animation": "Talking"
}

Styling

The component uses minimal default styling and can be customized using:

• The className prop for custom CSS classes
• The style prop for inline styles
• CSS variables for theming

/* Example custom styling */
.talking-head-container {
  border-radius: 20px;
  overflow: hidden;
  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.2);
}

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Note: Voice features require browser support for Web Audio API and getUserMedia.

License

MIT © Marcos Remar

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and feature requests, please create an issue.