narrator-avatar 1.0.4 → 1.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +34 -57
  2. package/dist/narrator-avatar.js +35280 -421
  3. package/dist/narrator-avatar.umd.cjs +4066 -5
  4. package/package.json +7 -6
  5. package/dist/narrator-avatar.js.map +0 -1
  6. package/dist/narrator-avatar.umd.cjs.map +0 -1
package/README.md CHANGED
@@ -8,17 +8,17 @@ React component for 3D talking avatars with lip-sync, Deepgram or Google TTS, co
8
8
  ## Features
9
9
 
10
10
  - **3D avatars** – Ready Player Me–compatible GLB models (full-body)
11
- - **Lip-sync** – Word-level sync with Deepgram or Google TTS
11
+ - **Lip-sync** – Word-level sync with Deepgram or Google TTS (English bundled; other languages need extra setup)
12
12
  - **TTS** – Deepgram (streaming) or Google Cloud Text-to-Speech
13
- - **Gestures** – Content-aware hand gestures using all 8 built-in: handup, index, ok, thumbup, thumbdown, side, shrug, namaste
13
+ - **Gestures** – Content-aware hand gestures: handup, index, ok, thumbup, side, shrug
14
14
  - **Playback** – Speak, Pause, Resume, Stop (phrase-level in accurate mode)
15
+ - **Avatar Studio controls** – Visual presets, skin gloss/pores/warmth, eye contact, and mood
15
16
  - **Accessibility** – Subtitle callback for closed captions
16
17
 
17
18
  ## Table of contents
18
19
 
19
20
  - [Install](#install)
20
21
  - [Usage](#usage)
21
- - [Using with Vite](#using-with-vite-dev-and-production)
22
22
  - [Props](#props)
23
23
  - [Ref API](#ref-api)
24
24
  - [Environment variables](#environment-variables)
@@ -31,9 +31,7 @@ React component for 3D talking avatars with lip-sync, Deepgram or Google TTS, co
31
31
  npm install narrator-avatar
32
32
  ```
33
33
 
34
- Peer dependencies (React 18+) and `@met4citizen/talkinghead` are installed automatically.
35
-
36
- **Using Vite?** You must add the Vite config and an import map or the avatar will fail in both dev and production. See [Using with Vite](#using-with-vite-dev-and-production).
34
+ Peer dependencies (React 18+) are installed automatically. The package bundles TalkingHead, Three.js, and English lip-sync—**no import maps or Vite config required.**
37
35
 
38
36
  ## Usage
39
37
 
@@ -55,10 +53,13 @@ function MyPage() {
55
53
  ttsApiKey={import.meta.env.VITE_DEEPGRAM_API_KEY}
56
54
  accurateLipSync={true}
57
55
  speechRate={0.9}
58
- onReady={() => console.log('Ready')}
59
- onSpeechStart={(text) => console.log('Started:', text)}
60
- onSpeechEnd={() => console.log('Ended')}
61
- onSubtitle={(text) => console.log('Subtitle:', text)}
56
+ visualPreset="beauty"
57
+ skinGloss={1.5}
58
+ skinPores={2}
59
+ onReady={() => {}}
60
+ onSpeechStart={() => {}}
61
+ onSpeechEnd={() => {}}
62
+ onSubtitle={() => {}}
62
63
  />
63
64
  <button onClick={() => avatarRef.current?.speakText('Hello! How are you?')}>
64
65
  Speak
@@ -66,63 +67,21 @@ function MyPage() {
66
67
  <button onClick={() => avatarRef.current?.pauseSpeaking()}>Pause</button>
67
68
  <button onClick={() => avatarRef.current?.resumeSpeaking()}>Resume</button>
68
69
  <button onClick={() => avatarRef.current?.stopSpeaking()}>Stop</button>
70
+ <button onClick={() => avatarRef.current?.makeEyeContact(2000)}>
71
+ Eye contact
72
+ </button>
69
73
  </div>
70
74
  );
71
75
  }
72
76
  ```
73
77
 
74
- ## Using with Vite (dev and production)
75
-
76
- **Required.** The underlying `@met4citizen/talkinghead` package loads lip-sync language modules via dynamic `import()`. If Vite bundles or pre-bundles it, those imports break and you get a 404 on `lipsync-en.mjs` and **`Cannot read properties of undefined (reading 'preProcessText')`** in both dev and production.
77
-
78
- Do **all three** of the following.
79
-
80
- ### 1. Vite config
81
-
82
- ```js
83
- // vite.config.js or vite.config.ts
84
- import { defineConfig } from 'vite';
85
- import react from '@vitejs/plugin-react';
86
-
87
- export default defineConfig({
88
- plugins: [react()],
89
- optimizeDeps: { exclude: ['@met4citizen/talkinghead'] },
90
- build: {
91
- rollupOptions: {
92
- external: ['@met4citizen/talkinghead', 'three'],
93
- },
94
- },
95
- });
96
- ```
97
-
98
- ### 2. Import map in `index.html`
99
-
100
- Add this **before** your main script (e.g. before `<script type="module" src="/src/main.jsx">`). It loads talkinghead (and three) from the CDN so the lip-sync modules resolve correctly in production.
101
-
102
- ```html
103
- <script type="importmap">
104
- {
105
- "imports": {
106
- "@met4citizen/talkinghead": "https://cdn.jsdelivr.net/npm/@met4citizen/talkinghead@1.7.0/modules/talkinghead.mjs",
107
- "three": "https://cdn.jsdelivr.net/npm/three@0.180.0/build/three.module.js",
108
- "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.180.0/examples/jsm/"
109
- }
110
- }
111
- </script>
112
- ```
113
-
114
- ### 3. Restart and rebuild
115
-
116
- - **Dev:** restart the dev server after changing the config.
117
- - **Production:** run `npm run build` again and redeploy.
118
-
119
78
  ## Props
120
79
 
121
80
  | Prop | Description |
122
81
  |------|-------------|
123
82
  | `avatarUrl` | URL to GLB model (e.g. `/avatars/brunette.glb`) |
124
83
  | `avatarBody` | `'M'` or `'F'` for posture |
125
- | `cameraView` | Camera framing (default `'mid'`) |
84
+ | `cameraView` | Camera framing: `'full'`, `'mid'`, `'upper'`, `'head'` (default `'mid'`) |
126
85
  | `cameraRotateEnable` | Allow mouse drag to rotate view (default `false`). Set `true` to enable. |
127
86
  | `cameraZoomEnable` | Allow mouse wheel to zoom (default `false`). Set `true` to enable. |
128
87
  | `cameraPanEnable` | Allow mouse to pan (default `false`) |
@@ -131,7 +90,15 @@ Add this **before** your main script (e.g. before `<script type="module" src="/s
131
90
  | `ttsApiKey` | API key (or set `VITE_DEEPGRAM_API_KEY` / `VITE_GOOGLE_TTS_API_KEY`) |
132
91
  | `lipsyncModules` | Array of language codes (default `['en']`) |
133
92
  | `lipsyncLang` | Lip-sync language (default `'en'`) |
134
- | `accurateLipSync` | `true` = REST per phrase, best lip-sync + pause/resume |
93
+ | `visualPreset` | Lighting preset: `'cinematic'`, `'beauty'`, `'studio'`, `'sunset'`, `'broadcast'` |
94
+ | `skinGloss` | Skin sheen/sweat intensity from `0` to `2` |
95
+ | `skinPores` | Procedural pore/normal intensity from `0` to `2` |
96
+ | `skinWarmth` | Warm skin tone blend from `0` to `2` |
97
+ | `eyeContactIntensity` | Eye openness/contact strength from `0` to `2` |
98
+ | `dracoEnabled`, `dracoDecoderPath` | Enable Draco-compressed avatar loading |
99
+ | `modelDynamicBones` | TalkingHead dynamic-bone config for rigged hair/body parts |
100
+ | `update` | Per-frame callback `(dt, talkingHead)` |
101
+ | `accurateLipSync` | `true` = REST per phrase, best lip-sync + pause/resume. Default `true` for stable tutor playback |
135
102
  | `speechRate` | e.g. `0.9` for 10% slower (pitch-preserving) |
136
103
  | `speechGestures` | Content-aware hand gestures (default `true`) |
137
104
  | `onReady`, `onError`, `onSpeechStart`, `onSpeechEnd`, `onSubtitle` | Callbacks |
@@ -144,6 +111,16 @@ Add this **before** your main script (e.g. before `<script type="module" src="/s
144
111
  | `pauseSpeaking()` | Pause (phrase-level when `accurateLipSync` is true) |
145
112
  | `resumeSpeaking()` | Resume from next phrase |
146
113
  | `stopSpeaking()` | Stop and clear |
114
+ | `makeEyeContact(durationMs?)` | Ask the avatar to hold stronger eye contact |
115
+ | `setMood(mood)` | Change TalkingHead mood |
116
+ | `setLighting(options)` | Pass lighting options to TalkingHead |
117
+ | `setView(view, options?)` | Change camera view |
118
+ | `playGesture(name, dur?, mirror?, ms?)` | Play a built-in gesture |
119
+ | `playAnimation(url, onprogress?, dur?, ndx?, scale?)` | Play a Mixamo/RPM FBX animation |
120
+ | `playPose(url, onprogress?, dur?, ndx?, scale?)` | Play a Mixamo/RPM FBX pose |
121
+ | `stopAnimation()`, `stopPose()` | Stop active animation or pose |
122
+ | `setMixerGain(speech, background?, fadeSecs?)` | Adjust speech/background audio gain |
123
+ | `playBackgroundAudio(url)`, `stopBackgroundAudio()` | Control background audio |
147
124
  | `isReady` | Whether the avatar has finished loading |
148
125
  | `isSpeaking` | Whether the avatar is currently speaking |
149
126