@lakshmiprasanth/react-voice-to-text/README.md

A modern React package for voice-to-text conversion with real-time speech recognition and file upload support

# React Voice-to-Text

A modern React package for voice-to-text conversion with real-time speech recognition and file upload support. Built with TypeScript and optimized for browser environments.

## 🚀 Features

- **🎤 Real-time Voice Recording** - Record and transcribe speech in real-time
- **📁 File Upload Support** - Upload audio files for transcription
- **🌍 Multi-language Support** - Support for 60+ languages
- **⚡ React Hooks** - Easy-to-use hooks for voice recognition
- **🎨 Beautiful UI Components** - Pre-built, customizable React components
- **📱 Responsive Design** - Works on desktop and mobile devices
- **🔧 TypeScript Support** - Full TypeScript definitions included
- **🎯 Web Speech API** - Uses native browser speech recognition

## 📦 Installation

```bash
npm install @lakshmiprasanth/react-voice-to-text
# or
yarn add @lakshmiprasanth/react-voice-to-text
```

## 🎯 Quick Start

### Basic Usage

```jsx
import React from 'react';
import { VoiceToTextConverter } from '@lakshmiprasanth/react-voice-to-text';

function App() {
  return (
    <div className="App">
      <VoiceToTextConverter />
    </div>
  );
}
```

### Using React Hooks

```jsx
import React from 'react';
import { useVoiceToText } from '@lakshmiprasanth/react-voice-to-text';

function VoiceRecorder() {
  const {
    isInitialized,
    isRecording,
    results,
    error,
    startRecording,
    stopRecording,
    clearResults
  } = useVoiceToText();

  return (
    <div>
      <button 
        onClick={isRecording ? stopRecording : startRecording}
        disabled={!isInitialized}
      >
        {isRecording ? 'Stop Recording' : 'Start Recording'}
      </button>
      
      {error && <p>Error: {error}</p>}
      
      <div>
        {results.map((result, index) => (
          <p key={index}>
            {result.transcript} (Confidence: {(result.confidence * 100).toFixed(1)}%)
          </p>
        ))}
      </div>
    </div>
  );
}
```

## 🧩 Components

### VoiceToTextConverter

The main component that provides a complete voice-to-text interface.

```jsx
import { VoiceToTextConverter } from '@lakshmiprasanth/react-voice-to-text';

<VoiceToTextConverter
  showFileUpload={true}
  showVoiceRecorder={true}
  showResults={true}
  defaultLanguage="en-US"
  onResult={(result) => console.log('New result:', result)}
  onError={(error) => console.error('Error:', error)}
/>
```

### VoiceRecorder

A component for real-time voice recording.

```jsx
import { VoiceRecorder } from '@lakshmiprasanth/react-voice-to-text';

<VoiceRecorder
  language="en-US"
  continuous={true}
  interimResults={true}
  onResult={(result) => console.log('Result:', result)}
  onError={(error) => console.error('Error:', error)}
/>
```

### FileUpload

A component for uploading and converting audio files.

```jsx
import { FileUpload } from '@lakshmiprasanth/react-voice-to-text';

<FileUpload
  acceptedFormats={['audio/*']}
  maxFileSize={50 * 1024 * 1024} // 50MB
  onConvert={(file, language) => {
    console.log('Converting file:', file.name);
  }}
  onError={(error) => console.error('Error:', error)}
/>
```

### ResultsDisplay

A component for displaying transcription results.

```jsx
import { ResultsDisplay } from '@lakshmiprasanth/react-voice-to-text';

<ResultsDisplay
  results={results}
  error={error}
  showConfidence={true}
  showStatus={true}
  maxResults={50}
  onClear={() => setResults([])}
/>
```

## 🎣 Hooks

### useVoiceToText

The main hook for voice-to-text functionality.

```jsx
import { useVoiceToText } from '@lakshmiprasanth/react-voice-to-text';

const {
  isInitialized,
  isRecording,
  isProcessing,
  results,
  error,
  browserSupport,
  startRecording,
  stopRecording,
  clearResults,
  clearError,
  updateConfig,
  getConfig
} = useVoiceToText({
  defaultRecognitionConfig: {
    language: 'en-US',
    continuous: true,
    interimResults: true
  },
  onResult: (result) => console.log('Result:', result),
  onError: (error) => console.error('Error:', error)
});
```

### useVoiceRecorder

A simplified hook for voice recording.

```jsx
import { useVoiceRecorder } from '@lakshmiprasanth/react-voice-to-text';

const {
  isInitialized,
  isRecording,
  results,
  error,
  startRecording,
  stopRecording,
  clearResults
} = useVoiceRecorder({
  language: 'en-US',
  continuous: true,
  interimResults: true
});
```

### useFileUpload

A hook for file upload functionality.

```jsx
import { useFileUpload } from '@lakshmiprasanth/react-voice-to-text';

const {
  selectedFile,
  isConverting,
  results,
  error,
  selectFile,
  convertFile,
  clearFile,
  clearResults,
  validateFile
} = useFileUpload({
  acceptedFormats: ['audio/*'],
  maxFileSize: 50 * 1024 * 1024,
  onConvert: async (file, language) => {
    // Handle file conversion
  }
});
```

### useSpeechRecognition

A low-level hook for direct speech recognition.

```jsx
import { useSpeechRecognition } from '@lakshmiprasanth/react-voice-to-text';

const {
  isSupported,
  isListening,
  transcript,
  finalTranscript,
  interimTranscript,
  error,
  start,
  stop,
  abort,
  reset
} = useSpeechRecognition({
  language: 'en-US',
  continuous: true,
  interimResults: true
});
```

## 🎨 Styling

All components come with built-in styles, but you can customize them using CSS classes or styled-components.

### Custom Styling

```jsx
<VoiceRecorder
  className="my-custom-recorder"
  style={{ 
    backgroundColor: '#f0f0f0',
    borderRadius: '12px',
    padding: '20px'
  }}
/>
```

### CSS Customization

```css
.my-custom-recorder {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
  border-radius: 16px;
  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.1);
}

.my-custom-recorder button {
  background: rgba(255, 255, 255, 0.2);
  border: 1px solid rgba(255, 255, 255, 0.3);
  color: white;
}
```

## 🌍 Language Support

The package supports 60+ languages. Here are some popular ones:

- English (US) - `en-US`
- English (UK) - `en-GB`
- Spanish - `es-ES`
- French - `fr-FR`
- German - `de-DE`
- Italian - `it-IT`
- Portuguese (Brazil) - `pt-BR`
- Japanese - `ja-JP`
- Korean - `ko-KR`
- Chinese (Simplified) - `zh-CN`
- Russian - `ru-RU`
- Arabic - `ar-SA`

## 🔧 Configuration

### VoiceToTextProvider Configuration

```jsx
import { VoiceToTextProvider } from '@lakshmiprasanth/react-voice-to-text';

<VoiceToTextProvider
  options={{
    defaultRecognitionConfig: {
      language: 'en-US',
      continuous: true,
      interimResults: true,
      maxAlternatives: 3
    },
    debug: false
  }}
  onResult={(result) => console.log('Result:', result)}
  onError={(error) => console.error('Error:', error)}
  onStart={() => console.log('Recording started')}
  onStop={() => console.log('Recording stopped')}
>
  <YourApp />
</VoiceToTextProvider>
```

## 🚀 Advanced Usage

### Custom Voice Recorder

```jsx
import React from 'react';
import { useVoiceToText, RecordingControls, ResultsDisplay } from '@lakshmiprasanth/react-voice-to-text';

function CustomVoiceRecorder() {
  const {
    isInitialized,
    isRecording,
    results,
    error,
    startRecording,
    stopRecording,
    clearResults
  } = useVoiceToText();

  return (
    <div className="custom-recorder">
      <h2>Custom Voice Recorder</h2>
      
      <RecordingControls
        isRecording={isRecording}
        onStart={startRecording}
        onStop={stopRecording}
        disabled={!isInitialized}
        startText="🎤 Start"
        stopText="⏹️ Stop"
      />
      
      <ResultsDisplay
        results={results}
        error={error}
        onClear={clearResults}
        showConfidence={true}
        showStatus={true}
      />
    </div>
  );
}
```

### File Upload with Custom UI

```jsx
import React from 'react';
import { useFileUpload, LanguageSelector } from '@lakshmiprasanth/react-voice-to-text';

function CustomFileUpload() {
  const {
    selectedFile,
    isConverting,
    results,
    error,
    selectFile,
    convertFile,
    clearResults
  } = useFileUpload();

  const [language, setLanguage] = useState('en-US');

  const handleFileChange = (event) => {
    const file = event.target.files[0];
    if (file) {
      selectFile(file);
    }
  };

  return (
    <div className="custom-file-upload">
      <h2>Custom File Upload</h2>
      
      <LanguageSelector
        value={language}
        onChange={setLanguage}
        showLabel={true}
        label="Select Language"
      />
      
      <input
        type="file"
        accept="audio/*"
        onChange={handleFileChange}
        disabled={isConverting}
      />
      
      {selectedFile && (
        <div>
          <p>Selected: {selectedFile.name}</p>
          <button
            onClick={() => convertFile(language)}
            disabled={isConverting}
          >
            {isConverting ? 'Converting...' : 'Convert'}
          </button>
        </div>
      )}
      
      {error && <p className="error">Error: {error}</p>}
      
      {results.length > 0 && (
        <div>
          <h3>Results:</h3>
          {results.map((result, index) => (
            <p key={index}>{result.transcript}</p>
          ))}
        </div>
      )}
    </div>
  );
}
```

## 🔍 Browser Support

The package uses the Web Speech API, which is supported in:

- ✅ Chrome 25+
- ✅ Safari 14.1+
- ✅ Edge 79+
- ✅ Firefox (limited support)
- ❌ Internet Explorer

## 📱 Mobile Support

The package works on mobile devices, but requires HTTPS in production for microphone access.

## 🛠️ Development

### Setup

```bash
git clone https://github.com/prasanth-sasuke/react-voice-to-text.git
cd react-voice-to-text
npm install
```

### Build

```bash
npm run build
```

### Test

```bash
npm test
```

### Storybook

```bash
npm run storybook
```

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🤝 Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## 📞 Support

- 📧 Email: support@example.com
- 🐛 Issues: [GitHub Issues](https://github.com/prasanth-sasuke/react-voice-to-text/issues)
- 📖 Documentation: [GitHub Wiki](https://github.com/prasanth-sasuke/react-voice-to-text/wiki)

## 🙏 Acknowledgments

- Web Speech API for speech recognition
- React team for the amazing framework
- TypeScript team for type safety
- All contributors and users

---

Made with ❤️ for the React community