narrator-avatar 1.0.5 → 1.0.7

package/README.md

@@ -10,8 +10,9 @@ React component for 3D talking avatars with lip-sync, Deepgram or Google TTS, co
 - **3D avatars** – Ready Player Me–compatible GLB models (full-body)
 - **Lip-sync** – Word-level sync with Deepgram or Google TTS (English bundled; other languages need extra setup)
 - **TTS** – Deepgram (streaming) or Google Cloud Text-to-Speech
-- **Gestures** – Content-aware hand gestures using all 8 built-in: handup, index, ok, thumbup, thumbdown, side, shrug, namaste
+- **Gestures** – Content-aware hand gestures: handup, index, ok, thumbup, side, shrug
 - **Playback** – Speak, Pause, Resume, Stop (phrase-level in accurate mode)
+- **Avatar Studio controls** – Visual presets, skin gloss/pores/warmth, eye contact, and mood
 - **Accessibility** – Subtitle callback for closed captions
 
 ## Table of contents
@@ -30,7 +31,7 @@ React component for 3D talking avatars with lip-sync, Deepgram or Google TTS, co
 npm install narrator-avatar
 ```
 
-Peer dependencies (React 18+) are installed automatically. The package bundles TalkingHead, Three.js (0.151), and English lip-sync—**no import maps or Vite config required.**
+Peer dependencies (React 18+) are installed automatically. The package bundles TalkingHead, Three.js, and English lip-sync—**no import maps or Vite config required.**
 
 ## Usage
 
@@ -52,10 +53,13 @@ function MyPage() {
         ttsApiKey={import.meta.env.VITE_DEEPGRAM_API_KEY}
         accurateLipSync={true}
         speechRate={0.9}
-        onReady={() => console.log('Ready')}
-        onSpeechStart={(text) => console.log('Started:', text)}
-        onSpeechEnd={() => console.log('Ended')}
-        onSubtitle={(text) => console.log('Subtitle:', text)}
+        visualPreset="beauty"
+        skinGloss={1.5}
+        skinPores={2}
+        onReady={() => {}}
+        onSpeechStart={() => {}}
+        onSpeechEnd={() => {}}
+        onSubtitle={() => {}}
       />
       <button onClick={() => avatarRef.current?.speakText('Hello! How are you?')}>
         Speak
@@ -63,6 +67,9 @@ function MyPage() {
       <button onClick={() => avatarRef.current?.pauseSpeaking()}>Pause</button>
       <button onClick={() => avatarRef.current?.resumeSpeaking()}>Resume</button>
       <button onClick={() => avatarRef.current?.stopSpeaking()}>Stop</button>
+      <button onClick={() => avatarRef.current?.makeEyeContact(2000)}>
+        Eye contact
+      </button>
     </div>
   );
 }
@@ -74,7 +81,7 @@ function MyPage() {
 |------|-------------|
 | `avatarUrl` | URL to GLB model (e.g. `/avatars/brunette.glb`) |
 | `avatarBody` | `'M'` or `'F'` for posture |
-| `cameraView` | Camera framing (default `'mid'`) |
+| `cameraView` | Camera framing: `'full'`, `'mid'`, `'upper'`, `'head'` (default `'mid'`) |
 | `cameraRotateEnable` | Allow mouse drag to rotate view (default `false`). Set `true` to enable. |
 | `cameraZoomEnable` | Allow mouse wheel to zoom (default `false`). Set `true` to enable. |
 | `cameraPanEnable` | Allow mouse to pan (default `false`) |
@@ -83,7 +90,15 @@ function MyPage() {
 | `ttsApiKey` | API key (or set `VITE_DEEPGRAM_API_KEY` / `VITE_GOOGLE_TTS_API_KEY`) |
 | `lipsyncModules` | Array of language codes (default `['en']`) |
 | `lipsyncLang` | Lip-sync language (default `'en'`) |
-| `accurateLipSync` | `true` = REST per phrase, best lip-sync + pause/resume |
+| `visualPreset` | Lighting preset: `'cinematic'`, `'beauty'`, `'studio'`, `'sunset'`, `'broadcast'` |
+| `skinGloss` | Skin sheen/sweat intensity from `0` to `2` |
+| `skinPores` | Procedural pore/normal intensity from `0` to `2` |
+| `skinWarmth` | Warm skin tone blend from `0` to `2` |
+| `eyeContactIntensity` | Eye openness/contact strength from `0` to `2` |
+| `dracoEnabled`, `dracoDecoderPath` | Enable Draco-compressed avatar loading |
+| `modelDynamicBones` | TalkingHead dynamic-bone config for rigged hair/body parts |
+| `update` | Per-frame callback `(dt, talkingHead)` |
+| `accurateLipSync` | `true` = REST per phrase, best lip-sync + pause/resume. Default `true` for stable tutor playback |
 | `speechRate` | e.g. `0.9` for 10% slower (pitch-preserving) |
 | `speechGestures` | Content-aware hand gestures (default `true`) |
 | `onReady`, `onError`, `onSpeechStart`, `onSpeechEnd`, `onSubtitle` | Callbacks |
@@ -96,6 +111,16 @@ function MyPage() {
 | `pauseSpeaking()` | Pause (phrase-level when `accurateLipSync` is true) |
 | `resumeSpeaking()` | Resume from next phrase |
 | `stopSpeaking()` | Stop and clear |
+| `makeEyeContact(durationMs?)` | Ask the avatar to hold stronger eye contact |
+| `setMood(mood)` | Change TalkingHead mood |
+| `setLighting(options)` | Pass lighting options to TalkingHead |
+| `setView(view, options?)` | Change camera view |
+| `playGesture(name, dur?, mirror?, ms?)` | Play a built-in gesture |
+| `playAnimation(url, onprogress?, dur?, ndx?, scale?)` | Play a Mixamo/RPM FBX animation |
+| `playPose(url, onprogress?, dur?, ndx?, scale?)` | Play a Mixamo/RPM FBX pose |
+| `stopAnimation()`, `stopPose()` | Stop active animation or pose |
+| `setMixerGain(speech, background?, fadeSecs?)` | Adjust speech/background audio gain |
+| `playBackgroundAudio(url)`, `stopBackgroundAudio()` | Control background audio |
 | `isReady` | Whether the avatar has finished loading |
 | `isSpeaking` | Whether the avatar is currently speaking |