@sage-rsc/talking-head-react 1.2.2 → 1.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sage-rsc/talking-head-react",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "A reusable React component for 3D talking avatars with lip-sync and text-to-speech",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",

package/src/components/SimpleTalkingAvatar.jsx

@@ -27,7 +27,10 @@ import { getActiveTTSConfig, ELEVENLABS_CONFIG, DEEPGRAM_CONFIG } from '../confi
  * @param {Function} props.onSpeechEnd - Callback when speech ends
  * @param {string} props.className - Additional CSS classes
  * @param {Object} props.style - Additional inline styles
- * @param {Object} props.animations - Object mapping animation names to FBX file paths
+ * @param {Object} props.animations - Object mapping animation names to FBX file paths, or animation groups
+ *                                    Can be: { "dance": "/animations/dance.fbx" } (single animation)
+ *                                    Or: { "talking": ["/animations/talk1.fbx", "/animations/talk2.fbx"] } (group)
+ * @param {string} props.autoAnimationGroup - Animation group to automatically play when speaking (e.g., "talking")
  * @param {boolean} props.autoSpeak - Whether to automatically speak the text prop when ready
  * @param {Object} ref - Ref to access component methods
  */
@@ -51,6 +54,7 @@ const SimpleTalkingAvatar = forwardRef(({
   className = "",
   style = {},
   animations = {},
+  autoAnimationGroup = null, // e.g., "talking" - will randomly select from this group when speaking
   autoSpeak = false
 }, ref) => {
   const containerRef = useRef(null);
@@ -220,6 +224,44 @@ const SimpleTalkingAvatar = forwardRef(({
     }
   }, []);
 
+  // Helper function to get random animation from a group
+  const getRandomAnimation = useCallback((groupName) => {
+    if (!animations || !animations[groupName]) {
+      return null;
+    }
+    
+    const group = animations[groupName];
+    
+    // If it's an array, randomly select one
+    if (Array.isArray(group) && group.length > 0) {
+      const randomIndex = Math.floor(Math.random() * group.length);
+      return group[randomIndex];
+    }
+    
+    // If it's a string, return it directly
+    if (typeof group === 'string') {
+      return group;
+    }
+    
+    return null;
+  }, [animations]);
+
+  // Helper function to play random animation from a group
+  const playRandomAnimation = useCallback((groupName, disablePositionLock = false) => {
+    const animationPath = getRandomAnimation(groupName);
+    if (animationPath && talkingHeadRef.current) {
+      try {
+        talkingHeadRef.current.playAnimation(animationPath, null, 10, 0, 0.01, disablePositionLock);
+        console.log(`Playing random animation from "${groupName}" group:`, animationPath);
+        return animationPath;
+      } catch (error) {
+        console.warn(`Failed to play random animation from "${groupName}" group:`, error);
+        return null;
+      }
+    }
+    return null;
+  }, [getRandomAnimation]);
+
   // Speak text with proper callback handling
   const speakText = useCallback(async (textToSpeak, options = {}) => {
     if (!talkingHeadRef.current || !isReady) {
@@ -235,6 +277,13 @@ const SimpleTalkingAvatar = forwardRef(({
     // Always resume audio context first (required for user interaction)
     await resumeAudioContext();
 
+    // Play random animation from autoAnimationGroup if specified
+    // Check both autoAnimationGroup prop and options.animationGroup
+    const animationGroup = options.animationGroup || autoAnimationGroup;
+    if (animationGroup && !options.skipAnimation) {
+      playRandomAnimation(animationGroup);
+    }
+
     // Reset speech progress tracking
     speechProgressRef.current = { remainingText: null, originalText: null, options: null };
     originalSentencesRef.current = [];
@@ -279,7 +328,7 @@ const SimpleTalkingAvatar = forwardRef(({
       console.error('Error speaking text:', err);
       setError(err.message || 'Failed to speak text');
     }
-  }, [isReady, onSpeechEnd, resumeAudioContext]);
+  }, [isReady, onSpeechEnd, resumeAudioContext, autoAnimationGroup, playRandomAnimation]);
 
   // Auto-speak text when ready and autoSpeak is true
   useEffect(() => {
@@ -394,6 +443,12 @@ const SimpleTalkingAvatar = forwardRef(({
         talkingHeadRef.current.playAnimation(animationName, null, 10, 0, 0.01, disablePositionLock);
       }
     },
+    playRandomAnimation: (groupName, disablePositionLock = false) => {
+      return playRandomAnimation(groupName, disablePositionLock);
+    },
+    getRandomAnimation: (groupName) => {
+      return getRandomAnimation(groupName);
+    },
     playReaction: (reactionType) => talkingHeadRef.current?.playReaction(reactionType),
     playCelebration: () => talkingHeadRef.current?.playCelebration(),
     setShowFullAvatar: (show) => {