ai-voix

v1.0.1

Published

2 months ago

**Voix AI** is a futuristic, real-time voice assistant React library. It is modular, themeable, and uniquely **Provider-Agnostic**, allowing you to integrate top-tier AI voice capabilities into any React application with zero configuration.

Downloads

0High
0Medium
0Low

shivangi-dixit

🎙️ Voix AI

Voix AI is a futuristic, real-time voice assistant React library. It is modular, themeable, and uniquely Provider-Agnostic, allowing you to integrate top-tier AI voice capabilities into any React application with zero configuration.

✨ Features

🚀 Plug-and-Play: A single component gives you a complete, high-end voice interface.
🌐 Universal Provider Support: Native, full-featured support for Gemini Multimodal Live. Support for OpenAI Realtime, Azure, and LiveKit is currently experimental.
🎨 Futuristic UI: Includes a reactive "Orb" visualizer, sliding chat history, and premium built-in themes.
🌈 Themeable: Choose from cyber, glass, midnight, or solar themes on the fly.
🎙️ High Performance: Low-latency, client-side audio processing using the Web Audio API.
🛡️ Secure & Private: BYOK (Bring Your Own Key) architecture with pure client-side streaming.

📦 Installation

Install the core package and its required peer dependencies:

npm install ai-voix @google/genai motion lucide-react

Note: @google/genai, motion, and lucide-react are required peer dependencies to ensure optimized bundling in your host application.

🚀 Quick Start

Drop the VoixProvider and VoixAppShell into your React application to get started immediately.

import { VoixProvider, VoixAppShell } from 'ai-voix';

function App() {
  return (
    <VoixProvider 
      provider="gemini" 
      apiKey="YOUR_API_KEY"
      agentName="Voix Assistant"
      initialTheme="cyber"
    >
      <VoixAppShell />
    </VoixProvider>
  );
}

🎭 Customizing Your Agent

You can easily customize the behavior and appearance via props on the VoixProvider.

<VoixProvider 
  provider="gemini"
  initialTheme="cyber" 
  agentName="Aura"
  greetingText="Aura online. How can I assist you today?"
  systemInstruction="You are Aura, a calm and highly intelligent AI assistant."
>
  <VoixAppShell />
</VoixProvider>

Supported Themes

cyber: Neon accents and dark backgrounds.
glass: Modern frosted glass effect.
midnight: Deep navy and subtle shadows.
solar: Bright, high-contrast professional look.

📖 API Reference

`VoixProvider` Props

The VoixProvider is the main configuration hub for the library.

🎙️ Voice Commands & System Control

Voix AI supports natural voice commands to control the session. You can ask the assistant to stop or shut down at any time.

Automatic Shutdown

When the assistant detects a shutdown command, it will politely acknowledge (e.g., "Goodbye! Shutting down now.") and automatically disconnect the microphone and AI stream.

Supported Shutdown Phrases:

"Stop listening"
"Go to sleep"
"Deactivate"
"Shut down"
"Goodbye"
"Turn off"

🛠️ Advanced Usage (Hooks)

Build your own custom UI using our built-in hooks:

`useVoice()`

The primary hook for controlling the session.

const { status, toggle, transcript, history, error } = useVoice();

`useAudioPlayer()`

Manage audio output and volume.

const { volume, isMuted, mute, unmute } = useAudioPlayer();

📜 Managing Chat History

Voix AI provides two primary ways to capture and manage your conversation history.

1. Using the `onHistoryUpdate` Prop

Pass a callback to the VoixProvider to receive the full history array (VoixMessage[]) every time it updates. This is ideal for logging or saving conversations to a database.

<VoixProvider 
  onHistoryUpdate={(history) => {
    console.log("Updated History:", history);
    // history is an array of objects: { role: 'user' | 'model', text: string, timestamp: Date }
  }}
>
  <VoixAppShell />
</VoixProvider>

2. Using the `useVoice()` Hook

Inside any component nested under VoixProvider, you can access the reactive history array directly.

import { useVoice } from 'ai-voix';

function MyCustomHistory() {
  const { history } = useVoice();
  
  return (
    <ul>
      {history.map((msg, index) => (
        <li key={index}>
          <strong>{msg.role}</strong>: {msg.text}
        </li>
      ))}
    </ul>
  );
}

🚀 Future Scope

Voix AI is constantly evolving. Here are some of the features currently on our roadmap:

🔗 Full Model Parity: Deepening integration protocols to ensure 100% feature parity between Gemini, OpenAI Realtime, and future models (like Claude Voice).
📜 Enhanced Chat Persistence: Built-in adapters for automated local/cloud storage of conversation history.
🎨 Custom Theme Injection: An API to allow developers to pass their own VoixThemeConfig objects for infinite branding possibilities.
🛠️ Function Calling Framework: A native hook-based system allowing the AI to trigger specific functions within your host application (e.g., toggle_lights, search_database).
📸 Multi-Modal Vision: Support for real-time video/screen capture streams during voice conversations.
🎙️ Local LLM Support: Experimental support for browser-local models (via Web-LLM) for ultra-private, offline-capable voice assistance.
📊 Developer Analytics: Insight dashboards for monitoring token usage, response latency, and conversation sentiment.

🛡️ Security & Privacy

Voix AI is built for production security:

Zero Middlemen: All audio and data streams travel directly from the browser to the AI provider.
Client-Side Processing: No servers are used to store or intercept your voice data.
Encapsulated Styles: CSS is hardened to prevent conflicts with your existing application styles.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme