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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sage-rsc/talking-head-react",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "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

@@ -1,6 +1,7 @@
 import React, { useEffect, useRef, useState, useCallback, forwardRef, useImperativeHandle } from 'react';
 import { TalkingHead } from '../lib/talkinghead.mjs';
 import { getActiveTTSConfig, ELEVENLABS_CONFIG, DEEPGRAM_CONFIG } from '../config/ttsConfig';
+import { loadAnimationsFromManifest } from '../utils/animationLoader';
 
 /**
  * SimpleTalkingAvatar - A simple React component for 3D talking avatars
@@ -27,7 +28,12 @@ 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)
+ *                                    Or: { "manifest": "/animations/manifest.json" } (load from manifest file)
+ * @param {string} props.autoAnimationGroup - Animation group to automatically play when speaking (e.g., "talking")
+ * @param {string} props.autoIdleGroup - Animation group to automatically play when idle (e.g., "idle")
  * @param {boolean} props.autoSpeak - Whether to automatically speak the text prop when ready
  * @param {Object} ref - Ref to access component methods
  */
@@ -51,6 +57,8 @@ const SimpleTalkingAvatar = forwardRef(({
   className = "",
   style = {},
   animations = {},
+  autoAnimationGroup = null, // e.g., "talking" - will randomly select from this group when speaking
+  autoIdleGroup = null, // e.g., "idle" - will randomly select from this group when idle
   autoSpeak = false
 }, ref) => {
   const containerRef = useRef(null);
@@ -65,12 +73,34 @@ const SimpleTalkingAvatar = forwardRef(({
   const [error, setError] = useState(null);
   const [isReady, setIsReady] = useState(false);
   const [isPaused, setIsPaused] = useState(false);
+  const [loadedAnimations, setLoadedAnimations] = useState(animations);
+  const idleAnimationIntervalRef = useRef(null);
   
   // Keep ref in sync with state
   useEffect(() => {
     isPausedRef.current = isPaused;
   }, [isPaused]);
 
+  // Load animations from manifest if specified
+  useEffect(() => {
+    const loadManifestAnimations = async () => {
+      if (animations.manifest) {
+        try {
+          const manifestAnimations = await loadAnimationsFromManifest(animations.manifest);
+          setLoadedAnimations(manifestAnimations);
+          console.log('Loaded animations from manifest:', manifestAnimations);
+        } catch (error) {
+          console.error('Failed to load animation manifest:', error);
+          setLoadedAnimations(animations);
+        }
+      } else {
+        setLoadedAnimations(animations);
+      }
+    };
+    
+    loadManifestAnimations();
+  }, [animations]);
+
   // Update ref when prop changes
   useEffect(() => {
     showFullAvatarRef.current = showFullAvatar;
@@ -220,6 +250,44 @@ const SimpleTalkingAvatar = forwardRef(({
     }
   }, []);
 
+  // Helper function to get random animation from a group
+  const getRandomAnimation = useCallback((groupName) => {
+    if (!loadedAnimations || !loadedAnimations[groupName]) {
+      return null;
+    }
+    
+    const group = loadedAnimations[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;
+  }, [loadedAnimations]);
+
+  // 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 +303,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 +354,40 @@ 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-play idle animations
+  useEffect(() => {
+    if (!isReady || !autoIdleGroup || !talkingHeadRef.current) {
+      return;
+    }
+
+    // Clear any existing interval
+    if (idleAnimationIntervalRef.current) {
+      clearInterval(idleAnimationIntervalRef.current);
+    }
+
+    // Play idle animation immediately
+    const playIdleAnimation = () => {
+      if (talkingHeadRef.current && !isPausedRef.current) {
+        playRandomAnimation(autoIdleGroup);
+      }
+    };
+
+    playIdleAnimation();
+
+    // Set up interval to play idle animation every 10-15 seconds
+    idleAnimationIntervalRef.current = setInterval(() => {
+      playIdleAnimation();
+    }, 12000 + Math.random() * 3000); // Random interval between 12-15 seconds
+
+    return () => {
+      if (idleAnimationIntervalRef.current) {
+        clearInterval(idleAnimationIntervalRef.current);
+        idleAnimationIntervalRef.current = null;
+      }
+    };
+  }, [isReady, autoIdleGroup, playRandomAnimation]);
 
   // Auto-speak text when ready and autoSpeak is true
   useEffect(() => {
@@ -394,6 +502,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) => {

package/src/utils/animationLoader.js

@@ -0,0 +1,94 @@
+/**
+ * Animation Loader Utility
+ * 
+ * Helps load animations from directories and create animation groups
+ */
+
+/**
+ * Load animations from a manifest file
+ * @param {string} manifestPath - Path to manifest.json file
+ * @returns {Promise<Object>} Object with animation groups
+ */
+export async function loadAnimationsFromManifest(manifestPath) {
+  try {
+    const response = await fetch(manifestPath);
+    const manifest = await response.json();
+    return manifest.animations || {};
+  } catch (error) {
+    console.error('Failed to load animation manifest:', error);
+    return {};
+  }
+}
+
+/**
+ * Load animations using Vite's glob feature (only works in Vite)
+ * Note: This requires literal glob patterns at build time, not dynamic patterns
+ * Example usage in your code:
+ *   const modules = import.meta.glob('/animations/talking/*.fbx');
+ *   const animations = Object.keys(modules);
+ */
+export function processGlobAnimations(modules) {
+  const animations = {};
+  
+  Object.keys(modules).forEach(path => {
+    // Extract filename without extension
+    const filename = path.split('/').pop().replace('.fbx', '');
+    animations[filename] = path;
+  });
+  
+  return animations;
+}
+
+/**
+ * Create animation groups from a directory listing
+ * @param {string} directoryPath - Path to animations directory
+ * @param {Object} groupMapping - Map of group names to subdirectories or patterns
+ * @returns {Promise<Object>} Object with animation groups
+ * 
+ * Example:
+ * createAnimationGroups('/animations', {
+ *   talking: '/animations/talking',
+ *   idle: '/animations/idle'
+ * })
+ */
+export async function createAnimationGroups(directoryPath, groupMapping) {
+  const groups = {};
+  
+  for (const [groupName, subPath] of Object.entries(groupMapping)) {
+    try {
+      // Try to fetch a directory listing (requires server support)
+      const listingPath = `${subPath}/.list.json`; // Server-generated file list
+      const response = await fetch(listingPath);
+      
+      if (response.ok) {
+        const files = await response.json();
+        groups[groupName] = files
+          .filter(file => file.endsWith('.fbx'))
+          .map(file => `${subPath}/${file}`);
+      } else {
+        console.warn(`Could not load directory listing for ${subPath}`);
+      }
+    } catch (error) {
+      console.warn(`Failed to load animations from ${subPath}:`, error);
+    }
+  }
+  
+  return groups;
+}
+
+/**
+ * Get random animation from a group
+ * @param {Array|string} group - Animation group (array) or single animation (string)
+ * @returns {string|null} Random animation path or null
+ */
+export function getRandomAnimationFromGroup(group) {
+  if (Array.isArray(group) && group.length > 0) {
+    const randomIndex = Math.floor(Math.random() * group.length);
+    return group[randomIndex];
+  }
+  if (typeof group === 'string') {
+    return group;
+  }
+  return null;
+}
+