@sage-rsc/talking-head-react 1.1.2 → 1.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sage-rsc/talking-head-react",
-  "version": "1.1.2",
+  "version": "1.1.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/lib/talkinghead.mjs

@@ -2253,11 +2253,11 @@ class TalkingHead {
     if (this.lockedPosition && this.armature) {
       // Enforce the locked position - keep avatar exactly where it was locked
       // This prevents FBX animations from moving the avatar
-      this.armature.position.set(
-        this.lockedPosition.x,
+        this.armature.position.set(
+          this.lockedPosition.x,
         this.lockedPosition.y,
-        this.lockedPosition.z
-      );
+          this.lockedPosition.z
+        );
     }
   }
 
@@ -5354,6 +5354,7 @@ class TalkingHead {
 
     // Remove common prefixes
     let normalized = fbxBoneName;
+    const originalNormalized = normalized;
     
     // Remove CC_Base prefix (Character Creator)
     if (normalized.startsWith('CC_Base_')) {
@@ -5367,6 +5368,15 @@ class TalkingHead {
     if (availableBones.has(normalized)) {
       return normalized;
     }
+    
+    // Debug: Log first few failed mappings to help identify patterns
+    if (!this._mappingDebugLog) {
+      this._mappingDebugLog = new Set();
+    }
+    if (this._mappingDebugLog.size < 5 && !this._mappingDebugLog.has(fbxBoneName)) {
+      this._mappingDebugLog.add(fbxBoneName);
+      console.debug(`Mapping attempt: "${fbxBoneName}" -> "${normalized}" (not found in available bones)`);
+    }
 
     // Handle numbered bones (e.g., Spine01 -> Spine1)
     if (normalized.match(/^Spine\d+$/)) {
@@ -5409,6 +5419,9 @@ class TalkingHead {
       'L_Middle1': 'LeftHandMiddle1',
       'L_Middle2': 'LeftHandMiddle2',
       'L_Middle3': 'LeftHandMiddle3',
+      'L_Mid1': 'LeftHandMiddle1',
+      'L_Mid2': 'LeftHandMiddle2',
+      'L_Mid3': 'LeftHandMiddle3',
       'L_Ring1': 'LeftHandRing1',
       'L_Ring2': 'LeftHandRing2',
       'L_Ring3': 'LeftHandRing3',
@@ -5430,6 +5443,9 @@ class TalkingHead {
       'R_Middle1': 'RightHandMiddle1',
       'R_Middle2': 'RightHandMiddle2',
       'R_Middle3': 'RightHandMiddle3',
+      'R_Mid1': 'RightHandMiddle1',
+      'R_Mid2': 'RightHandMiddle2',
+      'R_Mid3': 'RightHandMiddle3',
       'R_Ring1': 'RightHandRing1',
       'R_Ring2': 'RightHandRing2',
       'R_Ring3': 'RightHandRing3',
@@ -5459,8 +5475,9 @@ class TalkingHead {
 
     // Pattern-based matching for CC_Base and similar naming conventions
     const lowerNormalized = normalized.toLowerCase();
+    const upperFirst = normalized.charAt(0).toUpperCase() + normalized.slice(1).toLowerCase();
     
-    // Pattern: R_Index1/2/3 -> RightHandIndex1/2/3
+    // Pattern: R_Index1/2/3 or r_index1/2/3 -> RightHandIndex1/2/3
     const indexMatch = lowerNormalized.match(/^[rl]_index(\d+)$/);
     if (indexMatch) {
       const digit = indexMatch[1];
@@ -5493,8 +5510,8 @@ class TalkingHead {
       }
     }
     
-    // Pattern: R_Middle1/2/3 -> RightHandMiddle1/2/3
-    const middleMatch = lowerNormalized.match(/^[rl]_middle(\d+)$/);
+    // Pattern: R_Middle1/2/3 or R_Mid1/2/3 -> RightHandMiddle1/2/3
+    const middleMatch = lowerNormalized.match(/^[rl]_(?:middle|mid)(\d+)$/);
     if (middleMatch) {
       const digit = middleMatch[1];
       const side = lowerNormalized.startsWith('r') ? 'Right' : 'Left';
@@ -5515,7 +5532,7 @@ class TalkingHead {
       }
     }
     
-    // Pattern: R_Upperarm -> RightArm
+    // Pattern: R_Upperarm -> RightArm (case insensitive)
     if (lowerNormalized.match(/^[rl]_upperarm/)) {
       const side = lowerNormalized.startsWith('r') ? 'Right' : 'Left';
       const candidate = `${side}Arm`;
@@ -5524,6 +5541,15 @@ class TalkingHead {
       }
     }
     
+    // Pattern: R_UpperarmTwist01/02 -> ignore (twist bones and other extra bones)
+    if (lowerNormalized.includes('upperarmtwist') || 
+        lowerNormalized.includes('forearmtwist') ||
+        lowerNormalized.includes('ribstwist') ||
+        lowerNormalized.includes('breast') ||
+        lowerNormalized.includes('twist')) {
+      return null;
+    }
+    
     // Pattern: R_Forearm -> RightForeArm
     if (lowerNormalized.match(/^[rl]_forearm/)) {
       const side = lowerNormalized.startsWith('r') ? 'Right' : 'Left';
@@ -5564,6 +5590,13 @@ class TalkingHead {
     const missingBones = new Set();
     const mappedBones = new Map(); // Track mappings for logging
     
+    // Debug: Log available bones (first time only)
+    if (!this._loggedAvailableBones) {
+      console.log('Available avatar bones:', Array.from(availableBones).sort().slice(0, 50).join(', '), 
+        availableBones.size > 50 ? `... (${availableBones.size} total)` : '');
+      this._loggedAvailableBones = true;
+    }
+    
     clip.tracks.forEach(track => {
       // Extract bone name from track name (e.g., "CC_Base_R_Index3.position" -> "CC_Base_R_Index3")
       const trackNameParts = track.name.split('.');
@@ -5581,6 +5614,72 @@ class TalkingHead {
         const newTrack = track.clone();
         newTrack.name = newTrackName;
         
+        // Fix rotations for arm/hand bones that might be inverted
+        // If hands are folding behind instead of in front, we need to adjust rotations
+        const isArmBone = mappedBoneName.includes('Arm') || mappedBoneName.includes('Hand') || mappedBoneName.includes('Shoulder');
+        const isForearmBone = mappedBoneName.includes('ForeArm');
+        
+        if (isArmBone && (property === 'quaternion' || property === 'rotation')) {
+          // For quaternion tracks, we might need to adjust the rotation
+          // Check if this is a quaternion track
+          if (property === 'quaternion' && newTrack.values && newTrack.values.length >= 4) {
+            // Quaternion format: [x, y, z, w] per keyframe
+            // For arm bones, we might need to invert Y or Z rotation
+            // Adjust quaternion values to fix hand position
+            const numKeyframes = newTrack.times.length;
+            for (let i = 0; i < numKeyframes; i++) {
+              const baseIdx = i * 4;
+              if (baseIdx + 3 < newTrack.values.length) {
+                // Get quaternion values
+                let x = newTrack.values[baseIdx];
+                let y = newTrack.values[baseIdx + 1];
+                let z = newTrack.values[baseIdx + 2];
+                let w = newTrack.values[baseIdx + 3];
+                
+                // For arms, adjust rotation to flip hands from back to front
+                // This is a common fix for FBX animations with different coordinate systems
+                if (isForearmBone || mappedBoneName.includes('Hand')) {
+                  // Rotate 180 degrees around X axis to flip hands from behind to in front
+                  // Create a 180-degree rotation around X axis
+                  const flipAngle = Math.PI;
+                  const flipX = Math.cos(flipAngle / 2); // w component
+                  const flipY = Math.sin(flipAngle / 2); // x component (axis X = 1,0,0)
+                  
+                  // Multiply quaternions: q_result = q_flip * q_original
+                  // For rotation around X axis: q_flip = (sin(θ/2), 0, 0, cos(θ/2))
+                  const qw = flipX * w - flipY * x;
+                  const qx = flipX * x + flipY * w;
+                  const qy = flipX * y - flipY * z;
+                  const qz = flipX * z + flipY * y;
+                  
+                  x = qx;
+                  y = qy;
+                  z = qz;
+                  w = qw;
+                }
+                
+                newTrack.values[baseIdx] = x;
+                newTrack.values[baseIdx + 1] = y;
+                newTrack.values[baseIdx + 2] = z;
+                newTrack.values[baseIdx + 3] = w;
+              }
+            }
+          } else if (property === 'rotation' && newTrack.values && newTrack.values.length >= 3) {
+            // Euler rotation format: [x, y, z] per keyframe
+            const numKeyframes = newTrack.times.length;
+            for (let i = 0; i < numKeyframes; i++) {
+              const baseIdx = i * 3;
+              if (baseIdx + 2 < newTrack.values.length) {
+                // For arm bones, adjust Y rotation to flip hands
+                if (isForearmBone || mappedBoneName.includes('Hand')) {
+                  // Add 180 degrees (PI radians) to Y rotation
+                  newTrack.values[baseIdx + 1] += Math.PI;
+                }
+              }
+            }
+          }
+        }
+        
         validTracks.push(newTrack);
         
         // Track mappings for logging