voice-to-text-converter/README.md

A modern, lightweight Node.js package for speech-to-text conversion with support for multiple engines

# Voice-to-Text Converter

A modern, lightweight Node.js package for speech-to-text conversion with support for multiple engines and both Node.js and browser environments.

## Features

- 🎤 **Multiple Input Sources**: Microphone, audio files, and streams
- 🔧 **Multiple Engines**: Web Speech API, Vosk (offline), Google Cloud Speech-to-Text
- 🌐 **Cross-Platform**: Works in Node.js and browsers
- 📝 **TypeScript Support**: Full type definitions included
- 🔄 **Real-time Processing**: Streaming and continuous recognition
- 🛡️ **Error Handling**: Comprehensive error handling and fallback mechanisms
- 🎯 **Simple API**: Clean, intuitive interface for developers

## Installation

```bash
npm install voice-to-text-converter
```

### Optional Dependencies

For offline processing with Vosk:
```bash
npm install vosk
```

For Google Cloud Speech-to-Text:
```bash
npm install @google-cloud/speech
```

For microphone recording in Node.js:
```bash
npm install node-record-lpcm16
```

## Quick Start

### Node.js

```javascript
import { VoiceToText, transcribeFromFile, transcribeFromMicrophone } from 'voice-to-text-converter';

// Quick transcription from file
const results = await transcribeFromFile('audio.wav', {
  language: 'en-US'
});
console.log(results[0].transcript);

// Quick transcription from microphone
const micResults = await transcribeFromMicrophone({
  duration: 5000, // 5 seconds
  language: 'en-US'
});
console.log(micResults[0].transcript);
```

### Browser

```html
<script src="https://unpkg.com/voice-to-text-converter/lib/browser.js"></script>
<script>
  // Quick transcription from microphone
  voiceToText.transcribeFromMicrophone({
    duration: 5000,
    language: 'en-US'
  }).then(results => {
    console.log(results[0].transcript);
  });
</script>
```

## Usage Examples



### Basic Usage

```javascript
import { VoiceToText } from 'voice-to-text-converter';

const voiceToText = new VoiceToText({
  defaultEngine: { engine: 'vosk', modelPath: './models/vosk-model-en-us' },
  defaultRecognitionConfig: {
    language: 'en-US',
    continuous: true,
    interimResults: true
  }
});

// Initialize the converter
await voiceToText.initialize();

// Set up event listeners
voiceToText.on('result', (result) => {
  console.log(`Transcript: ${result.transcript}`);
  console.log(`Confidence: ${result.confidence}`);
  console.log(`Is Final: ${result.isFinal}`);
});

voiceToText.on('error', (error) => {
  console.error('Recognition error:', error.message);
});

// Start listening from microphone
await voiceToText.fromMicrophone({
  duration: 10000 // Record for 10 seconds
});

// Clean up
await voiceToText.cleanup();
```

### File Processing

```javascript
import { VoiceToText } from 'voice-to-text-converter';

const voiceToText = new VoiceToText();
await voiceToText.initialize();

// Process single file
const results = await voiceToText.fromFile('speech.wav', {
  language: 'en-US',
  maxAlternatives: 3
});

results.forEach((result, index) => {
  console.log(`Result ${index + 1}: ${result.transcript}`);
  console.log(`Confidence: ${result.confidence}`);
});
```

### Stream Processing

```javascript
import { VoiceToText } from 'voice-to-text-converter';
import fs from 'fs';

const voiceToText = new VoiceToText();
await voiceToText.initialize();

const audioStream = fs.createReadStream('audio.wav');
const results = await voiceToText.fromStream(audioStream, {
  language: 'es-ES'
});

console.log('Transcription:', results.map(r => r.transcript).join(' '));
```

### Real-time Recognition

```javascript
import { VoiceToText } from 'voice-to-text-converter';

const voiceToText = new VoiceToText({
  defaultRecognitionConfig: {
    continuous: true,
    interimResults: true
  }
});

await voiceToText.initialize();

// Handle real-time results
voiceToText.on('result', (result) => {
  if (result.isFinal) {
    console.log('Final:', result.transcript);
  } else {
    console.log('Interim:', result.transcript);
  }
});

// Start continuous listening
await voiceToText.startListening({
  source: 'microphone'
});

// Stop after 30 seconds
setTimeout(async () => {
  await voiceToText.stopListening();
}, 30000);
```

### Engine-Specific Usage

#### Vosk (Offline)

```javascript
import { VoiceToText, VoskEngine } from 'voice-to-text-converter';

// Download and setup Vosk model first
const modelPath = await VoskEngine.downloadModel('en-US', 'small');

const voiceToText = new VoiceToText({
  defaultEngine: {
    engine: 'vosk',
    modelPath: modelPath
  }
});

await voiceToText.initialize();
const results = await voiceToText.fromFile('audio.wav');
```

#### Google Cloud Speech-to-Text

```javascript
import { VoiceToText } from 'voice-to-text-converter';

const voiceToText = new VoiceToText({
  defaultEngine: {
    engine: 'google-cloud',
    apiKey: 'your-api-key',
    projectId: 'your-project-id'
  }
});

await voiceToText.initialize();
const results = await voiceToText.fromFile('audio.wav', {
  language: 'en-US',
  encoding: 'FLAC'
});
```

#### Web Speech API (Browser)

```javascript
import { VoiceToText } from 'voice-to-text-converter';

const voiceToText = new VoiceToText({
  defaultEngine: { engine: 'web-speech' }
});

await voiceToText.initialize();

// Only works in browsers with microphone access
await voiceToText.fromMicrophone({
  duration: 5000,
  language: 'en-US'
});
```


## API Reference

### VoiceToText Class

#### Constructor

```typescript
new VoiceToText(options?: VoiceToTextOptions)
```

**Options:**
- `defaultEngine?: EngineConfig` - Default engine configuration
- `defaultRecognitionConfig?: SpeechRecognitionConfig` - Default recognition settings
- `enableFallback?: boolean` - Enable automatic engine fallback (default: true)
- `enginePriority?: Array<'web-speech' | 'vosk' | 'google-cloud'>` - Engine priority order
- `debug?: boolean` - Enable debug logging (default: false)

#### Methods

##### `initialize(): Promise<void>`
Initialize the voice-to-text converter and select the best available engine.

##### `fromMicrophone(options?: MicrophoneOptions): Promise<void>`
Start speech recognition from microphone input.

**Options:**
- `duration?: number` - Recording duration in milliseconds
- `deviceId?: string` - Specific microphone device ID
- `sampleRate?: number` - Audio sample rate (default: 16000)

##### `fromFile(filePath: string, config?: SpeechRecognitionConfig): Promise<SpeechRecognitionResult[]>`
Process an audio file and return transcription results.

##### `fromStream(stream: NodeJS.ReadableStream, config?: SpeechRecognitionConfig): Promise<SpeechRecognitionResult[]>`
Process an audio stream and return transcription results.

##### `startListening(audioConfig: AudioInputConfig, config?: SpeechRecognitionConfig): Promise<void>`
Start continuous speech recognition.

##### `stopListening(): Promise<void>`
Stop ongoing speech recognition.

##### `abort(): Promise<void>`
Abort speech recognition immediately.

##### `switchEngine(engineConfig: EngineConfig): Promise<void>`
Switch to a different speech recognition engine.

##### `getCurrentEngine(): EngineInfo | null`
Get information about the currently active engine.

##### `cleanup(): Promise<void>`
Clean up resources and stop all recognition processes.

#### Properties

##### `isListening: boolean`
Whether the converter is currently listening/recording.

#### Static Methods

##### `getAvailableEngines(): Array<'web-speech' | 'vosk' | 'google-cloud'>`
Get list of available engines in the current environment.

##### `isEngineAvailable(engine: string): boolean`
Check if a specific engine is available.

##### `getEngineCapabilities(engine: string): EngineCapabilities`
Get capabilities and features of a specific engine.

##### `getBrowserSupport(): BrowserSupport`
Get browser compatibility information.

##### `quickTranscribe(source, options): Promise<SpeechRecognitionResult[]>`
Quick one-time transcription without managing instance lifecycle.

### Events

The VoiceToText class extends EventEmitter and emits the following events:

- `start` - Recognition started
- `end` - Recognition ended
- `result` - Transcription result available
- `error` - Error occurred
- `audiostart` - Audio input started
- `audioend` - Audio input ended
- `soundstart` - Sound detected
- `soundend` - Sound ended
- `speechstart` - Speech detected
- `speechend` - Speech ended

### Types and Interfaces

#### SpeechRecognitionResult

```typescript
interface SpeechRecognitionResult {
  transcript: string;
  confidence: number;
  isFinal: boolean;
  alternatives?: Array<{
    transcript: string;
    confidence: number;
  }>;
  timestamp?: {
    start: number;
    end: number;
  };
}
```

#### SpeechRecognitionConfig

```typescript
interface SpeechRecognitionConfig {
  language?: string; // Language code (e.g., 'en-US')
  sampleRate?: number; // Audio sample rate
  continuous?: boolean; // Enable continuous recognition
  interimResults?: boolean; // Return interim results
  maxAlternatives?: number; // Maximum alternatives to return
  confidenceThreshold?: number; // Confidence threshold (0-1)
  phrases?: string[]; // Custom vocabulary
  encoding?: 'LINEAR16' | 'FLAC' | 'MULAW' | 'AMR' | 'AMR_WB' | 'OGG_OPUS';
}
```

#### EngineConfig

```typescript
interface EngineConfig {
  engine: 'web-speech' | 'vosk' | 'google-cloud';
  apiKey?: string; // For cloud services
  modelPath?: string; // For offline engines
  projectId?: string; // For Google Cloud
  endpoint?: string; // Custom endpoint URL
}
```

### Quick Start Functions

#### `transcribeFromFile(filePath: string, options?): Promise<SpeechRecognitionResult[]>`
Quick transcription from an audio file.

#### `transcribeFromMicrophone(options?): Promise<SpeechRecognitionResult[]>`
Quick transcription from microphone input.

#### `transcribeFromStream(stream: NodeJS.ReadableStream, options?): Promise<SpeechRecognitionResult[]>`
Quick transcription from an audio stream.

#### `createVoiceToText(options?): VoiceToText`
Factory function to create a VoiceToText instance.

#### `getSystemInfo(): SystemInfo`
Get system information and available engines.


## Engine Comparison

| Feature | Web Speech API | Vosk | Google Cloud Speech |
|---------|---------------|------|-------------------|
| **Environment** | Browser only | Node.js + Browser | Node.js + Browser |
| **Online/Offline** | Online | Offline | Online |
| **Accuracy** | High | Medium-High | Very High |
| **Speed** | Fast | Fast | Fast |
| **Privacy** | Data sent to Google | Fully private | Data sent to Google |
| **Cost** | Free | Free | Pay per use |
| **Languages** | 60+ | 20+ | 125+ |
| **File Processing** | Limited | Yes | Yes |
| **Streaming** | Yes | Yes | Yes |
| **Setup Complexity** | None | Model download required | API key required |

### When to Use Each Engine

**Web Speech API:**
- Browser-based applications
- Quick prototyping
- No setup required
- Real-time microphone input

**Vosk:**
- Privacy-sensitive applications
- Offline processing required
- Cost-sensitive projects
- Edge computing scenarios

**Google Cloud Speech:**
- High accuracy requirements
- Production applications
- Multiple language support
- Advanced features needed

## Configuration

### Environment Variables

```bash
# Google Cloud Speech (optional)
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
GOOGLE_CLOUD_PROJECT=your-project-id

# OpenAI API (if using Whisper integration)
OPENAI_API_KEY=your-openai-api-key
```

### Vosk Model Setup

1. Download a Vosk model from [alphacephei.com/vosk/models](https://alphacephei.com/vosk/models)
2. Extract the model to a directory
3. Use the model path in your configuration:

```javascript
const voiceToText = new VoiceToText({
  defaultEngine: {
    engine: 'vosk',
    modelPath: './models/vosk-model-en-us-0.22'
  }
});
```

### Google Cloud Setup

1. Create a Google Cloud project
2. Enable the Speech-to-Text API
3. Create a service account and download the JSON key
4. Set the environment variable or pass credentials directly:

```javascript
const voiceToText = new VoiceToText({
  defaultEngine: {
    engine: 'google-cloud',
    apiKey: 'your-api-key',
    projectId: 'your-project-id'
  }
});
```

## Browser Usage

### CDN

```html
<script src="https://unpkg.com/voice-to-text-converter/lib/browser.js"></script>
```

### ES Modules

```javascript
import { VoiceToText } from 'voice-to-text-converter/browser';

const voiceToText = new VoiceToText();
await voiceToText.initialize();

// Request microphone permission
const hasPermission = await voiceToText.requestMicrophonePermission();
if (hasPermission) {
  await voiceToText.fromMicrophone({ duration: 5000 });
}
```

### Browser Compatibility

- Chrome 25+
- Firefox 44+
- Safari 14.1+
- Edge 79+

**Note:** Web Speech API requires HTTPS in production environments.

## Error Handling

```javascript
import { VoiceToText, SpeechRecognitionError, SpeechRecognitionErrorType } from 'voice-to-text-converter';

const voiceToText = new VoiceToText();

voiceToText.on('error', (error) => {
  switch (error.type) {
    case SpeechRecognitionErrorType.NO_SPEECH:
      console.log('No speech detected');
      break;
    case SpeechRecognitionErrorType.AUDIO_CAPTURE:
      console.log('Microphone access denied');
      break;
    case SpeechRecognitionErrorType.NETWORK:
      console.log('Network error occurred');
      break;
    case SpeechRecognitionErrorType.NOT_ALLOWED:
      console.log('Permission denied');
      break;
    default:
      console.error('Recognition error:', error.message);
  }
});

try {
  await voiceToText.initialize();
  const results = await voiceToText.fromFile('audio.wav');
} catch (error) {
  console.error('Failed to process audio:', error.message);
}
```

## Performance Tips

### Optimization

1. **Choose the right engine** for your use case
2. **Set appropriate sample rates** (16000 Hz is usually sufficient)
3. **Use confidence thresholds** to filter low-quality results
4. **Enable interim results** only when needed
5. **Implement proper cleanup** to prevent memory leaks

### Memory Management

```javascript
// Always clean up resources
const voiceToText = new VoiceToText();
try {
  await voiceToText.initialize();
  // ... use the converter
} finally {
  await voiceToText.cleanup();
}

// Or use the quick functions for one-time use
const results = await transcribeFromFile('audio.wav');
```

### Batch Processing

```javascript
// Process multiple files efficiently
const voiceToText = new VoiceToText();
await voiceToText.initialize();

const files = ['audio1.wav', 'audio2.wav', 'audio3.wav'];
const results = await Promise.all(
  files.map(file => voiceToText.fromFile(file))
);

await voiceToText.cleanup();
```


## Troubleshooting

### Common Issues

#### "No speech recognition engines are available"
- **Cause:** No compatible engines are installed or available
- **Solution:** Install optional dependencies (`vosk`, `@google-cloud/speech`) or use in a browser environment

#### "Microphone access denied"
- **Cause:** Browser blocked microphone access
- **Solution:** Enable microphone permissions in browser settings, ensure HTTPS in production

#### "Model not found" (Vosk)
- **Cause:** Vosk model path is incorrect or model not downloaded
- **Solution:** Download the correct model and verify the path

#### "Authentication failed" (Google Cloud)
- **Cause:** Invalid API credentials
- **Solution:** Verify API key and project ID, check service account permissions

#### Poor recognition accuracy
- **Cause:** Low audio quality, wrong language setting, or inappropriate engine
- **Solution:** 
  - Improve audio quality (reduce noise, use better microphone)
  - Set correct language in configuration
  - Try different engines
  - Adjust confidence threshold

### Debug Mode

Enable debug mode to get detailed logging:

```javascript
const voiceToText = new VoiceToText({ debug: true });
```

### Testing Audio Setup

```javascript
import { getSystemInfo, VoiceToText } from 'voice-to-text-converter';

// Check system capabilities
const systemInfo = getSystemInfo();
console.log('Available engines:', systemInfo.availableEngines);
console.log('Platform:', systemInfo.platform);

// Test browser support
if (systemInfo.platform === 'browser') {
  const support = VoiceToText.getBrowserSupport();
  console.log('Web Speech API:', support.webSpeechAPI);
  console.log('Media Recorder:', support.mediaRecorder);
  console.log('getUserMedia:', support.getUserMedia);
}
```

## Examples

See the `examples/` directory for complete working examples:

- `examples/node-basic.js` - Basic Node.js usage
- `examples/node-advanced.js` - Advanced Node.js features
- `examples/browser-simple.html` - Simple browser implementation
- `examples/browser-advanced.html` - Advanced browser features
- `examples/real-time.js` - Real-time speech recognition
- `examples/file-processing.js` - Batch file processing

## Testing

Run the test suite:

```bash
npm test
```

Run tests with coverage:

```bash
npm run test:coverage
```

Run tests in watch mode:

```bash
npm run test:watch
```

## Building

Build the package:

```bash
npm run build
```

Build in watch mode:

```bash
npm run build:watch
```

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Development Setup

1. Clone the repository:
```bash
git clone https://github.com/yourusername/voice-to-text-converter.git
cd voice-to-text-converter
```

2. Install dependencies:
```bash
npm install
```

3. Install optional dependencies for testing:
```bash
npm install vosk @google-cloud/speech node-record-lpcm16
```

4. Run tests:
```bash
npm test
```

5. Build the package:
```bash
npm run build
```

### Code Style

This project uses ESLint and TypeScript for code quality. Run linting:

```bash
npm run lint
npm run lint:fix
```

## Security Considerations

### Privacy

- **Web Speech API**: Audio data is sent to Google's servers
- **Google Cloud Speech**: Audio data is sent to Google Cloud (with enterprise privacy controls)
- **Vosk**: Fully offline, no data transmission

### Permissions

- Browser applications require microphone permission
- Ensure HTTPS for production browser deployments
- Validate and sanitize all audio file inputs

### Best Practices

1. Always request explicit user consent for microphone access
2. Implement proper error handling for permission denials
3. Use HTTPS in production environments
4. Consider data retention policies for transcribed text
5. Implement rate limiting for cloud-based engines

## License

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

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and changes.

## Support

- 📖 [Documentation](https://github.com/yourusername/voice-to-text-converter/wiki)
- 🐛 [Issue Tracker](https://github.com/yourusername/voice-to-text-converter/issues)
- 💬 [Discussions](https://github.com/yourusername/voice-to-text-converter/discussions)
- 📧 [Email Support](mailto:support@example.com)

## Acknowledgments

- [Vosk](https://alphacephei.com/vosk/) - Open source speech recognition toolkit
- [Google Cloud Speech-to-Text](https://cloud.google.com/speech-to-text) - Cloud-based speech recognition
- [Web Speech API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Speech_API) - Browser speech recognition

---

Made with ❤️ by the Voice-to-Text Converter team