Skip to main content

​
Introduction

The MascotBOT SDK provides a set of tools and components to integrate interactive mascots into your React applications. This documentation will guide you through the installation process and explain the main mechanisms and hooks available in the SDK.

​
Installation

To install the MascotBOT SDK, you need to add the package to your project. You can do this using the following command: 
npm install ./mascotbot-sdk-react-0.1.5.tgz
You’ll get the latest version of our SDK with integration examples once you subscribe to one of our plans
Ensure that you have the required peer dependencies installed: 
npm install react react-dom
npm install @rive-app/react-webgl2

​
Setup

​
1. Import and Wrap with MascotProvider

To use the SDK, wrap your application with the MascotProvider component. 
import { MascotProvider } from "@mascotbot-sdk/react";

function App() {
  return (
    <MascotProvider>
      {/* Your application components */}
    </MascotProvider>
  );
}

​
2. Create a Rive Instance

Use the useRive hook to create a Rive instance. This instance will manage the animations and state machines for your mascot. 
import { useRive } from "@rive-app/react-webgl2";

const rive = useRive({
  src: "your_rive_file_url",
  artboard: "YourArtboard",
  animations: "YourAnimation",
  stateMachines: "YourStateMachine",
  autoplay: true,
});

​
3. Use MascotClient

The MascotClient component connects your Rive instance with the MascotBOT SDK. 
import { MascotClient } from "@mascotbot-sdk/react";

<MascotClient rive={rive}>
  <YourMascotComponent />
</MascotClient>

​
Hooks

​
useMascot

The useMascot hook provides access to the Rive instance and Rive component. 
import { useMascot } from "@mascotbot-sdk/react";

const { rive, RiveComponent } = useMascot();

​
useMascotPlayback

The useMascotPlayback hook allows you to control the playback of animations and manage visemes. 
import { useMascotPlayback } from "@mascotbot-sdk/react";

const playback = useMascotPlayback();
playback.play();
playback.pause();

​
Controlling Speaking State

By default, the mascot’s is_speaking state is automatically set to true while it’s speaking and set to false when it stops. You can control this behavior by passing options to the useMascotPlayback hook: 
import { useMascotPlayback } from "@mascotbot-sdk/react";

// Default behavior - automatically set is_speaking state to true when speaking
const playback = useMascotPlayback();

// Disable automatic is_speaking state changes
const playback = useMascotPlayback({ setSpeakingState: false });
The setSpeakingState option allows you to disable the automatic management of the is_speaking state, giving you manual control over when and how the speaking state is set.

​
useMascotSpeech

The useMascotSpeech hook provides advanced text-to-speech functionality with support for multiple TTS engines, queueing, and real-time audio streaming. 
import { useMascotSpeech } from "@mascotbot-sdk/react";

const speech = useMascotSpeech({
  apiEndpoint: "/api/visemes-audio", // Required - your API route that handles MascotBot requests
  apiKey: "your-api-key", // Optional - adds auth headers when provided
  defaultVoice: "am_fenrir",
  bufferSize: 1,
});

// Basic usage
await speech.speak("Hello world", { voice: "am_fenrir" });

// Add to queue for sequential playback
speech.addToQueue("First message", { voice: "am_fenrir" });
speech.addToQueue("Second message", { voice: "af_nova" });

// Using custom TTS engines
await speech.speak("Hello from ElevenLabs", {
  ttsParams: {
    tts_engine: "elevenlabs",
    tts_api_key: "your-elevenlabs-key",
    voice: "voice-id",
    speed: 1.2
  }
});

// Control queue and playback
speech.stopAndClear(); // Stop and clear queue
speech.clearQueue(); // Clear queue only
speech.setBufferSize(3); // Adjust buffering

​
Handling Visemes and Audio Playback

To create a synchronized animation and audio experience, you can use the playback.add method to add visemes. This can be done in various ways, such as fetching from a server, generating in real-time, or any other method suitable for your application.

​
Adding Visemes

Visemes are visual representations of phonemes. You can add them to the playback to synchronize with the audio. 
const visemes = /* Obtain visemes from your source */;
playback.add(visemes);

​
Adding Audio

For speech playback, you need to provide an audio source. This can be done by setting the audio source dynamically. 
const audioElement = /* Reference to your audio element */;
audioElement.src = "your_audio_source";
audioElement.play();

​
WebGL2 Performance Benefits

The SDK now uses WebGL2 for better performance and rendering capabilities:
  • Better Performance: Hardware-accelerated rendering for smoother animations
  • Enhanced Effects: Support for advanced visual effects and shaders
  • Improved Memory Usage: More efficient handling of graphics resources
  • Better Scaling: Better performance with complex animations and multiple mascots

​
Conclusion

The MascotBOT SDK offers a flexible and powerful way to integrate mascots into your React applications. By following the setup instructions and utilizing the provided hooks, you can create engaging and interactive experiences for your users. The enhanced useMascotSpeech hook provides production-ready speech capabilities with support for multiple TTS providers, intelligent queueing, and real-time streaming. For more detailed examples and integration guides, please refer to the separate article on production and integration examples.