# Mascotbot Documentation ## Docs - [CLAUDE](https://docs.mascot.bot/CLAUDE.md) - [Changelog](https://docs.mascot.bot/changelog.md): Product updates, new features, and improvements - [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. - [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. - [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. - [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. - [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. - [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. - [Introduction](https://docs.mascot.bot/index.md): Create engaging AI mascots with advanced lip-sync technology. Build interactive experiences for your applications. - [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 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. - [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 → - [Natural Lip Sync](https://docs.mascot.bot/libraries/natural-lip-sync.md): Create more realistic mouth movements with intelligent viseme processing - [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. - [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 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. - [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 SDK Troubleshooting](https://docs.mascot.bot/libraries/react-troubleshooting.md) - [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. - [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. - [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 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. - [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. - [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. - [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. - [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. - [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. ## AsyncAPI Specs - [asyncapi](https://docs.mascot.bot/api-reference/asyncapi.yaml) ## Optional - [Follow us on X](https://x.com/mascot_bots)