@sage-rsc/talking-head-react 1.5.0 → 1.5.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sage-rsc/talking-head-react",
-  "version": "1.5.0",
+  "version": "1.5.5",
   "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/AnimationSelector.jsx

@@ -0,0 +1,419 @@
+import React, { useState, useEffect, useRef } from 'react';
+import { loadAnimationsFromManifest } from '../utils/animationLoader';
+
+/**
+ * AnimationSelector Component
+ * 
+ * Allows users to:
+ * 1. Load all animations from manifest
+ * 2. Display them as clickable buttons
+ * 3. Select animations to keep
+ * 4. Delete unselected animations
+ * 
+ * @param {Object} props
+ * @param {string} props.manifestPath - Path to manifest.json file
+ * @param {string} props.avatarBody - Avatar body type ('M' or 'F') for gender-specific filtering
+ * @param {Function} props.onAnimationPlay - Callback when animation button is clicked (receives animation path)
+ * @param {Function} props.onAnimationsSelected - Callback when animations are selected (receives array of selected paths)
+ * @param {Function} props.onDeleteAnimations - Callback when delete is clicked (receives array of paths to delete)
+ * @param {Object} props.style - Additional styles
+ */
+export function AnimationSelector({
+  manifestPath = "/animations/manifest.json",
+  avatarBody = "F",
+  onAnimationPlay = null,
+  onAnimationsSelected = null,
+  onDeleteAnimations = null,
+  style = {}
+}) {
+  const [animations, setAnimations] = useState([]);
+  const [selectedAnimations, setSelectedAnimations] = useState(new Set());
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState(null);
+  const [filterGroup, setFilterGroup] = useState('all'); // Filter by group
+  const [searchTerm, setSearchTerm] = useState('');
+
+  // Load animations from manifest
+  useEffect(() => {
+    const loadAnimations = async () => {
+      setIsLoading(true);
+      setError(null);
+      
+      try {
+        const manifestData = await loadAnimationsFromManifest(manifestPath);
+        
+        // Flatten animations into a list with metadata
+        const flatAnimations = [];
+        
+        // Handle gender-specific animations
+        if (manifestData._genderSpecific) {
+          const avatarGender = avatarBody?.toUpperCase() || 'F';
+          const genderKey = avatarGender === 'M' ? 'male' : 'female';
+          
+          // Add gender-specific animations
+          if (manifestData._genderSpecific[genderKey]) {
+            Object.entries(manifestData._genderSpecific[genderKey]).forEach(([groupName, anims]) => {
+              const animArray = Array.isArray(anims) ? anims : [anims];
+              animArray.forEach(animPath => {
+                flatAnimations.push({
+                  path: animPath,
+                  group: groupName,
+                  gender: genderKey,
+                  name: animPath.split('/').pop().replace('.fbx', '')
+                });
+              });
+            });
+          }
+          
+          // Add shared animations
+          if (manifestData._genderSpecific.shared) {
+            Object.entries(manifestData._genderSpecific.shared).forEach(([groupName, anims]) => {
+              const animArray = Array.isArray(anims) ? anims : [anims];
+              animArray.forEach(animPath => {
+                flatAnimations.push({
+                  path: animPath,
+                  group: groupName,
+                  gender: 'shared',
+                  name: animPath.split('/').pop().replace('.fbx', '')
+                });
+              });
+            });
+          }
+        }
+        
+        // Add root-level animations
+        Object.entries(manifestData).forEach(([key, value]) => {
+          if (key !== '_genderSpecific') {
+            const animArray = Array.isArray(value) ? value : [value];
+            animArray.forEach(animPath => {
+              if (typeof animPath === 'string') {
+                flatAnimations.push({
+                  path: animPath,
+                  group: key,
+                  gender: 'root',
+                  name: animPath.split('/').pop().replace('.fbx', '')
+                });
+              }
+            });
+          }
+        });
+        
+        setAnimations(flatAnimations);
+        setIsLoading(false);
+      } catch (err) {
+        console.error('Failed to load animations:', err);
+        setError(err.message);
+        setIsLoading(false);
+      }
+    };
+    
+    loadAnimations();
+  }, [manifestPath, avatarBody]);
+
+  // Get unique groups for filtering
+  const groups = ['all', ...new Set(animations.map(a => a.group))];
+
+  // Filter animations
+  const filteredAnimations = animations.filter(anim => {
+    const matchesGroup = filterGroup === 'all' || anim.group === filterGroup;
+    const matchesSearch = searchTerm === '' || 
+      anim.name.toLowerCase().includes(searchTerm.toLowerCase()) ||
+      anim.path.toLowerCase().includes(searchTerm.toLowerCase());
+    return matchesGroup && matchesSearch;
+  });
+
+  // Toggle selection
+  const toggleSelection = (path) => {
+    const newSelected = new Set(selectedAnimations);
+    if (newSelected.has(path)) {
+      newSelected.delete(path);
+    } else {
+      newSelected.add(path);
+    }
+    setSelectedAnimations(newSelected);
+    
+    if (onAnimationsSelected) {
+      onAnimationsSelected(Array.from(newSelected));
+    }
+  };
+
+  // Select all visible
+  const selectAll = () => {
+    const newSelected = new Set(selectedAnimations);
+    filteredAnimations.forEach(anim => {
+      newSelected.add(anim.path);
+    });
+    setSelectedAnimations(newSelected);
+    
+    if (onAnimationsSelected) {
+      onAnimationsSelected(Array.from(newSelected));
+    }
+  };
+
+  // Deselect all visible
+  const deselectAll = () => {
+    const newSelected = new Set(selectedAnimations);
+    filteredAnimations.forEach(anim => {
+      newSelected.delete(anim.path);
+    });
+    setSelectedAnimations(newSelected);
+    
+    if (onAnimationsSelected) {
+      onAnimationsSelected(Array.from(newSelected));
+    }
+  };
+
+  // Handle delete
+  const handleDelete = () => {
+    const toDelete = animations.filter(anim => !selectedAnimations.has(anim.path));
+    const deletePaths = toDelete.map(anim => anim.path);
+    
+    if (deletePaths.length === 0) {
+      alert('No animations to delete. Select animations to keep, then delete will remove the unselected ones.');
+      return;
+    }
+    
+    if (window.confirm(`Are you sure you want to delete ${deletePaths.length} animation(s)?\n\nThis will delete:\n${deletePaths.slice(0, 5).join('\n')}${deletePaths.length > 5 ? '\n...' : ''}`)) {
+      if (onDeleteAnimations) {
+        onDeleteAnimations(deletePaths);
+      }
+      
+      // Remove deleted animations from state
+      setAnimations(animations.filter(anim => selectedAnimations.has(anim.path)));
+      setSelectedAnimations(new Set());
+    }
+  };
+
+  // Handle play animation
+  const handlePlay = (path) => {
+    if (onAnimationPlay) {
+      onAnimationPlay(path);
+    }
+  };
+
+  if (isLoading) {
+    return (
+      <div style={{ padding: '20px', textAlign: 'center', ...style }}>
+        <p>Loading animations...</p>
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div style={{ padding: '20px', color: 'red', ...style }}>
+        <p>Error loading animations: {error}</p>
+      </div>
+    );
+  }
+
+  return (
+    <div style={{
+      padding: '20px',
+      backgroundColor: '#2a2a2a',
+      borderRadius: '8px',
+      color: '#fff',
+      ...style
+    }}>
+      <h2 style={{ marginTop: 0 }}>Animation Selector</h2>
+      <p style={{ color: '#aaa', fontSize: '14px' }}>
+        Click buttons to play animations. Select animations to keep, then delete will remove the rest.
+      </p>
+      
+      {/* Controls */}
+      <div style={{ 
+        display: 'flex', 
+        gap: '10px', 
+        marginBottom: '20px',
+        flexWrap: 'wrap',
+        alignItems: 'center'
+      }}>
+        {/* Search */}
+        <input
+          type="text"
+          placeholder="Search animations..."
+          value={searchTerm}
+          onChange={(e) => setSearchTerm(e.target.value)}
+          style={{
+            padding: '8px 12px',
+            borderRadius: '6px',
+            border: '1px solid #555',
+            backgroundColor: '#333',
+            color: '#fff',
+            fontSize: '14px',
+            flex: '1',
+            minWidth: '200px'
+          }}
+        />
+        
+        {/* Group Filter */}
+        <select
+          value={filterGroup}
+          onChange={(e) => setFilterGroup(e.target.value)}
+          style={{
+            padding: '8px 12px',
+            borderRadius: '6px',
+            border: '1px solid #555',
+            backgroundColor: '#333',
+            color: '#fff',
+            fontSize: '14px'
+          }}
+        >
+          {groups.map(group => (
+            <option key={group} value={group}>
+              {group === 'all' ? 'All Groups' : group}
+            </option>
+          ))}
+        </select>
+        
+        {/* Selection Controls */}
+        <button
+          onClick={selectAll}
+          style={{
+            padding: '8px 16px',
+            backgroundColor: '#4CAF50',
+            color: 'white',
+            border: 'none',
+            borderRadius: '6px',
+            cursor: 'pointer',
+            fontSize: '14px'
+          }}
+        >
+          Select All Visible
+        </button>
+        
+        <button
+          onClick={deselectAll}
+          style={{
+            padding: '8px 16px',
+            backgroundColor: '#666',
+            color: 'white',
+            border: 'none',
+            borderRadius: '6px',
+            cursor: 'pointer',
+            fontSize: '14px'
+          }}
+        >
+          Deselect All Visible
+        </button>
+        
+        {/* Delete Button */}
+        <button
+          onClick={handleDelete}
+          style={{
+            padding: '8px 16px',
+            backgroundColor: '#f44336',
+            color: 'white',
+            border: 'none',
+            borderRadius: '6px',
+            cursor: 'pointer',
+            fontSize: '14px',
+            fontWeight: 'bold'
+          }}
+        >
+          Delete Unselected ({animations.length - selectedAnimations.size})
+        </button>
+      </div>
+      
+      {/* Stats */}
+      <div style={{ 
+        marginBottom: '15px',
+        fontSize: '14px',
+        color: '#aaa'
+      }}>
+        Total: {animations.length} | 
+        Selected: {selectedAnimations.size} | 
+        Showing: {filteredAnimations.length}
+      </div>
+      
+      {/* Animation Grid */}
+      <div style={{
+        display: 'grid',
+        gridTemplateColumns: 'repeat(auto-fill, minmax(200px, 1fr))',
+        gap: '10px',
+        maxHeight: '500px',
+        overflowY: 'auto',
+        padding: '10px',
+        backgroundColor: '#1a1a1a',
+        borderRadius: '6px'
+      }}>
+        {filteredAnimations.map((anim, index) => {
+          const isSelected = selectedAnimations.has(anim.path);
+          
+          return (
+            <div
+              key={`${anim.path}-${index}`}
+              style={{
+                border: `2px solid ${isSelected ? '#4CAF50' : '#555'}`,
+                borderRadius: '6px',
+                padding: '10px',
+                backgroundColor: isSelected ? '#2a4a2a' : '#222',
+                cursor: 'pointer',
+                transition: 'all 0.2s'
+              }}
+              onClick={() => toggleSelection(anim.path)}
+            >
+              {/* Checkbox */}
+              <div style={{ marginBottom: '8px' }}>
+                <input
+                  type="checkbox"
+                  checked={isSelected}
+                  onChange={() => toggleSelection(anim.path)}
+                  onClick={(e) => e.stopPropagation()}
+                  style={{
+                    marginRight: '8px',
+                    cursor: 'pointer'
+                  }}
+                />
+                <span style={{ fontSize: '12px', color: '#aaa' }}>
+                  {anim.group} {anim.gender !== 'root' && `(${anim.gender})`}
+                </span>
+              </div>
+              
+              {/* Animation Name */}
+              <div style={{
+                fontSize: '13px',
+                fontWeight: 'bold',
+                marginBottom: '8px',
+                wordBreak: 'break-word'
+              }}>
+                {anim.name}
+              </div>
+              
+              {/* Play Button */}
+              <button
+                onClick={(e) => {
+                  e.stopPropagation();
+                  handlePlay(anim.path);
+                }}
+                style={{
+                  width: '100%',
+                  padding: '6px',
+                  backgroundColor: '#2196F3',
+                  color: 'white',
+                  border: 'none',
+                  borderRadius: '4px',
+                  cursor: 'pointer',
+                  fontSize: '12px'
+                }}
+              >
+                ▶ Play
+              </button>
+            </div>
+          );
+        })}
+      </div>
+      
+      {filteredAnimations.length === 0 && (
+        <div style={{ 
+          padding: '40px',
+          textAlign: 'center',
+          color: '#aaa'
+        }}>
+          No animations found matching your filters.
+        </div>
+      )}
+    </div>
+  );
+}
+

package/src/index.js

@@ -8,6 +8,7 @@ export { default as TalkingHeadAvatar } from './components/TalkingHeadAvatar';
 export { default as TalkingHeadComponent } from './components/TalkingHeadComponent';
 export { default as SimpleTalkingAvatar } from './components/SimpleTalkingAvatar';
 export { default as CurriculumLearning } from './components/CurriculumLearning';
+export { AnimationSelector } from './components/AnimationSelector';
 export { getActiveTTSConfig, getVoiceOptions } from './config/ttsConfig';
 export { animations, getAnimation, hasAnimation } from './config/animations';
 

package/src/lib/talkinghead.mjs

@@ -1667,32 +1667,28 @@ class TalkingHead {
     const tempEuler = new THREE.Euler();
     const tempQuaternion = new THREE.Quaternion();
     
-    // Check if FBX animation is playing
-    const isFBXPlaying = this.mixer && this.currentFBXAction && this.currentFBXAction.isRunning();
-    
-    // Instead of forcing to a fixed value, reduce X rotation proportionally
-    // This maintains the relative relationship between shoulders and arms
-    // Natural relaxed shoulders: X rotation typically 0.3-0.6 radians
-    // High shoulders: X rotation > 0.8 radians
-    // We reduce high rotations by 40-50% to bring them down while maintaining arm relationships
-    const reductionFactor = isFBXPlaying ? 0.5 : 0.6; // Reduce by 50% during FBX, 40% otherwise
-    const maxAllowedX = 0.7; // Maximum allowed X rotation
+    // Research-based relaxed shoulder rotation values
+    // Natural relaxed shoulders: X rotation ~0.5-0.7 radians (much lower for natural look)
+    // High/stiff shoulders: X rotation ~1.5-1.8 radians
+    // We aggressively clamp to a very relaxed position
+    const targetX = 0.6; // Target X rotation for relaxed, natural shoulders (radians) - lowered significantly
+    const maxX = 0.7; // Maximum allowed X rotation - lowered significantly
     
     // Adjust left shoulder bone directly
     if (leftShoulderBone.quaternion) {
       tempEuler.setFromQuaternion(leftShoulderBone.quaternion, 'XYZ');
       const originalX = tempEuler.x;
       
-      // Reduce X rotation proportionally if it's too high
-      if (tempEuler.x > maxAllowedX) {
-        // Reduce by percentage to maintain arm-shoulder relationship
-        tempEuler.x = maxAllowedX + (tempEuler.x - maxAllowedX) * (1 - reductionFactor);
-      } else if (tempEuler.x > 0.5) {
-        // Slight reduction for moderately high shoulders
-        tempEuler.x = tempEuler.x * (1 - reductionFactor * 0.5);
+      // Aggressively clamp X rotation to relaxed position
+      if (tempEuler.x > maxX) {
+        // Force to target relaxed position
+        tempEuler.x = targetX;
+      } else if (tempEuler.x > targetX) {
+        // Smoothly reduce if slightly above target
+        tempEuler.x = targetX + (tempEuler.x - targetX) * 0.2; // More aggressive reduction
       }
       
-      // Only update if we changed something significantly
+      // Only update if we actually changed something
       if (Math.abs(tempEuler.x - originalX) > 0.01) {
         tempQuaternion.setFromEuler(tempEuler, 'XYZ');
         leftShoulderBone.quaternion.copy(tempQuaternion);
@@ -1705,16 +1701,16 @@ class TalkingHead {
       tempEuler.setFromQuaternion(rightShoulderBone.quaternion, 'XYZ');
       const originalX = tempEuler.x;
       
-      // Reduce X rotation proportionally if it's too high
-      if (tempEuler.x > maxAllowedX) {
-        // Reduce by percentage to maintain arm-shoulder relationship
-        tempEuler.x = maxAllowedX + (tempEuler.x - maxAllowedX) * (1 - reductionFactor);
-      } else if (tempEuler.x > 0.5) {
-        // Slight reduction for moderately high shoulders
-        tempEuler.x = tempEuler.x * (1 - reductionFactor * 0.5);
+      // Aggressively clamp X rotation to relaxed position
+      if (tempEuler.x > maxX) {
+        // Force to target relaxed position
+        tempEuler.x = targetX;
+      } else if (tempEuler.x > targetX) {
+        // Smoothly reduce if slightly above target
+        tempEuler.x = targetX + (tempEuler.x - targetX) * 0.2; // More aggressive reduction
       }
       
-      // Only update if we changed something significantly
+      // Only update if we actually changed something
       if (Math.abs(tempEuler.x - originalX) > 0.01) {
         tempQuaternion.setFromEuler(tempEuler, 'XYZ');
         rightShoulderBone.quaternion.copy(tempQuaternion);
@@ -5764,6 +5760,7 @@ class TalkingHead {
         // Filter and map animation tracks
         const mappedTracks = [];
         const unmappedBones = new Set();
+        let filteredShoulderTracks = 0;
         anim.tracks.forEach(track => {
           // Remove mixamorig prefix first
           let trackName = track.name.replaceAll('mixamorig', '');
@@ -5774,8 +5771,13 @@ class TalkingHead {
           // Map bone name to avatar skeleton
           const mappedBoneName = mapBoneName(fbxBoneName);
           
-          // Note: We allow shoulder rotation tracks to play so arms position correctly
-          // The shoulder adjustment function will override them after animation updates
+          // Filter out shoulder rotation tracks - we'll control shoulders manually
+          if (mappedBoneName && (mappedBoneName === 'LeftShoulder' || mappedBoneName === 'RightShoulder')) {
+            if (property === 'quaternion' || property === 'rotation') {
+              filteredShoulderTracks++;
+              return; // Skip this track - don't add it to mappedTracks
+            }
+          }
           
           if (mappedBoneName && property) {
             // Create new track with mapped bone name
@@ -5804,6 +5806,10 @@ class TalkingHead {
           }
         });
         
+        if (filteredShoulderTracks > 0) {
+          console.log(`✓ Filtered out ${filteredShoulderTracks} shoulder rotation track(s) to prevent high shoulders`);
+        }
+        
         if (unmappedBones.size > 0) {
           console.warn(`⚠️ ${unmappedBones.size} bone(s) could not be mapped:`, Array.from(unmappedBones).sort().join(', '));
         }