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
@mascotbot:registry=https://npm.mascot.bot/
//npm.mascot.bot/:_authToken=mascot_xxx

pnpm add @mascotbot/react
pnpm add @rive-app/react-webgl2 @rive-app/webgl2
@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

ImportProvides
@mascotbot/reactMascotProvider, useMascot, useProcessAudio — the audio pipeline + the top-level provider.
@mascotbot/react/riveMascot, MascotRive, useMascotRive, useMascotInputs, useMascotPlayback, useLipsyncStream — the Rive layer.

​
Composition

One provider, one component. <MascotProvider> owns the licensed inference engine; <Mascot> mounts the Rive avatar inside it. 
"use client";
import { MascotProvider } from "@mascotbot/react";
import { Mascot, Fit, Alignment } from "@mascotbot/react/rive";

export default function App() {
  return (
    <MascotProvider apiKey="mascot_pub_…">
      <Mascot
        src="/mascot-fox.riv"
        layout={{ fit: Fit.Contain, alignment: Alignment.Center }}
      />
    </MascotProvider>
  );
}
ComponentPurpose
<MascotProvider apiKey="…">Initializes one LipsyncClient and exposes it to descendants. Props extend the client config.
<Mascot src=… | rive=…>Loads Rive and exposes its inputs via context. Pass a .riv URL or a pre-loaded Rive instance. Renders the canvas by default; children opt out and take control (you can still use <MascotRive /> inside).
<MascotRive>The canvas component. Use it inside <Mascot> children when you need a custom loading slot or layout wrapper; otherwise <Mascot> mounts it for you.
<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).