# Mascotbot Documentation ## Docs - [Introduction](https://docs.mascot.bot/index.md): Create engaging AI mascots with advanced lip-sync technology. Build interactive experiences for your applications. - [Mascotbot Avatar SDK Overview - Build Interactive AI Avatars](https://docs.mascot.bot/overview.md): What the Mascotbot avatar SDK is: real-time interactive AI avatars for React and JavaScript — offline, microphone, and realtime voice-agent paths. - [Install the Mascotbot Lipsync SDK - Private Registry & API Keys](https://docs.mascot.bot/installation.md): Install @mascotbot/react and lipsync-core from the private npm registry, configure your .npmrc auth token, and pick the right development or production API key. - [Mascotbot Lipsync SDK Quickstart - Animate a Rive Avatar in Minutes](https://docs.mascot.bot/quickstart.md): Wire the Mascotbot lipsync SDK into a React app: provider setup, drive a Rive avatar from an audio file, add live microphone input, or use the vanilla core without React. - [Visemes & the Viseme Timeline - Mascotbot Lip Sync Data Model](https://docs.mascot.bot/concepts/visemes-and-timeline.md): How the Mascotbot SDK represents lip sync: viseme ids, the serializable run-length VisemeTimeline, and the framesToTimeline / timelineToCues / parseTimeline helpers. - [Rive Co-existence - The SDK Does Not Own Your Rive Instance](https://docs.mascot.bot/concepts/rive-coexistence.md): The Mascotbot SDK writes only mouth visemes, is_speaking, and stress. Every other Rive input, ViewModel, event, and listener stays yours on the raw rive instance. - [Licensing & API Keys - Mascotbot Lipsync SDK Session Model](https://docs.mascot.bot/concepts/licensing-and-keys.md): How Mascotbot lipsync SDK licensing works: development vs production keys, origin enforcement, the init / background-refresh session lifecycle, usage metering, and the key security model. - [Mascotbot React SDK Documentation](https://docs.mascot.bot/libraries/react-sdk.md): Learn how to install and use the Mascotbot SDK with React. - [Mascotbot React Hooks Reference - useMascot, useMascotPlayback & More](https://docs.mascot.bot/libraries/react-hooks.md): Complete reference for the Mascotbot lipsync React hooks: useMascot, useProcessAudio, useMascotRive, useMascotInputs, useMascotPlayback, useLipsyncStream, useLoadRive, and useRiveAsset. - [Streaming & Microphone Lip Sync - useLipsyncStream Guide](https://docs.mascot.bot/libraries/streaming-and-mic.md): Drive a Mascotbot avatar from live audio with useLipsyncStream: microphone input, tapping a played MediaStream, or pushing audio manually. One hook, three sources. - [Offline Lip Sync - Generate, Persist & Replay Viseme Timelines](https://docs.mascot.bot/libraries/offline-lipsync.md): Run Mascotbot inference once, persist the VisemeTimeline as JSON, and replay it forever with zero reprocessing — ideal for prefetching, queues, and video export. - [Natural Lip Sync](https://docs.mascot.bot/libraries/natural-lip-sync.md): Create more realistic mouth movements with intelligent viseme processing - [Mascotbot Session Lifecycle - Refresh, Refused & Recovery](https://docs.mascot.bot/libraries/session-lifecycle.md): How a Mascotbot lipsync session moves through idle → initializing → ready → refused, what triggers the refusal, and the canonical recovery pattern using reload() — pre-check at the top of every action plus a RefusedError catch mid-flight. - [LipsyncClient - Vanilla JavaScript Lip Sync Core API](https://docs.mascot.bot/core/client.md): Use @mascotbot/core without React: LipsyncClient.init, processAudio, createStreamingSession, resample, diagnostics, events, and the vanilla Rive engine. - [Streaming Lip Sync Sessions - createStreamingSession & pushWindow](https://docs.mascot.bot/core/streaming.md): Drive lip sync from live audio with the vanilla createStreamingSession API: push 25 ms windows, read per-frame results, handle silence, and barge-in. - [createPCMStreamPlayer - Play & Tap Raw PCM for Realtime Lip Sync](https://docs.mascot.bot/core/pcm-stream-player.md): createPCMStreamPlayer plays streamed PCM16 gap-tolerantly and exposes a parallel MediaStream tap — the bridge for realtime AI providers that hand you raw audio. - [Realtime AI Voice Avatars - Lip Sync for OpenAI, Gemini & ElevenLabs](https://docs.mascot.bot/realtime/overview.md): Add a real-time avatar to any voice AI: tap the assistant's audio into useLipsyncStream. OpenAI Realtime, Gemini Live, ElevenLabs. - [ElevenLabs Avatar Integration - Add Real-time Visual Avatars to Your Voice AI](https://docs.mascot.bot/libraries/elevenlabs-avatar.md): Complete guide to integrating animated avatars with ElevenLabs conversational AI. Real-time lip sync, WebSocket support, and production-ready React components. Start in 5 minutes → - [Gemini Live API Avatar Integration - Build Interactive AI Avatars with Lip Sync](https://docs.mascot.bot/libraries/gemini-live-api-avatar.md): Complete guide to building interactive AI avatars with Gemini Live API and Mascot Bot SDK. Real-time lip sync, ephemeral tokens, WebSocket streaming, and production-ready React components. TypeScript/JavaScript tutorial → - [OpenAI Realtime API Avatar — Build an Interactive Lip-Synced ChatGPT Avatar](https://docs.mascot.bot/libraries/openai-realtime-api-avatar.md): Build an interactive lip-synced avatar powered by OpenAI Realtime API. Real-time lip sync, ephemeral token security, WebSocket streaming, natural viseme processing, and production-ready React components. Open-source alternative to HeyGen, D-ID, Synthesia. TypeScript/React tutorial → - [Mascotbot SDK Error Codes - License, Network & Timeline Failures](https://docs.mascot.bot/reference/error-codes.md): Every Mascotbot lipsync SDK error code, the HTTP status it maps from, the customer-readable message, and the recommended UI. Branch on error.code, not the subclass. - [Mascotbot SDK API Conventions - Predictable, Hard-to-Misuse Design](https://docs.mascot.bot/reference/api-conventions.md): The rules the Mascotbot lipsync SDK follows so it stays predictable: events vs callbacks, options objects, honest async, the error taxonomy, format versioning, and module boundaries. - [Migrating the Mascotbot Lipsync SDK](https://docs.mascot.bot/reference/migration.md): How to move existing integrations onto the current Mascotbot lipsync SDK — the 0.2.x → 0.3.0 unified-naming cutover, plus the legacy → 0.2.x architectural migration for older integrations. - [Mascotbot React SDK Troubleshooting](https://docs.mascot.bot/libraries/react-troubleshooting.md) - [Meet Our Ready-to-Use Mascots: A Quick Start Guide](https://docs.mascot.bot/mascots/ready-to-use-mascots.md): Below is a selection of pre-made mascots available to all subscribers. Feel free to use them for testing, early integration, or commercial projects while we craft your custom mascot. Each one offers unique personality traits, different visual styles, and multiple potential use cases. - [Mascotbot Avatars API - Ready-Made Mascot .riv Distribution](https://docs.mascot.bot/libraries/avatars.md): A small public HTTP API that serves ready-made Mascotbot avatars as Rive .riv files plus per-version metadata. Fetch once, self-host, drive Rive from the metadata. - [Changelog](https://docs.mascot.bot/changelog.md): Product updates, new features, and improvements - [CLAUDE](https://docs.mascot.bot/CLAUDE.md) ## AsyncAPI Specs - [asyncapi](https://docs.mascot.bot/api-reference/asyncapi.yaml) ## Optional - [Follow us on X](https://x.com/mascot_bots) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.