{"_id":"@sage-rsc/talking-head-avatar","_rev":"4-8c28cb086689d1bdbd263286943e12cc","name":"@sage-rsc/talking-head-avatar","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.0":{"name":"@sage-rsc/talking-head-avatar","version":"1.0.0","keywords":["react","3d","avatar","tts","text-to-speech","lip-sync","animation","three.js","gltf","fbx","education","tutor","ai","component","reusable"],"author":{"name":"Your Name","email":"your.email@example.com"},"license":"MIT","_id":"@sage-rsc/talking-head-avatar@1.0.0","maintainers":[{"name":"sage-rsc","email":"Jaysage73@gmail.com"}],"homepage":"https://github.com/your-username/talking-head-avatar#readme","bugs":{"url":"https://github.com/your-username/talking-head-avatar/issues"},"dist":{"shasum":"fec1f218d6242ca7317c59d1b7bdec11ed79a875","tarball":"https://registry.npmjs.org/@sage-rsc/talking-head-avatar/-/talking-head-avatar-1.0.0.tgz","fileCount":12,"integrity":"sha512-ubEafywD89RiyEQHttC6BFDSorIVFc/1j29a5CREXs4Z0ZwIAbISMrSEQMWhnPWrxBSrhtx14xU5NZj8fVLMWw==","signatures":[{"sig":"MEUCIQDNpJzrxeq9aGtsNPE4Zksasp45zrrLI39XwjSth8UpzAIgREKHokFxiQ0/o/b7Aoa814QLU6GDxXgW7JkWZ+INCCM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":19961430},"main":"index.js","types":"index.d.ts","module":"index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./styles":"./dist/styles.css"},"gitHead":"f8229b1dbe8250a4c4b0d13eca7af6c735a36e1b","_npmUser":{"name":"sage-rsc","email":"Jaysage73@gmail.com"},"repository":{"url":"git+https://github.com/your-username/talking-head-avatar.git","type":"git"},"_npmVersion":"10.9.2","description":"Professional 3D Avatar Component for React with TTS, Lip-sync, and Animation Support","directories":{},"_nodeVersion":"23.8.0","dependencies":{"three":">=0.150.0"},"_hasShrinkwrap":false,"peerDependencies":{"react":">=18.0.0","three":">=0.150.0","react-dom":">=18.0.0"},"_npmOperationalInternal":{"tmp":"tmp/talking-head-avatar_1.0.0_1761391770988_0.19194856113388936","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@sage-rsc/talking-head-avatar","version":"1.0.1","keywords":["react","3d","avatar","tts","text-to-speech","lip-sync","animation","three.js","gltf","fbx","education","tutor","ai","component","reusable"],"author":{"name":"Your Name","email":"your.email@example.com"},"license":"MIT","_id":"@sage-rsc/talking-head-avatar@1.0.1","maintainers":[{"name":"sage-rsc","email":"Jaysage73@gmail.com"}],"homepage":"https://github.com/your-username/talking-head-avatar#readme","bugs":{"url":"https://github.com/your-username/talking-head-avatar/issues"},"dist":{"shasum":"8f8e6bb0b60f7959ad4d84e14b20100eebf284bd","tarball":"https://registry.npmjs.org/@sage-rsc/talking-head-avatar/-/talking-head-avatar-1.0.1.tgz","fileCount":12,"integrity":"sha512-1lFb36in3JNUetU3FW4lMEvyaqlFipjDNrCa7+bgMuGjC1ULUORCRJkUWofEwa3iDExLy9baBvBeGH9Nx94hrQ==","signatures":[{"sig":"MEYCIQCBB1991Tvd6b3NsOOyx7/KK40JzLPer9acjbxyPDncdwIhAPmtPViuCiB1tGLaULktqKIFhKYHhJ+2FHaLel2oNVza","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":19961383},"main":"index.js","types":"index.d.ts","module":"index.js","exports":{".":{"types":"./index.d.ts","import":"./index.js"}},"gitHead":"f8229b1dbe8250a4c4b0d13eca7af6c735a36e1b","_npmUser":{"name":"sage-rsc","email":"Jaysage73@gmail.com"},"repository":{"url":"git+https://github.com/your-username/talking-head-avatar.git","type":"git"},"_npmVersion":"10.9.2","description":"Professional 3D Avatar Component for React with TTS, Lip-sync, and Animation Support","directories":{},"_nodeVersion":"23.8.0","dependencies":{"three":">=0.150.0"},"_hasShrinkwrap":false,"peerDependencies":{"react":">=18.0.0","three":">=0.150.0","react-dom":">=18.0.0"},"_npmOperationalInternal":{"tmp":"tmp/talking-head-avatar_1.0.1_1761392583174_0.6156501134196266","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@sage-rsc/talking-head-avatar","version":"1.0.2","keywords":["react","3d","avatar","tts","text-to-speech","lip-sync","animation","three.js","gltf","fbx","education","tutor","ai","component","reusable"],"author":{"name":"Your Name","email":"your.email@example.com"},"license":"MIT","_id":"@sage-rsc/talking-head-avatar@1.0.2","maintainers":[{"name":"sage-rsc","email":"Jaysage73@gmail.com"}],"homepage":"https://github.com/your-username/talking-head-avatar#readme","bugs":{"url":"https://github.com/your-username/talking-head-avatar/issues"},"dist":{"shasum":"f51a1d3fe8427520d2459d1853973399598943d5","tarball":"https://registry.npmjs.org/@sage-rsc/talking-head-avatar/-/talking-head-avatar-1.0.2.tgz","fileCount":12,"integrity":"sha512-qc+WaHc8AoF8MtNLOgXvya3TuUrLTXyD7pZh6Ek47ChsH31NHrM6CKJ5bT2MNYulaI4JDzjNYNgQsGtBid35Bg==","signatures":[{"sig":"MEUCIQCA8XbrVDe2JmzsLURd5eBpM7cGVQJ6Ko0edlM8rr4RRwIge2OEEjOd+jVwdhgIJkFASPZ+3KjKeZj6h9nocuQ1txA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":19963374},"main":"index.js","types":"index.d.ts","module":"index.js","exports":{".":{"types":"./index.d.ts","import":"./index.js"}},"gitHead":"f8229b1dbe8250a4c4b0d13eca7af6c735a36e1b","_npmUser":{"name":"sage-rsc","email":"Jaysage73@gmail.com"},"repository":{"url":"git+https://github.com/your-username/talking-head-avatar.git","type":"git"},"_npmVersion":"10.9.2","description":"Professional 3D Avatar Component for React with TTS, Lip-sync, and Animation Support","directories":{},"_nodeVersion":"23.8.0","dependencies":{"three":">=0.150.0"},"_hasShrinkwrap":false,"peerDependencies":{"react":">=18.0.0","three":">=0.150.0","react-dom":">=18.0.0"},"_npmOperationalInternal":{"tmp":"tmp/talking-head-avatar_1.0.2_1761392877486_0.12487420658064696","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@sage-rsc/talking-head-avatar","version":"1.0.3","description":"Professional 3D Avatar Component for React with TTS, Lip-sync, and Animation Support","main":"index.js","module":"index.js","types":"index.d.ts","exports":{".":{"import":"./index.js","types":"./index.d.ts"},"./lib/*":"./lib/*","./avatars/*":"./avatars/*","./animations/*":"./animations/*"},"keywords":["react","3d","avatar","tts","text-to-speech","lip-sync","animation","three.js","gltf","fbx","education","tutor","ai","component","reusable"],"author":{"name":"Your Name","email":"your.email@example.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/your-username/talking-head-avatar.git"},"homepage":"https://github.com/your-username/talking-head-avatar#readme","bugs":{"url":"https://github.com/your-username/talking-head-avatar/issues"},"peerDependencies":{"react":">=18.0.0","react-dom":">=18.0.0","three":">=0.150.0"},"dependencies":{"three":">=0.150.0"},"_id":"@sage-rsc/talking-head-avatar@1.0.3","gitHead":"f8229b1dbe8250a4c4b0d13eca7af6c735a36e1b","_nodeVersion":"23.8.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-FOoddI/arDtvfbmiK+s6fNJjX2zZFxxGQNxz7fV7MHvPmWU+M/n6znFR2YS2SEWup5ObmTiBuNk3eH8eUUaA7Q==","shasum":"50096ae485bc9b318b8123bfe3eae156bfafb312","tarball":"https://registry.npmjs.org/@sage-rsc/talking-head-avatar/-/talking-head-avatar-1.0.3.tgz","fileCount":21,"unpackedSize":20323960,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCN6A9FmtFnoU9FGuHxyFnuoGdfRJYGAEN673h5CmZNHQIhAKKk/QSKWbeWOuUtfaI6yqkEtRmV+udcd8TJwKyZy6bh"}]},"_npmUser":{"name":"sage-rsc","email":"Jaysage73@gmail.com"},"directories":{},"maintainers":[{"name":"sage-rsc","email":"Jaysage73@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/talking-head-avatar_1.0.3_1761393318042_0.7037493383847881"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-25T11:29:30.929Z","modified":"2025-10-25T11:55:18.783Z","1.0.0":"2025-10-25T11:29:31.339Z","1.0.1":"2025-10-25T11:43:03.517Z","1.0.2":"2025-10-25T11:47:57.769Z","1.0.3":"2025-10-25T11:55:18.594Z"},"bugs":{"url":"https://github.com/your-username/talking-head-avatar/issues"},"author":{"name":"Your Name","email":"your.email@example.com"},"license":"MIT","homepage":"https://github.com/your-username/talking-head-avatar#readme","keywords":["react","3d","avatar","tts","text-to-speech","lip-sync","animation","three.js","gltf","fbx","education","tutor","ai","component","reusable"],"repository":{"type":"git","url":"git+https://github.com/your-username/talking-head-avatar.git"},"description":"Professional 3D Avatar Component for React with TTS, Lip-sync, and Animation Support","maintainers":[{"name":"sage-rsc","email":"Jaysage73@gmail.com"}],"readme":"# Talking Head Avatar\n\nA 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.\n\n## Features\n\n- 🎭 **3D Avatar Rendering** - High-quality GLTF/GLB avatar support\n- 🗣️ **Text-to-Speech** - Multiple TTS services (Edge, Google, Azure, Browser)\n- 👄 **Automatic Lip-sync** - Real-time mouth animation synchronized with speech\n- 🎨 **Rich Animations** - Code-based and FBX animation support\n- 🎮 **Interactive Controls** - Programmatic control via React refs\n- 📱 **Responsive Design** - Full viewport coverage with no scrollbars\n- 🔧 **Highly Customizable** - Extensive configuration options\n- 📦 **TypeScript Support** - Full type definitions included\n- 🎯 **Production Ready** - Optimized for performance and reliability\n\n## Installation\n\n```bash\nnpm install @your-username/talking-head-avatar\n```\n\n## Quick Start\n\n```tsx\nimport React, { useRef } from 'react';\nimport { TalkingHeadAvatar } from '@your-username/talking-head-avatar';\n\nfunction App() {\n  const avatarRef = useRef(null);\n\n  const handleSpeak = () => {\n    avatarRef.current?.speakText(\"Hello! I'm your AI assistant.\");\n  };\n\n  return (\n    <div>\n      <TalkingHeadAvatar\n        ref={avatarRef}\n        avatarUrl=\"/path/to/your/avatar.glb\"\n        onReady={() => console.log('Avatar ready!')}\n      />\n      <button onClick={handleSpeak}>Make Avatar Speak</button>\n    </div>\n  );\n}\n```\n\n## Advanced Usage\n\n### Custom Configuration\n\n```tsx\nimport { TalkingHeadAvatar, createTalkingHeadConfig } from '@your-username/talking-head-avatar';\n\nconst customConfig = createTalkingHeadConfig({\n  avatar: {\n    url: \"/avatars/my-avatar.glb\",\n    mood: \"happy\",\n    bodyMovement: \"gesturing\",\n    position: { x: 0, y: 0.5, z: 0 }\n  },\n  tts: {\n    service: \"edge\",\n    voice: \"en-US-AriaNeural\",\n    timingAdjustment: 1.1\n  },\n  animations: {\n    useFBXForTeaching: true,\n    teachingAnimation: {\n      fbx: \"/animations/teaching.fbx\"\n    }\n  }\n});\n\nfunction App() {\n  return (\n    <TalkingHeadAvatar\n      config={customConfig}\n      fbxAnimations={[\n        \"/animations/dance.fbx\",\n        \"/animations/wave.fbx\",\n        \"/animations/celebration.fbx\"\n      ]}\n    />\n  );\n}\n```\n\n### Programmatic Control\n\n```tsx\nimport React, { useRef, useEffect } from 'react';\nimport { TalkingHeadAvatar } from '@your-username/talking-head-avatar';\n\nfunction App() {\n  const avatarRef = useRef(null);\n\n  useEffect(() => {\n    const avatar = avatarRef.current;\n    if (avatar) {\n      // Set avatar mood\n      avatar.setMood(\"excited\");\n      \n      // Play animation\n      avatar.playAnimation(\"dance\");\n      \n      // Speak with lip-sync\n      avatar.speakText(\"Welcome to our application!\");\n      \n      // Set body movement\n      avatar.setBodyMovement(\"gesturing\");\n    }\n  }, []);\n\n  return (\n    <TalkingHeadAvatar\n      ref={avatarRef}\n      avatarUrl=\"/avatars/assistant.glb\"\n      onReady={(talkingHead) => {\n        console.log('Avatar initialized:', talkingHead);\n      }}\n    />\n  );\n}\n```\n\n## API Reference\n\n### Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `config` | `Partial<TalkingHeadConfig>` | `{}` | Avatar configuration object |\n| `avatarUrl` | `string` | - | Override avatar GLB/GLTF file path |\n| `fbxAnimations` | `string[]` | `[]` | Array of FBX animation file paths |\n| `onReady` | `(talkingHead: any) => void` | - | Callback when avatar is ready |\n| `onError` | `(error: Error) => void` | - | Error callback |\n| `onLoading` | `(progress: number) => void` | - | Loading progress callback |\n| `className` | `string` | - | CSS class name |\n| `style` | `React.CSSProperties` | - | Inline styles |\n| `children` | `React.ReactNode` | - | Child components |\n\n### Ref Methods\n\n| Method | Parameters | Description |\n|--------|------------|-------------|\n| `speakText` | `(text: string) => void` | Make avatar speak with lip-sync |\n| `stopSpeaking` | `() => void` | Stop current speech |\n| `setMood` | `(mood: string) => void` | Set avatar mood |\n| `setBodyMovement` | `(movement: string) => void` | Set body movement animation |\n| `playAnimation` | `(name: string, disablePositionLock?: boolean) => void` | Play animation |\n| `playReaction` | `(reaction: string) => void` | Play reaction animation |\n| `playCelebration` | `() => void` | Play celebration animation |\n| `playRandomDance` | `() => void` | Play random dance animation |\n| `setShowFullAvatar` | `(show: boolean) => void` | Toggle full body mode |\n| `setMovementIntensity` | `(intensity: number) => void` | Set movement intensity (0-1) |\n| `setTimingAdjustment` | `(adjustment: number) => void` | Adjust lip-sync timing |\n| `lockAvatarPosition` | `() => void` | Lock avatar position |\n| `unlockAvatarPosition` | `() => void` | Unlock avatar position |\n\n### Configuration Types\n\n```typescript\ninterface TalkingHeadConfig {\n  avatar: {\n    url: string;\n    body?: 'F' | 'M';\n    mood?: 'happy' | 'neutral' | 'sad' | 'excited' | 'curious' | 'celebrating';\n    ttsLang?: string;\n    ttsService?: 'edge' | 'google' | 'azure' | 'browser';\n    ttsVoice?: string;\n    bodyMovement?: 'idle' | 'gesturing' | 'dancing' | 'walking' | 'excited' | 'happy';\n    movementIntensity?: number;\n    showFullAvatar?: boolean;\n    showControls?: boolean;\n    position?: { x?: number; y?: number; z?: number; };\n  };\n  tts: {\n    service: 'edge' | 'google' | 'azure' | 'browser';\n    voice: string;\n    timingAdjustment?: number;\n    voices?: Record<string, string>;\n    endpoint?: string;\n    apiKey?: string;\n  };\n  animations: {\n    useFBXForTeaching?: boolean;\n    teachingAnimation?: { fbx?: string; codeBased?: string; };\n    feedbackAnimations?: { correct?: string; wrong?: string; };\n    celebrationAnimations?: { lessonComplete?: string; curriculumComplete?: string; };\n  };\n  ui: {\n    showProgressBar?: boolean;\n    showStatusIndicators?: boolean;\n    showControlButtons?: boolean;\n    showVoiceSelector?: boolean;\n    showTimingControls?: boolean;\n    showTeachingModeToggle?: boolean;\n    showFullBodyIndicator?: boolean;\n    autoStartTeaching?: boolean;\n  };\n  curriculum: {\n    maxRetries?: number;\n    teachingDuration?: number;\n    questionTransitionDelay?: number;\n  };\n}\n```\n\n## Avatar Requirements\n\n### GLTF/GLB Files\n- Must include morph targets for lip-sync\n- Recommended bone structure for animations\n- Optimized for web (compressed textures)\n\n### FBX Animations\n- Compatible with avatar skeleton\n- Include position and rotation tracks\n- Optimized file sizes\n\n## Browser Support\n\n- Chrome 80+\n- Firefox 75+\n- Safari 13+\n- Edge 80+\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## Support\n\n- 📧 Email: your.email@example.com\n- 🐛 Issues: [GitHub Issues](https://github.com/your-username/talking-head-avatar/issues)\n- 📖 Documentation: [Full Documentation](https://github.com/your-username/talking-head-avatar#readme)\n\n## Changelog\n\n### v1.0.0\n- Initial release\n- 3D avatar rendering with GLTF/GLB support\n- Text-to-speech with multiple services\n- Automatic lip-sync\n- Animation system (code-based and FBX)\n- TypeScript support\n- Comprehensive configuration options","readmeFilename":"README.md"}