@sage-rsc/talking-head-react 1.0.72 → 1.0.74

package/README.md

@@ -1,74 +1,76 @@
-# Talking Head React
+# @sage-rsc/talking-head-react
 
-A reusable React component library for 3D talking avatars with lip-sync and text-to-speech capabilities. Perfect for creating interactive learning experiences, virtual assistants, and animated presentations.
+A powerful React component library for creating interactive 3D talking avatars with realistic lip-sync, multiple text-to-speech services, and curriculum-based learning capabilities.
 
-## Features
+## ✨ Features
 
-- 🎭 **3D Avatar Rendering** - Support for GLB/GLTF avatar models
-- 🎤 **Lip-Sync** - Real-time lip synchronization with audio
-- 🔊 **Text-to-Speech** - Multiple TTS services (Edge TTS, ElevenLabs, Google Cloud, Azure, Browser)
-- 🎬 **Animation Support** - FBX animation support and code-based animations
-- 🎯 **Programmatic Control** - Full control via props and ref methods
-- 🎨 **Zero UI** - Pure component, no built-in UI elements
-- 📦 **NPM Ready** - Easy to install and use
+- 🎭 **3D Avatar Rendering** - Support for GLB/GLTF avatar models with full body or head-only modes
+- 🎤 **Real-time Lip-Sync** - Automatic lip synchronization with audio using viseme-based animation
+- 🔊 **Multiple TTS Services** - Edge TTS, ElevenLabs, Deepgram, Google Cloud, Azure, and Browser TTS
+- 📚 **Curriculum Learning** - Built-in curriculum system with lessons, questions, and code examples
+- 🎬 **Animation Support** - FBX animation support and code-based body movements
+- ⏯️ **Playback Control** - Pause, resume, and stop speech functionality
+- 🎯 **Interactive Mode** - Manual control over curriculum progression
+- 💻 **Code IDE Integration** - Simulate code typing and execution in an IDE
+- 🎨 **Zero UI** - Pure components, no built-in UI elements - full control over styling
 
-## Installation
+## 📦 Installation
 
 ```bash
-npm install talking-head-react
+npm install @sage-rsc/talking-head-react
 ```
 
-## Peer Dependencies
-
-This package requires the following peer dependencies:
+### Peer Dependencies
 
 ```bash
 npm install react react-dom three
 ```
 
-## Quick Start
+**Requirements:**
+- React 18.0.0+ or 19.0.0+
+- React DOM 18.0.0+ or 19.0.0+
+- Three.js 0.150.0+
+
+## 🚀 Quick Start
+
+### Simple Talking Avatar
 
-### Basic Usage
+The simplest way to get started - just pass text and the avatar speaks:
 
 ```jsx
-import React, { useRef, useEffect } from 'react';
-import { TalkingHeadAvatar } from 'talking-head-react';
+import React, { useRef } from 'react';
+import { SimpleTalkingAvatar } from '@sage-rsc/talking-head-react';
 
 function App() {
   const avatarRef = useRef(null);
 
-  useEffect(() => {
-    // Wait for avatar to be ready
-    if (avatarRef.current?.isReady) {
-      // Make the avatar speak
-      avatarRef.current.speakText("Hello! I'm your talking avatar.");
-    }
-  }, []);
+  const handleSpeak = () => {
+    avatarRef.current?.speakText("Hello! I'm a talking avatar.");
+  };
 
   return (
     <div style={{ width: '100vw', height: '100vh' }}>
-      <TalkingHeadAvatar
+      <SimpleTalkingAvatar
         ref={avatarRef}
-        avatarUrl="/path/to/your/avatar.glb"
+        avatarUrl="/avatars/brunette.glb"
         avatarBody="F"
         mood="happy"
-        ttsService="edge"
-        ttsVoice="en-US-AriaNeural"
-        showFullAvatar={true}
-        onReady={(talkingHead) => {
-          console.log('Avatar is ready!', talkingHead);
-        }}
+        showFullAvatar={false}
+        onReady={() => console.log('Avatar ready!')}
       />
+      <button onClick={handleSpeak}>Speak</button>
     </div>
   );
 }
 ```
 
-### With FBX Animations
+### Full-Featured Avatar
+
+For advanced control with animations and custom configurations:
 
 ```jsx
 import React, { useRef } from 'react';
-import { TalkingHeadAvatar } from 'talking-head-react';
+import { TalkingHeadAvatar } from '@sage-rsc/talking-head-react';
 
 function App() {
   const avatarRef = useRef(null);
@@ -76,61 +78,60 @@ function App() {
   const animations = {
     teaching: "/animations/Arguing.fbx",
     correct: "/animations/Happy.fbx",
-    incorrect: "/animations/Disappointed.fbx",
-    lessonComplete: "/animations/Step.fbx"
-  };
-
-  const handleSpeak = () => {
-    if (avatarRef.current?.isReady) {
-      // Play animation while speaking
-      avatarRef.current.playAnimation(animations.teaching, true);
-      avatarRef.current.speakText("Let me explain this concept to you.");
-    }
+    incorrect: "/animations/Disappointed.fbx"
   };
 
   return (
     <div style={{ width: '100vw', height: '100vh' }}>
       <TalkingHeadAvatar
         ref={avatarRef}
-        avatarUrl="/path/to/your/avatar.glb"
+        avatarUrl="/avatars/brunette.glb"
+        avatarBody="F"
+        mood="happy"
+        ttsService="elevenlabs"
+        ttsApiKey="your-api-key"
+        ttsVoice="21m00Tcm4TlvDq8ikWAM"
+        showFullAvatar={false}
+        bodyMovement="gesturing"
         animations={animations}
         onReady={() => {
-          console.log('Avatar ready!');
+          avatarRef.current?.speakText("Welcome!");
         }}
       />
-      <button onClick={handleSpeak}>Start Teaching</button>
     </div>
   );
 }
 ```
 
-### With Curriculum Data
+### Curriculum Learning
+
+Complete learning system with lessons, questions, and automatic progression:
 
 ```jsx
 import React, { useRef } from 'react';
-import { CurriculumLearning } from 'talking-head-react';
+import { CurriculumLearning } from '@sage-rsc/talking-head-react';
 
 function App() {
-  const curriculumRef = useRef(null);
-
   const curriculumData = {
     curriculum: {
-      title: "Introduction to Computer Science",
+      title: "Introduction to Programming",
+      description: "Learn the basics of programming",
+      language: "en",
       modules: [
         {
-          title: "Module 1",
+          title: "Module 1: Variables",
           lessons: [
             {
-              title: "Lesson 1",
-              body: "This is lesson content...",
-              avatar_script: "Welcome to this lesson!",
+              title: "JavaScript Variables",
+              avatar_script: "Let's learn about variables.",
+              body: "Variables store data values in your program.",
               questions: [
                 {
                   type: "multiple_choice",
-                  question: "What is a variable?",
-                  options: ["Option A", "Option B", "Option C"],
-                  answer: "Option A",
-                  explanation: "A variable is..."
+                  question: "Which keyword creates a constant variable?",
+                  options: ["let", "const", "var"],
+                  answer: "const",
+                  explanation: "The 'const' keyword creates a constant variable."
                 }
               ]
             }
@@ -140,122 +141,297 @@ function App() {
     }
   };
 
-  const animations = {
-    teaching: "/animations/Arguing.fbx",
-    correct: "/animations/Happy.fbx",
-    incorrect: "/animations/Disappointed.fbx"
-  };
-
   const avatarConfig = {
-    avatarUrl: "/path/to/your/avatar.glb",
+    avatarUrl: "/avatars/brunette.glb",
     avatarBody: "F",
-    ttsService: "edge",
-    ttsVoice: "en-US-AriaNeural"
+    mood: "happy",
+    showFullAvatar: false
   };
 
   return (
     <div style={{ width: '100vw', height: '100vh' }}>
       <CurriculumLearning
-        ref={curriculumRef}
         curriculumData={curriculumData}
         avatarConfig={avatarConfig}
-        animations={animations}
         autoStart={true}
-        onLessonStart={(data) => {
-          console.log('Lesson started:', data);
-        }}
         onLessonComplete={(data) => {
           console.log('Lesson completed:', data);
         }}
-        onQuestionAnswer={(data) => {
-          console.log('Question answered:', data);
-        }}
       />
     </div>
   );
 }
 ```
 
-## API Reference
+## 📖 Components
+
+### SimpleTalkingAvatar
+
+A lightweight component for simple text-to-speech scenarios. Perfect when you just need an avatar to speak text.
 
-### TalkingHeadAvatar Props
+**Props:**
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `avatarUrl` | `string` | `"/avatars/brunette.glb"` | URL/path to the GLB avatar file |
+| `text` | `string` | `null` | Text to speak (optional, can use `speakText` method) |
+| `avatarUrl` | `string` | `"/avatars/brunette.glb"` | URL/path to GLB avatar file |
 | `avatarBody` | `string` | `"F"` | Avatar body type ('M' or 'F') |
-| `mood` | `string` | `"neutral"` | Initial mood ('happy', 'sad', 'neutral', etc.) |
+| `mood` | `string` | `"neutral"` | Initial mood ('happy', 'sad', 'neutral', 'excited') |
 | `ttsLang` | `string` | `"en"` | Text-to-speech language code |
-| `ttsService` | `string` | `null` | TTS service ('edge', 'elevenlabs', 'google', 'azure', 'browser') |
+| `ttsService` | `string` | `null` | TTS service ('edge', 'elevenlabs', 'deepgram', 'google', 'azure', 'browser') |
 | `ttsVoice` | `string` | `null` | TTS voice ID |
-| `bodyMovement` | `string` | `"idle"` | Initial body movement type |
+| `ttsApiKey` | `string` | `null` | TTS API key (ElevenLabs, Deepgram, Google, or Azure |
+| `bodyMovement` | `string` | `"idle"` | Body movement type ('idle', 'gesturing', 'dancing') |
 | `movementIntensity` | `number` | `0.5` | Movement intensity (0-1) |
-| `showFullAvatar` | `boolean` | `true` | Whether to show full body avatar |
-| `cameraView` | `string` | `"upper"` | Camera view ('upper', 'full', etc.) |
-| `animations` | `object` | `{}` | Object mapping animation names to FBX file paths |
+| `showFullAvatar` | `boolean` | `false` | Whether to show full body avatar |
+| `cameraView` | `string` | `"upper"` | Camera view ('upper', 'full') |
+| `autoSpeak` | `boolean` | `false` | Automatically speak `text` prop when ready |
 | `onReady` | `function` | `() => {}` | Callback when avatar is ready |
-| `onLoading` | `function` | `() => {}` | Callback for loading progress |
 | `onError` | `function` | `() => {}` | Callback for errors |
+| `onSpeechEnd` | `function` | `() => {}` | Callback when speech ends |
 | `className` | `string` | `""` | Additional CSS classes |
 | `style` | `object` | `{}` | Additional inline styles |
 
-### TalkingHeadAvatar Ref Methods
+**Ref Methods:**
 
 | Method | Parameters | Description |
 |--------|------------|-------------|
-| `speakText(text)` | `text: string` | Make the avatar speak the given text |
-| `stopSpeaking()` | - | Stop current speech |
-| `setMood(mood)` | `mood: string` | Set avatar mood |
-| `setTimingAdjustment(rate)` | `rate: number` | Adjust animation timing (e.g., 1.05 for 5% slower) |
-| `playAnimation(name, disablePositionLock)` | `name: string`, `disablePositionLock: boolean` | Play an FBX animation |
-| `setBodyMovement(movement)` | `movement: string` | Set body movement type |
-| `setMovementIntensity(intensity)` | `intensity: number` | Set movement intensity (0-1) |
-| `playRandomDance()` | - | Play a random dance animation |
-| `playReaction(reactionType)` | `reactionType: string` | Play a reaction animation |
+| `speakText(text, options)` | `text: string`, `options: object` | Make avatar speak text |
+| `pauseSpeaking()` | - | Pause current speech |
+| `resumeSpeaking()` | - | Resume paused speech |
+| `stopSpeaking()` | - | Stop all speech |
+| `resumeAudioContext()` | - | Resume audio context (for user interaction) |
+| `isPaused()` | - | Check if currently paused |
+| `setMood(mood)` | `mood: string` | Change avatar mood |
+| `setBodyMovement(movement)` | `movement: string` | Change body movement |
+| `playAnimation(name)` | `name: string` | Play FBX animation |
+| `playReaction(type)` | `type: string` | Play reaction animation |
 | `playCelebration()` | - | Play celebration animation |
 | `setShowFullAvatar(show)` | `show: boolean` | Toggle full body mode |
+| `isReady` | - | Boolean indicating if avatar is ready |
+
+**Example:**
+
+```jsx
+const avatarRef = useRef(null);
+
+// Speak text
+avatarRef.current?.speakText("Hello world!", {
+  lipsyncLang: 'en',
+  onSpeechEnd: () => console.log('Done speaking')
+});
+
+// Pause/Resume
+avatarRef.current?.pauseSpeaking();
+avatarRef.current?.resumeSpeaking();
+
+// Change mood
+avatarRef.current?.setMood("happy");
+```
+
+### TalkingHeadAvatar
+
+Full-featured avatar component with advanced controls, animations, and TTS configuration.
+
+**Props:** Same as `SimpleTalkingAvatar` plus:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `animations` | `object` | `{}` | Object mapping animation names to FBX file paths |
+| `onLoading` | `function` | `() => {}` | Callback for loading progress |
+
+**Ref Methods:** Same as `SimpleTalkingAvatar` plus:
+
+| Method | Parameters | Description |
+|--------|------------|-------------|
+| `setTimingAdjustment(rate)` | `rate: number` | Adjust animation timing (e.g., 1.05 for 5% slower) |
+| `setMovementIntensity(intensity)` | `intensity: number` | Set movement intensity (0-1) |
+| `playRandomDance()` | - | Play random dance animation |
 | `lockAvatarPosition()` | - | Lock avatar position |
 | `unlockAvatarPosition()` | - | Unlock avatar position |
 
-### CurriculumLearning Props
+### CurriculumLearning
+
+Complete learning system with curriculum management, questions, and code examples.
+
+**Props:**
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `curriculumData` | `object` | `null` | Curriculum data object |
-| `avatarConfig` | `object` | `{}` | Avatar configuration |
+| `curriculumData` | `object` | `null` | Curriculum data object (see structure below) |
+| `avatarConfig` | `object` | `{}` | Avatar configuration (same as `SimpleTalkingAvatar` props) |
 | `animations` | `object` | `{}` | Animation files mapping |
+| `autoStart` | `boolean` | `false` | Automatically start teaching when ready |
 | `onLessonStart` | `function` | `() => {}` | Callback when lesson starts |
 | `onLessonComplete` | `function` | `() => {}` | Callback when lesson completes |
 | `onQuestionAnswer` | `function` | `() => {}` | Callback when question is answered |
 | `onCurriculumComplete` | `function` | `() => {}` | Callback when curriculum completes |
-| `autoStart` | `boolean` | `false` | Whether to auto-start the curriculum |
+| `onCustomAction` | `function` | `() => {}` | Callback for custom actions (interactive mode) |
 
-### CurriculumLearning Ref Methods
+**Ref Methods:**
 
 | Method | Parameters | Description |
 |--------|------------|-------------|
-| `startTeaching()` | - | Start teaching the current lesson |
+| `startTeaching()` | - | Start teaching current lesson |
 | `startQuestions()` | - | Start asking questions |
-| `handleAnswerSelect(answer)` | `answer: string/boolean` | Handle answer selection |
+| `handleAnswerSelect(answer)` | `answer: string/boolean` | Submit answer to current question |
 | `nextQuestion()` | - | Move to next question |
+| `previousQuestion()` | - | Move to previous question |
 | `nextLesson()` | - | Move to next lesson |
+| `previousLesson()` | - | Move to previous lesson |
 | `completeLesson()` | - | Complete current lesson |
 | `completeCurriculum()` | - | Complete entire curriculum |
 | `resetCurriculum()` | - | Reset curriculum to beginning |
 | `getState()` | - | Get current curriculum state |
+| `pauseSpeaking()` | - | Pause avatar speech |
+| `resumeSpeaking()` | - | Resume avatar speech |
+| `isPaused()` | - | Check if paused |
+| `speakText(text, options)` | `text: string`, `options: object` | Make avatar speak text |
 
-## TTS Configuration
-
-The package includes a TTS configuration system. You can configure TTS services in `src/config/ttsConfig.js`:
+**Curriculum Data Structure:**
 
 ```javascript
-import { getActiveTTSConfig } from 'talking-head-react';
+{
+  curriculum: {
+    title: "Course Title",
+    description: "Course description",
+    language: "en",
+    modules: [
+      {
+        title: "Module Title",
+        lessons: [
+          {
+            title: "Lesson Title",
+            avatar_script: "What the avatar will say",
+            body: "Lesson content text",
+            code_example: {  // Optional
+              code: "console.log('Hello');",
+              language: "javascript",
+              description: "Code example description",
+              autoRun: true,
+              typingSpeed: 50
+            },
+            questions: [  // Optional
+              {
+                type: "multiple_choice",  // or "true_false" or "code_test"
+                question: "Question text?",
+                options: ["Option 1", "Option 2", "Option 3"],  // For multiple_choice
+                answer: "Option 1",  // or true/false for true_false
+                explanation: "Why this answer is correct"
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
 
-const config = getActiveTTSConfig();
-console.log(config.service); // 'edge', 'elevenlabs', 'google', 'azure', or 'browser'
+**Interactive Mode:**
+
+For manual control over curriculum progression:
+
+```jsx
+const curriculumRef = useRef(null);
+
+// Handle custom actions
+const handleCustomAction = (action) => {
+  switch (action.type) {
+    case 'teachingComplete':
+      // Teaching finished, enable "Start Questions" button
+      break;
+    case 'questionStart':
+      // Question started, show question UI
+      break;
+    case 'answerFeedbackComplete':
+      // Answer feedback finished, enable "Next Question" button
+      break;
+    case 'allQuestionsComplete':
+      // All questions done, enable "Complete Lesson" button
+      break;
+    case 'lessonCompleteFeedbackDone':
+      // Lesson completion feedback done, enable "Next Lesson" button
+      break;
+    case 'codeExampleReady':
+      // Code example ready, trigger IDE typing animation
+      break;
+  }
+};
+
+<CurriculumLearning
+  ref={curriculumRef}
+  curriculumData={curriculumData}
+  avatarConfig={avatarConfig}
+  autoStart={false}  // Manual control
+  onCustomAction={handleCustomAction}
+/>
+
+// Control progression manually
+curriculumRef.current?.startTeaching();
+curriculumRef.current?.startQuestions();
+curriculumRef.current?.nextQuestion();
+curriculumRef.current?.completeLesson();
+```
+
+## 🎤 Text-to-Speech Services
+
+### Edge TTS (Default)
+
+Free, no API key required:
+
+```jsx
+<SimpleTalkingAvatar
+  ttsService="edge"
+  ttsVoice="en-US-AriaNeural"
+/>
+```
+
+### ElevenLabs
+
+High-quality voices, requires API key:
+
+```jsx
+<SimpleTalkingAvatar
+  ttsService="elevenlabs"
+  ttsApiKey="your-api-key"
+  ttsVoice="21m00Tcm4TlvDq8ikWAM"
+/>
 ```
 
-## Animation Support
+### Deepgram
+
+Fast, high-quality TTS, requires API key:
+
+```jsx
+<SimpleTalkingAvatar
+  ttsService="deepgram"
+  ttsApiKey="your-api-key"
+  ttsVoice="aura-asteria-en"  // Options: aura-thalia-en, aura-asteria-en, aura-orion-en, etc.
+/>
+```
+
+### Browser TTS
+
+Uses browser's built-in speech synthesis:
+
+```jsx
+<SimpleTalkingAvatar
+  ttsService="browser"
+/>
+```
+
+### Google Cloud / Azure
+
+```jsx
+<SimpleTalkingAvatar
+  ttsService="google"  // or "azure"
+  ttsApiKey="your-api-key"
+  ttsVoice="en-US-Wavenet-D"
+/>
+```
+
+## 🎬 Animations
 
 ### FBX Animations
 
@@ -265,7 +441,8 @@ Provide animation mappings via the `animations` prop:
 const animations = {
   teaching: "/animations/Arguing.fbx",
   correct: "/animations/Happy.fbx",
-  incorrect: "/animations/Disappointed.fbx"
+  incorrect: "/animations/Disappointed.fbx",
+  lessonComplete: "/animations/Step.fbx"
 };
 
 <TalkingHeadAvatar animations={animations} />
@@ -273,19 +450,173 @@ const animations = {
 
 ### Code-Based Animations
 
-The package also supports code-based animations:
+Built-in body movements:
 
 - `idle` - Idle animation
 - `gesturing` - Teaching gestures
+- `dancing` - Dance animation
 - `happy` - Happy mood animation
 - `sad` - Sad mood animation
-- `dancing` - Dance animation
-- And more...
 
-## License
+```jsx
+avatarRef.current?.setBodyMovement("gesturing");
+avatarRef.current?.playReaction("happy");
+avatarRef.current?.playCelebration();
+```
+
+## 📚 Question Types
+
+### Multiple Choice
+
+```javascript
+{
+  type: "multiple_choice",
+  question: "What is a variable?",
+  options: ["A container", "A function", "A loop"],
+  answer: "A container",
+  explanation: "A variable is a container that stores data."
+}
+```
+
+### True/False
+
+```javascript
+{
+  type: "true_false",
+  question: "JavaScript is a compiled language.",
+  answer: false,
+  explanation: "JavaScript is an interpreted language."
+}
+```
+
+### Code Test
+
+```javascript
+{
+  type: "code_test",
+  question: "Write a function that adds two numbers.",
+  testCriteria: {
+    type: "function",
+    functionName: "add",
+    testCases: [
+      { input: [2, 3], expectedOutput: 5 },
+      { input: [10, 20], expectedOutput: 30 }
+    ]
+  },
+  explanation: "The function should return the sum of two numbers."
+}
+```
+
+## 💻 Code Examples
+
+Include code examples in lessons for IDE integration:
+
+```javascript
+{
+  title: "JavaScript Variables",
+  avatar_script: "Let's learn about variables.",
+  body: "Variables store data values.",
+  code_example: {
+    code: "let name = 'Alice';\nconst age = 25;\nconsole.log(name);",
+    language: "javascript",  // "javascript", "python", "java", "html"
+    description: "Basic variable declarations",
+    autoRun: true,  // Automatically run after typing
+    typingSpeed: 50  // Characters per second
+  }
+}
+```
+
+Listen for `codeExampleReady` event in interactive mode:
+
+```jsx
+const handleCustomAction = (action) => {
+  if (action.type === 'codeExampleReady') {
+    // Trigger IDE typing animation
+    handleCodeExample(action.codeExample);
+  }
+};
+```
+
+## 🎯 Use Cases
+
+- **Educational Platforms** - Interactive learning with curriculum management
+- **Virtual Assistants** - Conversational avatars with TTS
+- **Code Tutorials** - Step-by-step coding lessons with IDE integration
+- **Training Simulations** - Interactive training with questions and feedback
+- **Presentation Tools** - Animated presentations with talking avatars
+
+## 🔧 Configuration
+
+### TTS Configuration
+
+Configure default TTS service in your app:
+
+```javascript
+import { getActiveTTSConfig } from '@sage-rsc/talking-head-react';
+
+const config = getActiveTTSConfig();
+// Returns current TTS configuration
+```
+
+### Avatar Configuration
+
+Common avatar settings:
+
+```javascript
+const avatarConfig = {
+  avatarUrl: "/avatars/brunette.glb",
+  avatarBody: "F",  // "M" or "F"
+  mood: "happy",
+  ttsService: "elevenlabs",
+  ttsApiKey: "your-key",
+  ttsVoice: "voice-id",
+  showFullAvatar: false,  // false = head only, true = full body
+  bodyMovement: "gesturing",
+  movementIntensity: 0.7
+};
+```
+
+## 📝 Examples
+
+Check the `example-*.jsx` files in the repository for complete examples:
+
+- `example-simple-avatar.jsx` - Simple text-to-speech usage
+- `example-interactive-mode.jsx` - Manual curriculum control
+- `example-with-code-ide.jsx` - Code IDE integration
+- `example-with-api-key.jsx` - TTS service configuration
+
+## 🐛 Troubleshooting
+
+### Audio Not Playing
+
+If you see "Web Audio API suspended" error:
+
+```jsx
+// The component automatically resumes audio context on user interaction
+// But you can also manually resume:
+avatarRef.current?.resumeAudioContext();
+```
+
+### Avatar Not Loading
+
+- Ensure the avatar file path is correct
+- Check browser console for loading errors
+- Verify GLB file is valid
+
+### Lip-Sync Not Working
+
+- Ensure avatar model has viseme morph targets
+- Check that `lipsyncLang` matches your TTS language
+- Verify TTS service is working correctly
+
+## 📄 License
 
 MIT
 
-## Contributing
+## 🤝 Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📞 Support
+
+For issues, questions, or feature requests, please open an issue on GitHub.