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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sage-rsc/talking-head-react",
-  "version": "1.2.3",
+  "version": "1.3.1",
   "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
@@ -30,7 +31,9 @@ import { getActiveTTSConfig, ELEVENLABS_CONFIG, DEEPGRAM_CONFIG } from '../confi
  * @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
  */
@@ -55,6 +58,7 @@ const SimpleTalkingAvatar = forwardRef(({
   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);
@@ -69,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;
@@ -226,11 +252,11 @@ const SimpleTalkingAvatar = forwardRef(({
 
   // Helper function to get random animation from a group
   const getRandomAnimation = useCallback((groupName) => {
-    if (!animations || !animations[groupName]) {
+    if (!loadedAnimations || !loadedAnimations[groupName]) {
       return null;
     }
     
-    const group = animations[groupName];
+    const group = loadedAnimations[groupName];
     
     // If it's an array, randomly select one
     if (Array.isArray(group) && group.length > 0) {
@@ -244,7 +270,7 @@ const SimpleTalkingAvatar = forwardRef(({
     }
     
     return null;
-  }, [animations]);
+  }, [loadedAnimations]);
 
   // Helper function to play random animation from a group
   const playRandomAnimation = useCallback((groupName, disablePositionLock = false) => {
@@ -330,6 +356,39 @@ const SimpleTalkingAvatar = forwardRef(({
     }
   }, [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(() => {
     if (isReady && text && autoSpeak && talkingHeadRef.current) {

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;
+}
+