Skip to main content

Mascotbot React SDK

@mascotbot/react is the React layer of the Mascotbot avatar SDK. It gives you a provider, a few hooks, and a thin set of Rive components. Speech goes in; the avatar speaks in real time. This page is the map. Each area links to its dedicated guide.

Install

.npmrc
@rive-app/react-webgl2 + @rive-app/webgl2 are optional peer dependencies of the /rive subpath — install them only when you render an avatar. Full registry and key setup is in Installation.

The two subpaths

Composition

One provider, one component. <MascotProvider> owns the licensed inference engine; <Mascot> mounts the Rive avatar inside it.
<Mascot> accepts a pre-loaded rive instance you constructed yourself. The SDK only writes the mouth, is_speaking, and stress — everything else stays yours. See Rive co-existence.

Where to go next

Hooks reference

useMascot, useProcessAudio, useMascotRive, useMascotInputs, useMascotPlayback, useLipsyncStream, and more.

Offline lip sync

Generate a timeline once, persist it, replay with zero reprocessing.

Streaming & microphone

useLipsyncStream for mic, tapped MediaStream, and manual audio.

Natural lip sync

Smoother, less robotic mouth movement.

Realtime providers

OpenAI Realtime, Gemini Live, ElevenLabs.

Troubleshooting

Common integration issues and fixes.

WebGL2 rendering

The Rive avatar renders through @rive-app/*-webgl2: hardware-accelerated, smoother animation, advanced effects, efficient memory, and good scaling with multiple mascots. WebGL2 is required for the renderer (the audio pipeline does not need it).