> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mascot.bot/llms.txt
> Use this file to discover all available pages before exploring further.

# Mascotbot React SDK Documentation

> Learn how to install and use the Mascotbot SDK with React.

## 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:

<CodeGroup>
  ```bash npm theme={null}
  npm install ./mascotbot-sdk-react-0.1.5.tgz
  ```

  ```bash yarn theme={null}
  yarn add ./mascotbot-sdk-react-0.1.5.tgz
  ```

  ```bash pnpm theme={null}
  pnpm add ./mascotbot-sdk-react-0.1.5.tgz
  ```
</CodeGroup>

<Note>You'll get the latest version of our SDK with integration examples once you subscribe to one of our plans</Note>

Ensure that you have the required peer dependencies installed:

<CodeGroup>
  ```bash npm theme={null}
  npm install react react-dom
  npm install @rive-app/react-webgl2
  ```

  ```bash yarn theme={null}
  yarn add react react-dom
  yarn add @rive-app/react-webgl2
  ```

  ```bash pnpm theme={null}
  pnpm add react react-dom
  pnpm add @rive-app/react-webgl2
  ```
</CodeGroup>

## Setup

### 1. Import and Wrap with `MascotProvider`

To use the SDK, wrap your application with the `MascotProvider` component.

```jsx theme={null}
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.

```jsx theme={null}
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.

```jsx theme={null}
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.

```jsx theme={null}
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.

```jsx theme={null}
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:

```jsx theme={null}
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.

```jsx theme={null}
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.

```jsx theme={null}
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.

```jsx theme={null}
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.