npm package: @sage-rsc/talking-head-avatar
Description: Professional 3D Avatar Component for React with TTS, Lip-sync, and Animation Support
Author: Your Name
Latest version: 1.0.3

# 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

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

## Quick Start

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

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

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

```typescript
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](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: your.email@example.com
- 🐛 Issues: [GitHub Issues](https://github.com/your-username/talking-head-avatar/issues)
- 📖 Documentation: [Full Documentation](https://github.com/your-username/talking-head-avatar#readme)

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