@sage-rsc/talking-head-react 1.0.69 → 1.0.71

package/package.json

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

@@ -0,0 +1,444 @@
+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';
+
+/**
+ * SimpleTalkingAvatar - A simple React component for 3D talking avatars
+ * 
+ * This component provides all avatar settings and functionality without curriculum features.
+ * You can pass text to speak via props or use the ref methods.
+ * 
+ * @param {Object} props
+ * @param {string} props.text - Text to speak (optional, can also use speakText method)
+ * @param {string} props.avatarUrl - URL/path to the GLB avatar file
+ * @param {string} props.avatarBody - Avatar body type ('M' or 'F')
+ * @param {string} props.mood - Initial mood ('happy', 'sad', 'neutral', etc.)
+ * @param {string} props.ttsLang - Text-to-speech language code
+ * @param {string} props.ttsService - TTS service ('edge', 'elevenlabs', 'deepgram', 'google', 'azure', 'browser')
+ * @param {string} props.ttsVoice - TTS voice ID
+ * @param {string} props.ttsApiKey - TTS API key (overrides config for ElevenLabs, Google Cloud, Azure)
+ * @param {string} props.bodyMovement - Initial body movement type
+ * @param {number} props.movementIntensity - Movement intensity (0-1)
+ * @param {boolean} props.showFullAvatar - Whether to show full body avatar
+ * @param {string} props.cameraView - Camera view ('upper', 'full', etc.)
+ * @param {Function} props.onReady - Callback when avatar is ready
+ * @param {Function} props.onLoading - Callback for loading progress
+ * @param {Function} props.onError - Callback for errors
+ * @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 {boolean} props.autoSpeak - Whether to automatically speak the text prop when ready
+ * @param {Object} ref - Ref to access component methods
+ */
+const SimpleTalkingAvatar = forwardRef(({ 
+  text = null,
+  avatarUrl = "/avatars/brunette.glb",
+  avatarBody = "F",
+  mood = "neutral",
+  ttsLang = "en",
+  ttsService = null,
+  ttsVoice = null,
+  ttsApiKey = null,
+  bodyMovement = "idle",
+  movementIntensity = 0.5,
+  showFullAvatar = false,
+  cameraView = "upper",
+  onReady = () => {},
+  onLoading = () => {},
+  onError = () => {},
+  onSpeechEnd = () => {},
+  className = "",
+  style = {},
+  animations = {},
+  autoSpeak = false
+}, ref) => {
+  const containerRef = useRef(null);
+  const talkingHeadRef = useRef(null);
+  const showFullAvatarRef = useRef(showFullAvatar);
+  const pausedSpeechRef = useRef(null);
+  const speechEndIntervalRef = useRef(null);
+  const isPausedRef = useRef(false);
+  const speechProgressRef = useRef({ remainingText: null, originalText: null, options: null });
+  const originalSentencesRef = useRef([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState(null);
+  const [isReady, setIsReady] = useState(false);
+  const [isPaused, setIsPaused] = useState(false);
+  
+  // Keep ref in sync with state
+  useEffect(() => {
+    isPausedRef.current = isPaused;
+  }, [isPaused]);
+
+  // Update ref when prop changes
+  useEffect(() => {
+    showFullAvatarRef.current = showFullAvatar;
+  }, [showFullAvatar]);
+
+  // Get TTS configuration
+  const ttsConfig = getActiveTTSConfig();
+
+  // Override TTS service if specified in props
+  const effectiveTtsService = ttsService || ttsConfig.service;
+  
+  // Build effective TTS config
+  let effectiveTtsConfig;
+  
+  if (effectiveTtsService === 'browser') {
+    effectiveTtsConfig = {
+      service: 'browser',
+      endpoint: '',
+      apiKey: null,
+      defaultVoice: 'Google US English'
+    };
+  } else if (effectiveTtsService === 'elevenlabs') {
+    const apiKey = ttsApiKey || ttsConfig.apiKey;
+    effectiveTtsConfig = {
+      service: 'elevenlabs',
+      endpoint: 'https://api.elevenlabs.io/v1/text-to-speech',
+      apiKey: apiKey,
+      defaultVoice: ttsVoice || ttsConfig.defaultVoice || ELEVENLABS_CONFIG.defaultVoice,
+      voices: ttsConfig.voices || ELEVENLABS_CONFIG.voices
+    };
+  } else if (effectiveTtsService === 'deepgram') {
+    const apiKey = ttsApiKey || ttsConfig.apiKey;
+    effectiveTtsConfig = {
+      service: 'deepgram',
+      endpoint: 'https://api.deepgram.com/v1/speak',
+      apiKey: apiKey,
+      defaultVoice: ttsVoice || ttsConfig.defaultVoice || DEEPGRAM_CONFIG.defaultVoice,
+      voices: ttsConfig.voices || DEEPGRAM_CONFIG.voices
+    };
+  } else {
+    effectiveTtsConfig = {
+      ...ttsConfig,
+      apiKey: ttsApiKey !== null ? ttsApiKey : ttsConfig.apiKey
+    };
+  }
+
+  const defaultAvatarConfig = {
+    url: avatarUrl,
+    body: avatarBody,
+    avatarMood: mood,
+    ttsLang: effectiveTtsService === 'browser' ? "en-US" : ttsLang,
+    ttsVoice: ttsVoice || effectiveTtsConfig.defaultVoice,
+    lipsyncLang: 'en',
+    showFullAvatar: showFullAvatar,
+    bodyMovement: bodyMovement,
+    movementIntensity: movementIntensity,
+  };
+  
+  const defaultOptions = {
+    ttsEndpoint: effectiveTtsConfig.endpoint,
+    ttsApikey: effectiveTtsConfig.apiKey,
+    ttsService: effectiveTtsService,
+    lipsyncModules: ["en"],
+    cameraView: cameraView
+  };
+
+  const initializeTalkingHead = useCallback(async () => {
+    if (!containerRef.current || talkingHeadRef.current) return;
+
+    try {
+      setIsLoading(true);
+      setError(null);
+
+      talkingHeadRef.current = new TalkingHead(containerRef.current, defaultOptions);
+
+      await talkingHeadRef.current.showAvatar(defaultAvatarConfig, (ev) => {
+        if (ev.lengthComputable) {
+          const progress = Math.min(100, Math.round(ev.loaded / ev.total * 100));
+          onLoading(progress);
+        }
+      });
+
+      setIsLoading(false);
+      setIsReady(true);
+      onReady(talkingHeadRef.current);
+
+      // Handle visibility change
+      const handleVisibilityChange = () => {
+        if (document.visibilityState === "visible") {
+          talkingHeadRef.current?.start();
+        } else {
+          talkingHeadRef.current?.stop();
+        }
+      };
+
+      document.addEventListener("visibilitychange", handleVisibilityChange);
+
+      return () => {
+        document.removeEventListener("visibilitychange", handleVisibilityChange);
+      };
+
+    } catch (err) {
+      console.error('Error initializing TalkingHead:', err);
+      setError(err.message || 'Failed to initialize avatar');
+      setIsLoading(false);
+      onError(err);
+    }
+  }, []); // Empty deps - only initialize once
+
+  useEffect(() => {
+    initializeTalkingHead();
+
+    return () => {
+      if (talkingHeadRef.current) {
+        talkingHeadRef.current.stop();
+        talkingHeadRef.current.dispose();
+        talkingHeadRef.current = null;
+      }
+    };
+  }, [initializeTalkingHead]);
+
+  // Resume audio context helper
+  const resumeAudioContext = useCallback(async () => {
+    if (talkingHeadRef.current) {
+      try {
+        // Try to access audio context through talkingHead instance
+        const audioCtx = talkingHeadRef.current.audioCtx || talkingHeadRef.current.audioContext;
+        if (audioCtx && (audioCtx.state === 'suspended' || audioCtx.state === 'interrupted')) {
+          await audioCtx.resume();
+          console.log('Audio context resumed');
+        }
+      } catch (err) {
+        console.warn('Failed to resume audio context:', err);
+      }
+    }
+  }, []);
+
+  // Auto-speak text when ready and autoSpeak is true
+  useEffect(() => {
+    if (isReady && text && autoSpeak && talkingHeadRef.current) {
+      speakText(text);
+    }
+  }, [isReady, text, autoSpeak, speakText]);
+
+  // Speak text with proper callback handling
+  const speakText = useCallback(async (textToSpeak, options = {}) => {
+    if (!talkingHeadRef.current || !isReady) {
+      console.warn('Avatar not ready for speaking');
+      return;
+    }
+
+    if (!textToSpeak || textToSpeak.trim() === '') {
+      console.warn('No text provided to speak');
+      return;
+    }
+
+    // Always resume audio context first (required for user interaction)
+    await resumeAudioContext();
+
+    // Reset speech progress tracking
+    speechProgressRef.current = { remainingText: null, originalText: null, options: null };
+    originalSentencesRef.current = [];
+    
+    // Store for pause/resume
+    pausedSpeechRef.current = { text: textToSpeak, options };
+    
+    // Clear any existing speech end interval
+    if (speechEndIntervalRef.current) {
+      clearInterval(speechEndIntervalRef.current);
+      speechEndIntervalRef.current = null;
+    }
+
+    // Reset pause state
+    setIsPaused(false);
+    isPausedRef.current = false;
+
+    // Split text into sentences for tracking
+    const sentences = textToSpeak.split(/[.!?]+/).filter(s => s.trim().length > 0);
+    originalSentencesRef.current = sentences;
+
+    const speakOptions = {
+      lipsyncLang: options.lipsyncLang || 'en',
+      onSpeechEnd: () => {
+        // Clear interval
+        if (speechEndIntervalRef.current) {
+          clearInterval(speechEndIntervalRef.current);
+          speechEndIntervalRef.current = null;
+        }
+
+        // Call user's onSpeechEnd callback
+        if (options.onSpeechEnd) {
+          options.onSpeechEnd();
+        }
+        onSpeechEnd();
+      }
+    };
+
+    try {
+      talkingHeadRef.current.speakText(textToSpeak, speakOptions);
+    } catch (err) {
+      console.error('Error speaking text:', err);
+      setError(err.message || 'Failed to speak text');
+    }
+  }, [isReady, onSpeechEnd, resumeAudioContext]);
+
+  // Pause speaking
+  const pauseSpeaking = useCallback(() => {
+    if (!talkingHeadRef.current) return;
+
+    try {
+      // Check if currently speaking
+      const isSpeaking = talkingHeadRef.current.isSpeaking || false;
+      const audioPlaylist = talkingHeadRef.current.audioPlaylist || [];
+      const speechQueue = talkingHeadRef.current.speechQueue || [];
+
+      if (isSpeaking || audioPlaylist.length > 0 || speechQueue.length > 0) {
+        // Clear speech end interval
+        if (speechEndIntervalRef.current) {
+          clearInterval(speechEndIntervalRef.current);
+          speechEndIntervalRef.current = null;
+        }
+
+        // Extract remaining text from speech queue
+        let remainingText = '';
+        if (speechQueue.length > 0) {
+          remainingText = speechQueue.map(item => {
+            if (item.text && Array.isArray(item.text)) {
+              return item.text.map(wordObj => wordObj.word).join(' ');
+            }
+            return item.text || '';
+          }).join(' ');
+        }
+
+        // Store progress for resume
+        speechProgressRef.current = {
+          remainingText: remainingText || null,
+          originalText: pausedSpeechRef.current?.text || null,
+          options: pausedSpeechRef.current?.options || null
+        };
+
+        // Clear speech queue and pause
+        talkingHeadRef.current.speechQueue.length = 0;
+        talkingHeadRef.current.pauseSpeaking();
+        setIsPaused(true);
+        isPausedRef.current = true;
+      }
+    } catch (err) {
+      console.warn('Error pausing speech:', err);
+    }
+  }, []);
+
+  // Resume speaking
+  const resumeSpeaking = useCallback(async () => {
+    if (!talkingHeadRef.current || !isPaused) return;
+
+    try {
+      // Resume audio context first
+      await resumeAudioContext();
+
+      setIsPaused(false);
+      isPausedRef.current = false;
+
+      // Determine what text to speak
+      const remainingText = speechProgressRef.current?.remainingText;
+      const originalText = speechProgressRef.current?.originalText || pausedSpeechRef.current?.text;
+      const originalOptions = speechProgressRef.current?.options || pausedSpeechRef.current?.options || {};
+
+      const textToSpeak = remainingText || originalText;
+
+      if (textToSpeak) {
+        speakText(textToSpeak, originalOptions);
+      }
+    } catch (err) {
+      console.warn('Error resuming speech:', err);
+      setIsPaused(false);
+      isPausedRef.current = false;
+    }
+  }, [isPaused, speakText, resumeAudioContext]);
+
+  // Stop speaking
+  const stopSpeaking = useCallback(() => {
+    if (talkingHeadRef.current) {
+      talkingHeadRef.current.stopSpeaking();
+      if (speechEndIntervalRef.current) {
+        clearInterval(speechEndIntervalRef.current);
+        speechEndIntervalRef.current = null;
+      }
+      setIsPaused(false);
+      isPausedRef.current = false;
+    }
+  }, []);
+
+  // Expose methods via ref
+  useImperativeHandle(ref, () => ({
+    speakText,
+    pauseSpeaking,
+    resumeSpeaking,
+    stopSpeaking,
+    resumeAudioContext,
+    isPaused: () => isPaused,
+    setMood: (mood) => talkingHeadRef.current?.setMood(mood),
+    setBodyMovement: (movement) => {
+      if (talkingHeadRef.current) {
+        talkingHeadRef.current.setBodyMovement(movement);
+      }
+    },
+    playAnimation: (animationName, disablePositionLock = false) => {
+      if (talkingHeadRef.current && talkingHeadRef.current.playAnimation) {
+        talkingHeadRef.current.playAnimation(animationName, null, 10, 0, 0.01, disablePositionLock);
+      }
+    },
+    playReaction: (reactionType) => talkingHeadRef.current?.playReaction(reactionType),
+    playCelebration: () => talkingHeadRef.current?.playCelebration(),
+    setShowFullAvatar: (show) => {
+      if (talkingHeadRef.current) {
+        showFullAvatarRef.current = show;
+        talkingHeadRef.current.setShowFullAvatar(show);
+      }
+    },
+    isReady,
+    talkingHead: talkingHeadRef.current
+  }));
+
+  return (
+    <div className={`simple-talking-avatar-container ${className}`} style={style}>
+      <div 
+        ref={containerRef} 
+        className="talking-head-viewer"
+        style={{ 
+          width: '100%', 
+          height: '100%',
+          minHeight: '400px',
+        }}
+      />
+      {isLoading && (
+        <div className="loading-overlay" style={{
+          position: 'absolute',
+          top: '50%',
+          left: '50%',
+          transform: 'translate(-50%, -50%)',
+          color: 'white',
+          fontSize: '18px',
+          zIndex: 10
+        }}>
+          Loading avatar...
+        </div>
+      )}
+      {error && (
+        <div className="error-overlay" style={{
+          position: 'absolute',
+          top: '50%',
+          left: '50%',
+          transform: 'translate(-50%, -50%)',
+          color: '#ff6b6b',
+          fontSize: '16px',
+          textAlign: 'center',
+          zIndex: 10,
+          padding: '20px',
+          borderRadius: '8px'
+        }}>
+          {error}
+        </div>
+      )}
+    </div>
+  );
+});
+
+SimpleTalkingAvatar.displayName = 'SimpleTalkingAvatar';
+
+export default SimpleTalkingAvatar;
+

package/src/index.js

@@ -6,6 +6,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 { getActiveTTSConfig, getVoiceOptions } from './config/ttsConfig';
 export { animations, getAnimation, hasAnimation } from './config/animations';