@varunmhajan/hom-i-voice-ai/dist/README.md

Voice AI utilities for home loan assistance with India-specific formatting

# @varunmhajan/hom-i-voice-ai

🎙️ **Ultra-fast Voice AI SDK** with **ElevenLabs Monica voice** and minimal latency optimizations for real-time voice chat applications.

[![npm version](https://badge.fury.io/js/@varunmhajan/hom-i-voice-ai.svg)](https://badge.fury.io/js/@varunmhajan/hom-i-voice-ai)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## ✨ Features

- **🚀 Ultra-fast processing** - Optimized for <1500ms latency
- **🎙️ ElevenLabs Monica Voice** - Premium voice quality with multilingual support (Hindi/English)
- **✂️ Intelligent content shortening** - Automatically reduces lengthy responses to 2 sentences max for voice
- **🔢 Smart number formatting** - Project names as digits ("Godrej 101" → "Godrej one zero one") & prices naturally ("3.5 cr" → "three point five crores")
- **🗣️ Voice-optimized responses** - Removes verbose phrases and markdown formatting for natural speech
- **🎯 Voice Activity Detection** - Smart silence detection with auto-stop
- **💾 Intelligent caching** - Audio response caching for instant playback
- **🔧 Multiple build targets** - React components, vanilla JS, and UMD builds
- **📱 Cross-platform** - Works on web, mobile web, and Electron
- **🌍 Multi-language support** - 10+ languages with native voice IDs
- **⚡ Performance monitoring** - Real-time metrics and recommendations
- **🛡️ TypeScript support** - Full type safety and IntelliSense

## 🎤 Voice Quality

This SDK uses **ElevenLabs Monica voice** by default, providing:
- **Superior audio quality** with natural intonation
- **Multilingual support** for Hindi-English conversations
- **Code-switching capabilities** for natural language mixing
- **Optimized for real-time** conversation with <600ms response times

## 🔢 Smart Voice Formatting

**NEW in v1.3.0**: Advanced text formatting for optimal voice interactions:

### Content Shortening
- **Automatically reduces lengthy responses** to 2 sentences maximum
- **Removes verbose phrases** like "I can help you with", "Let me assist you"
- **Cleans up markdown** and formatting symbols for natural speech
- **Reduces average response length by 30-50%**

### Smart Number Formatting
- **Project names**: "Godrej 101" → "Godrej one zero one" (digits spoken individually)
- **Prices**: "3.5 cr" → "three point five crores" (natural pronunciation)
- **Context-aware**: Automatically detects project names vs prices
- **Multiple formats**: Handles cr, crores, lakhs, ₹ symbols

### Usage Examples
```javascript
import { formatTextForVoice, voiceFormatting } from '@varunmhajan/hom-i-voice-ai';

// Complete voice formatting
const longText = "I can help you with Godrej 101 which is priced at 3.5 cr. This property offers excellent amenities.";
const voiceText = formatTextForVoice(longText);
console.log(voiceText); // "Godrej one zero one which is priced at three point five crores."

// Individual utilities
const shortText = voiceFormatting.shortenForVoice(longText, 2);
const projectText = voiceFormatting.formatProjectNames("DLF Phase 5");
const priceText = voiceFormatting.formatPrice("Budget of 2.8 crores");
```

## 🚀 Quick Start

### Installation

```bash
npm install @varunmhajan/hom-i-voice-ai
# or
yarn add @varunmhajan/hom-i-voice-ai
```

### 🔐 API Key Authentication

**⚠️ Required**: This package requires a valid HOM-i Voice AI API key to function. Contact the HOM-i team to obtain your API key.

The package includes built-in API key validation and verification:
- ✅ Validates API key format during initialization
- ✅ Verifies API key with backend during setup
- ✅ Prevents usage with invalid or placeholder keys
- ✅ Provides clear error messages for authentication issues

### Basic Usage (Vanilla JavaScript)

```javascript
import { VoiceClient, utils } from '@varunmhajan/hom-i-voice-ai';

// Quick setup with optimal config and your actual API key
// Monica voice is used by default for superior quality
const client = utils.createQuickClient('your-homi-voice-ai-api-key', 'ultra-fast');

// For voice interactions, format responses to be ultra-short
const shortResponse = utils.formatForVoice('I can definitely help you with your home loan application today', 6);
console.log(shortResponse); // "Help with home loan!"

// Listen for API key verification
client.on('apiKeyVerified', ({ valid, error }) => {
  if (valid) {
    console.log('✅ API key verified successfully');
  } else {
    console.error('❌ API key verification failed:', error);
  }
});

// Wait for initialization to complete
client.on('ready', async () => {
  // Send a voice message
  const response = await client.sendTextMessage('Hello, how are you?');
  console.log('AI Response:', response.message);

  // Text to speech with Monica voice
  await client.textToSpeech('Hello there!', { autoPlay: true });

  // Performance metrics
  console.log('Performance:', client.getPerformanceMetrics());
});
```

### React Usage

```jsx
import { useVoiceClient } from '@varunmhajan/hom-i-voice-ai/react';

function VoiceChat() {
  const voice = useVoiceClient({
    apiKey: 'your-homi-voice-ai-api-key', // ⚠️ Replace with your actual API key
    ultraFastMode: true,
    enableCaching: true,
    voiceId: '2bNrEsM0omyhLiEyOwqY', // Monica voice (default)
    onMessageReceived: (response) => {
      console.log('Received:', response.message);
    },
    onApiKeyVerified: ({ valid, error }) => {
      if (!valid) {
        console.error('API Key Error:', error);
      }
    }
  });

  if (!voice.isReady) {
    return <div>Initializing voice AI...</div>;
  }

  return (
    <div>
      <button 
        onClick={() => voice.sendTextMessage('Hello!')}
        disabled={voice.isBusy}
      >
        {voice.isProcessing ? 'Processing...' : 'Say Hello'}
      </button>
      
      {voice.error && (
        <div className="error">
          Error: {voice.error}
          <button onClick={voice.clearError}>Clear</button>
        </div>
      )}
      
      <div>
        Latency: {voice.performanceMetrics.averageLatency}ms
        Cache Hit Rate: {(voice.performanceMetrics.cacheHitRate * 100).toFixed(1)}%
      </div>
    </div>
  );
}
```

### Voice Recording with React

```jsx
import { useVoiceRecorder } from '@hom-i/voice-ai/react';

function VoiceRecorder() {
  const recorder = useVoiceRecorder({
    enableVAD: true,
    silenceTimeout: 1500,
    onRecordingStop: (audioBlob) => {
      console.log('Recording completed:', audioBlob);
    }
  });

  return (
    <div>
      <button 
        onClick={recorder.toggleRecording}
        disabled={!recorder.isReady}
        className={recorder.isRecording ? 'recording' : ''}
      >
        {recorder.isRecording ? '🛑 Stop' : '🎙️ Record'}
      </button>
      
      <div>
        Duration: {recorder.formattedDuration}
        {recorder.voiceActivityDetected && <span> 🗣️ Voice detected</span>}
      </div>
      
      <div className="audio-level">
        Level: {'█'.repeat(Math.floor(recorder.audioLevel * 20))}
      </div>
    </div>
  );
}
```

## 📦 Build Targets

### React Components (`@hom-i/voice-ai/react`)
```javascript
import { useVoiceClient, useVoiceRecorder } from '@hom-i/voice-ai/react';
```

### Vanilla JavaScript (`@hom-i/voice-ai/vanilla`)
```javascript
import { VoiceClient, VoiceRecorder, VanillaVoiceAI } from '@hom-i/voice-ai/vanilla';

// Or use the global object (UMD build)
const { HomiVoiceAI } = window;
```

### Core Library (`@hom-i/voice-ai`)
```javascript
import { VoiceClient, VoiceRecorder, utils } from '@hom-i/voice-ai';
```

## 🗣️ Voice Response Optimization

### Automatic Response Shortening

For voice interactions, responses are automatically shortened to 3-6 words maximum for natural conversation flow:

```javascript
import { utils } from '@varunmhajan/hom-i-voice-ai';

// Format any text for voice interactions
const longText = "I can definitely help you with your home loan application today";
const shortText = utils.formatForVoice(longText, 6);
console.log(shortText); // "Help with home loan!"

// Other examples:
utils.formatForVoice("Yes, I can assist you with that") // "Sure!"
utils.formatForVoice("What is your budget range?") // "Your budget?"
utils.formatForVoice("That's an excellent credit score") // "Great score!"
```

### Voice-Optimized Configuration

```javascript
import { utils } from '@varunmhajan/hom-i-voice-ai';

// Get pre-configured settings optimized for voice
const voiceConfig = utils.getVoiceOptimizedConfig('your-api-key');
const client = new VoiceClient(voiceConfig);

// Backend automatically applies voice-assistant context for ultra-short responses
```

## ⚡ Performance Optimizations

### Ultra-Fast Mode
```javascript
const client = new VoiceClient({
  apiKey: 'your-homi-voice-ai-api-key', // Your actual API key
  ultraFastMode: true,        // Enable all optimizations
  enableCaching: true,        // Cache audio responses
  enableCompression: true,    // Compress requests
  priority: 'speed',          // Prioritize speed over quality
  timeout: 5000,             // Fast timeout
  preloadVoices: true,       // Pre-warm voice models
});
```

### Caching Strategy
```javascript
const client = new VoiceClient({
  apiKey: 'your-homi-voice-ai-api-key', // Your actual API key
  enableCaching: true,
  maxCacheSize: 100,         // Cache up to 100 responses
});

// Clear cache when needed
client.clearCache();
```

### Performance Monitoring
```javascript
const metrics = client.getPerformanceMetrics();
console.log(`
  Average Latency: ${metrics.averageLatency}ms
  Cache Hit Rate: ${(metrics.cacheHitRate * 100).toFixed(1)}%
  Error Rate: ${(metrics.errorRate * 100).toFixed(1)}%
  Request Count: ${metrics.requestCount}
`);

// Get recommendations
const recommendations = utils.getPerformanceRecommendations(metrics);
recommendations.forEach(rec => console.log('💡', rec));
```

## 🎙️ Voice Activity Detection

```javascript
const recorder = new VoiceRecorder({
  enableVAD: true,           // Enable voice activity detection
  vadThreshold: 0.01,        // Sensitivity threshold
  silenceTimeout: 1500,      // Auto-stop after 1.5s of silence
  minRecordingTime: 500,     // Minimum recording duration
  maxRecordingTime: 30000,   // Maximum recording duration
});

recorder.on('voiceStart', () => console.log('Voice detected'));
recorder.on('voiceEnd', () => console.log('Voice ended'));
recorder.on('silenceDetected', ({ autoStopping }) => {
  console.log('Silence detected, auto-stopping:', autoStopping);
});
```

## 🌍 Multi-Language Support

```javascript
const client = new VoiceClient({
  apiKey: 'your-homi-voice-ai-api-key', // Your actual API key
  language: 'hi',           // Hindi
  voiceId: 'hindi-voice-id', // Specific voice for Hindi
});

// Supported languages: en, hi, ta, te, bn, mr, gu, kn, ml, pa
```

## 🔧 Configuration Options

### VoiceClient Config
```typescript
interface VoiceConfig {
  apiKey: string;
  baseUrl?: string;
  language?: string;
  voiceId?: string;
  audioFormat?: 'mp3' | 'wav' | 'ogg';
  priority?: 'speed' | 'quality' | 'balanced';
  mode?: 'full-voice' | 'stt-only' | 'tts-only' | 'auto';
  
  // Performance optimizations
  ultraFastMode?: boolean;
  enableCaching?: boolean;
  enableCompression?: boolean;
  maxCacheSize?: number;
  timeout?: number;
  retryAttempts?: number;
  
  // Audio settings
  enableSTT?: boolean;
  enableTTS?: boolean;
  autoPlay?: boolean;
}
```

### VoiceRecorder Config
```typescript
interface RecorderConfig {
  // Audio settings
  sampleRate?: number;
  channels?: number;
  audioBitsPerSecond?: number;
  mimeType?: string;
  
  // Voice Activity Detection
  enableVAD?: boolean;
  vadThreshold?: number;
  silenceTimeout?: number;
  minRecordingTime?: number;
  maxRecordingTime?: number;
  
  // Performance optimizations
  ultraFastMode?: boolean;
  enableNoiseSuppression?: boolean;
  enableEchoCancellation?: boolean;
  enableAutoGainControl?: boolean;
}
```

## 🛠️ Advanced Usage

### Custom Audio Processing
```javascript
const recorder = new VoiceRecorder({
  enableRealTimeProcessing: true,
});

recorder.on('audioChunk', (chunk) => {
  // Process audio chunk in real-time
  console.log('Audio chunk:', chunk.duration + 'ms');
});

recorder.on('audioBuffer', ({ buffer, peak, energy }) => {
  // Access raw audio buffer for custom processing
  console.log('Audio buffer - Peak:', peak, 'Energy:', energy);
});
```

### Request Queue Management
```javascript
const client = new VoiceClient({
  apiKey: 'your-api-key',
  ultraFastMode: true, // Cancels previous request when new one starts
});

// Multiple rapid requests - only the latest will complete
client.sendTextMessage('First message');
client.sendTextMessage('Second message');
client.sendTextMessage('Final message'); // Only this will complete
```

### Error Handling
```javascript
const client = new VoiceClient({
  apiKey: 'your-api-key',
  retryAttempts: 3,
});

client.on('error', (error) => {
  console.error('Voice AI Error:', error);
});

try {
  const response = await client.sendTextMessage('Hello');
} catch (error) {
  if (error.message.includes('timeout')) {
    // Handle timeout
  } else if (error.message.includes('API key')) {
    // Handle authentication error
  }
}
```

## 📊 Performance Benchmarks

| Metric | Target | Typical |
|--------|--------|---------|
| **Initial Latency** | <1500ms | ~800ms |
| **Cached Response** | <100ms | ~50ms |
| **Voice Processing** | <2000ms | ~1200ms |
| **Memory Usage** | <50MB | ~30MB |
| **Cache Hit Rate** | >70% | ~85% |

## 🔍 Browser Support

- ✅ Chrome 60+
- ✅ Firefox 55+
- ✅ Safari 11+
- ✅ Edge 79+
- ✅ iOS Safari 11+
- ✅ Chrome Android 60+

**Requirements:**
- HTTPS connection (or localhost for development)
- Modern browser with MediaRecorder API support
- Microphone permissions for recording

## 📚 API Reference

### VoiceClient Methods

#### `sendVoiceMessage(input, options?)`
Send voice or text message and get AI response.
- **input**: `string | Blob | File | AudioInput`
- **options**: `Partial<VoiceConfig>`
- **Returns**: `Promise<VoiceResponse>`

#### `sendTextMessage(text, options?)`
Send text message optimized for speed.
- **text**: `string`
- **options**: `Partial<VoiceConfig>`
- **Returns**: `Promise<VoiceResponse>`

#### `textToSpeech(text, options?)`
Convert text to speech with caching.
- **text**: `string`
- **options**: `Partial<VoiceConfig>`
- **Returns**: `Promise<VoiceResponse>`

#### `transcribeAudio(audioInput, options?)`
Transcribe audio to text only.
- **audioInput**: `Blob | File | AudioInput`
- **options**: `Partial<VoiceConfig>`
- **Returns**: `Promise<VoiceResponse>`

### VoiceRecorder Methods

#### `startRecording()`
Start audio recording with optimized settings.
- **Returns**: `Promise<void>`

#### `stopRecording()`
Stop recording and return audio data.
- **Returns**: `Promise<Blob>`

#### `toggleRecording()`
Toggle recording state.
- **Returns**: `Promise<Blob | void>`

### Utility Functions

#### `utils.isVoiceSupported()`
Check if voice features are supported.
- **Returns**: `boolean`

#### `utils.getOptimalConfig(scenario)`
Get optimal configuration for different scenarios.
- **scenario**: `'ultra-fast' | 'balanced' | 'high-quality'`
- **Returns**: `Partial<VoiceConfig>`

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- 📧 Email: support@hom-i.com
- 📚 Documentation: [https://docs.hom-i.com/voice-ai](https://docs.hom-i.com/voice-ai)
- 🐛 Issues: [GitHub Issues](https://github.com/hom-i/voice-ai/issues)

---

Made with ❤️ by the HOM-i team