@marcosremar/talking-head-avatar/README.md

React 3D avatar component with integrated chat and lip-sync capabilities

# @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

```bash
npm install @marcosremar/talking-head-avatar
```

or

```bash
yarn add @marcosremar/talking-head-avatar
```

## Quick Start

```jsx
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

```jsx
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

```jsx
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

```json
{
  "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

```css
/* 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](https://github.com/marcosremar)

## Contributing

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

## Support

For issues and feature requests, please [create an issue](https://github.com/marcosremar/talking-head-avatar/issues).