narrator-avatar 1.1.1 → 1.1.5

package/README.md

@@ -91,7 +91,8 @@ function MyPage() {
 | `lipsyncModules` | Array of language codes (default `['en']`) |
 | `lipsyncLang` | Lip-sync language (default `'en'`) |
 | `visualPreset` | Lighting preset: `'cinematic'`, `'beauty'`, `'studio'`, `'sunset'`, `'broadcast'` |
-| `visualQuality` | `'auto'` (default): ultra on desktop, balanced ultra on mobile. `'ultra'` \| `'balanced'` \| `'performance'` |
+| `visualQuality` | `'auto'` (default): ultra on desktop, balanced on mobile/slow network. `'ultra'` \| `'balanced'` \| `'performance'` |
+| `lazyMount` | `true` \| `false` \| `'auto'` (default): defer WebGL init until visible on mobile |
 | `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` |
@@ -137,24 +138,30 @@ function MyPage() {
 
 The package is JavaScript. For TypeScript, add a declaration file (e.g. `src/narrator-avatar.d.ts`) that declares the component props and ref type, or use the component with `// @ts-expect-error` if you prefer.
 
-## Performance (web and mobile)
+## Performance (web and mobile, one GLB per avatar)
 
-`visualQuality="auto"` (default) keeps **ultra-realistic** polish on desktop and a **balanced ultra** tier on mobile (same lighting and skin shaders, tuned GPU settings).
+Use **one** model URL per avatar (e.g. `/avatars/tutor.glb`). The component adapts at runtime — no `-mobile` / `-web` copies.
 
-Ship optimized GLBs beside each source model:
+| Mechanism | Desktop | Mobile / slow network |
+|-----------|---------|------------------------|
+| `visualQuality="auto"` | `ultra` — 60 FPS, 4K shadows, full skin polish | `balanced` — 24 FPS, capped resolution, no shadows, lightweight skin (TalkingHead lights only) |
+| `lazyMount="auto"` | init immediately | init when scrolled into view |
+| Load timeout | 30s | 90s (large GLB download) |
+| Tab hidden | animation paused | animation paused |
 
-| File | Use |
-|------|-----|
-| `avatar-web.glb` | Desktop / tablet (1024px textures, ~3–5MB) |
-| `avatar-mobile.glb` | Phones (512px textures, ~1–2MB) |
+```jsx
+<NarratorAvatar
+  avatarUrl="/avatars/test.glb"
+  visualQuality="auto"
+  lazyMount="auto"
+/>
+```
 
-`avatarUrl="/avatars/avatar.glb"` resolves automatically to `-web` or `-mobile`.
+**App tips:** mount only one avatar on narrow viewports; enable gzip/brotli for static `.glb` on your CDN/hosting.
 
-```bash
-npm run optimize-avatars   # in narrator-avatar-test
-```
+Keep `modelPixelRatio` near **1–1.25**. TalkingHead multiplies it again by `devicePixelRatio`.
 
-Keep `modelPixelRatio` near **1–1.25**. TalkingHead multiplies it again by `devicePixelRatio`; the old value of `4` meant up to 12× pixels on retina phones.
+**Next.js:** dedupe React in `next.config` (see `narrator-avatar-test/next.config.ts`).
 
 ## License