narrator-avatar

React component for 3D talking avatars with lip-sync, Deepgram or Google TTS, content-aware hand gestures, and pause/resume. Built on @met4citizen/talkinghead.

Features

• 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
• Playback – Speak, Pause, Resume, Stop (phrase-level in accurate mode)
• Accessibility – Subtitle callback for closed captions

Table of contents

• Install
• Usage
• Props
• Ref API
• Environment variables
• TypeScript
• License

Install

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.

Usage

import { useRef } from 'react';
import NarratorAvatar from 'narrator-avatar';

function MyPage() {
  const avatarRef = useRef(null);

  return (
    <div style={{ width: '400px', height: '500px' }}>
      <NarratorAvatar
        ref={avatarRef}
        avatarUrl="/avatars/brunette.glb"
        avatarBody="F"
        ttsService="deepgram"
        ttsVoice="aura-2-aurora-en"
        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)}
      />
      <button onClick={() => avatarRef.current?.speakText('Hello! How are you?')}>
        Speak
      </button>
      <button onClick={() => avatarRef.current?.pauseSpeaking()}>Pause</button>
      <button onClick={() => avatarRef.current?.resumeSpeaking()}>Resume</button>
      <button onClick={() => avatarRef.current?.stopSpeaking()}>Stop</button>
    </div>
  );
}

Props

| Prop | Description | |------|-------------| | avatarUrl | URL to GLB model (e.g. /avatars/brunette.glb) | | avatarBody | 'M' or 'F' for posture | | cameraView | Camera framing (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) | | ttsService | 'google' or 'deepgram' | | ttsVoice | Deepgram: e.g. aura-2-mars-en, aura-2-aurora-en. Google: e.g. en-GB-Standard-A | | 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 | | speechRate | e.g. 0.9 for 10% slower (pitch-preserving) | | speechGestures | Content-aware hand gestures (default true) | | onReady, onError, onSpeechStart, onSpeechEnd, onSubtitle | Callbacks |

Ref API

| Method / property | Description | |-------------------|-------------| | speakText(text, options?) | Speak text via TTS | | pauseSpeaking() | Pause (phrase-level when accurateLipSync is true) | | resumeSpeaking() | Resume from next phrase | | stopSpeaking() | Stop and clear | | isReady | Whether the avatar has finished loading | | isSpeaking | Whether the avatar is currently speaking |

Environment variables

| Variable | Use | |----------|-----| | VITE_DEEPGRAM_API_KEY | Deepgram TTS (or pass ttsApiKey prop) | | VITE_GOOGLE_TTS_API_KEY | Google TTS when ttsService="google" (or pass ttsApiKey) |

TypeScript

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.

License

MIT