@dwack1234/arabic-voice-to-text-nextjs

🎤 Egyptian Arabic Speech-to-Text Component for React and Next.js applications.

A production-ready, customizable voice-to-text component that integrates with Egyptian Arabic STS (Speech-to-Text) API. Record audio directly from your browser and get high-quality Arabic transcriptions in real-time.

✨ Features

• 🎙️ Browser Audio Recording - MediaRecorder API integration with pause/resume
• 🇪🇬 Egyptian Arabic STS - Optimized for Egyptian Arabic dialect
• ⚡ Two Processing Methods - Pipeline (chunked) or Direct processing
• 🎨 Fully Customizable - Control appearance, behavior, and callbacks
• 📱 Responsive Design - Works on desktop and mobile browsers
• 🔧 TypeScript First - Full type safety and IntelliSense support
• ⚙️ Flexible Integration - Standalone or integrated into forms
• 🎯 Comprehensive Callbacks - Track every stage of recording and transcription

📦 Installation

npm install @dwack1234/arabic-voice-to-text-nextjs

yarn add @dwack1234/arabic-voice-to-text-nextjs

pnpm add @dwack1234/arabic-voice-to-text-nextjs

🚀 Quick Start

'use client';

import { ArabicVoiceToText } from '@dwack1234/arabic-voice-to-text-nextjs';
import '@dwack1234/arabic-voice-to-text-nextjs/dist/package.css';

export default function MyPage() {
  return (
    <ArabicVoiceToText
      apiEndpoint="http://192.168.4.54:8001"
      method="pipeline"
      maxDuration={60}
      callbacks={{
        onTranscriptionComplete: (result) => {
          console.log('Transcription:', result.text);
        },
      }}
    />
  );
}

📖 API Reference

Main Component: ArabicVoiceToText

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | apiEndpoint | string | http://192.168.4.54:8001 | STS API endpoint URL | | method | 'pipeline' \| 'direct' | 'pipeline' | Processing method | | maxDuration | number | 60 | Maximum recording duration (seconds) | | audioFormat | string | 'audio/webm' | Audio format for recording | | sampleRate | number | 16000 | Audio sample rate | | showTimer | boolean | true | Show recording timer | | allowEdit | boolean | true | Allow editing transcription | | direction | 'ltr' \| 'rtl' | 'rtl' | Text direction | | enableSounds | boolean | true | Enable sound effects | | callbacks | VoiceCallbacks | {} | Event callbacks | | className | string | '' | Custom CSS class | | onInsertText | (text: string) => void | - | Insert text callback |

Callbacks Interface

The component supports comprehensive callbacks for all events:

interface VoiceCallbacks {
  // Recording Events
  onRecordingStart?: (metadata: RecordingMetadata) => void;
  onRecordingStop?: (duration: number, audioBlob: Blob) => void;
  onRecordingPause?: (currentTime: number) => void;
  onRecordingResume?: (currentTime: number) => void;
  onRecordingError?: (error: Error) => void;
  
  // Transcription Events
  onTranscriptionStart?: (audioBlob: Blob) => void;
  onTranscriptionProgress?: (progress: number) => void;
  onTranscriptionComplete?: (result: TranscriptionResult) => void;
  onTranscriptionError?: (error: Error) => void;
  
  // Text Events
  onTextChange?: (newText: string, source: 'transcription' | 'external') => void;
  onTextInsert?: (text: string, targetField?: string) => void;
  
  // API Events
  onApiRequest?: (requestData: ApiRequestData) => void;
  onApiResponse?: (responseData: ApiResponseData) => void;
  onApiError?: (error: ApiError) => void;
  
  // Permission Events
  onMicrophonePermissionGranted?: () => void;
  onMicrophonePermissionDenied?: (error: Error) => void;
  
  // State Events
  onStatusChange?: (status: VoiceToTextStatus) => void;
}

🎯 Usage Examples

Example 1: Basic Standalone

import { ArabicVoiceToText } from '@dwack1234/arabic-voice-to-text-nextjs';

function App() {
  return (
    <ArabicVoiceToText
      apiEndpoint="http://192.168.4.54:8001"
      callbacks={{
        onTranscriptionComplete: (result) => {
          console.log('Text:', result.text);
          console.log('Duration:', result.duration);
          console.log('Language:', result.language);
        },
      }}
    />
  );
}

Example 2: Form Integration

import { useState } from 'react';
import { ArabicVoiceToText } from '@dwack1234/arabic-voice-to-text-nextjs';

function ContactForm() {
  const [message, setMessage] = useState('');
  
  return (
    <form>
      <textarea
        value={message}
        onChange={(e) => setMessage(e.target.value)}
        placeholder="Type or speak your message..."
      />
      
      <ArabicVoiceToText
        onInsertText={(text) => setMessage(prev => prev + ' ' + text)}
        callbacks={{
          onTranscriptionComplete: (result) => {
            // Automatically append to textarea
            setMessage(prev => prev + ' ' + result.text);
          },
        }}
      />
    </form>
  );
}

Example 3: Advanced Usage with All Callbacks

import { ArabicVoiceToText } from '@dwack1234/arabic-voice-to-text-nextjs';

function AdvancedExample() {
  return (
    <ArabicVoiceToText
      apiEndpoint="http://192.168.4.54:8001"
      method="pipeline"
      maxDuration={120}
      callbacks={{
        onRecordingStart: (metadata) => {
          console.log('Started recording:', metadata);
        },
        onRecordingStop: (duration, blob) => {
          console.log(`Recorded ${duration}s, size: ${blob.size}`);
        },
        onTranscriptionProgress: (progress) => {
          console.log(`Progress: ${progress}%`);
        },
        onTranscriptionComplete: (result) => {
          console.log('Result:', result);
          // Save to database
          saveToDB(result);
        },
        onApiError: (error) => {
          console.error('API Error:', error);
          alert(`Transcription failed: ${error.message}`);
        },
        onMicrophonePermissionDenied: (error) => {
          alert('Microphone access denied. Please allow microphone access.');
        },
        onStatusChange: (status) => {
          console.log('Status:', status);
        },
      }}
    />
  );
}

🔧 Processing Methods

Pipeline Method (Recommended)

Best for longer recordings. Processes audio in 30-second chunks for better accuracy and lower memory usage.

<ArabicVoiceToText
  method="pipeline"
  maxDuration={120}
/>

Direct Method

Best for short recordings (< 30s). Processes the entire audio file at once.

<ArabicVoiceToText
  method="direct"
  maxDuration={30}
/>

🎨 Styling

The component includes default styles. Import the CSS file:

import '@dwack1234/arabic-voice-to-text-nextjs/dist/package.css';

Custom Styling

Override styles using className or CSS modules:

<ArabicVoiceToText
  className="my-custom-class"
/>

.my-custom-class {
  /* Your custom styles */
  background: linear-gradient(to right, #667eea 0%, #764ba2 100%);
  border-radius: 16px;
}

🌐 Browser Support

| Browser | Minimum Version | Notes | |---------|----------------|-------| | Chrome | 49+ | ✅ Full support | | Firefox | 25+ | ✅ Full support | | Safari | 14.1+ | ✅ Full support (iOS 14.5+) | | Edge | 79+ | ✅ Full support |

Requirements:

• MediaRecorder API support
• getUserMedia API support
• Secure context (HTTPS or localhost)

🔒 Privacy & Security

• No Data Storage: Audio is processed in real-time and not stored by the component
• HTTPS Required: For production, serve your app over HTTPS
• API Security: The STS API should implement proper authentication
• Microphone Permission: Users must explicitly grant microphone access

🤝 Contributing

Contributions are welcome! Please check the IMPLEMENTATION_GUIDE.md for development setup.

📝 License

MIT © dwack1234

🆘 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Documentation: Full Docs

🙏 Acknowledgments

• Egyptian Arabic STS API
• MediaRecorder Web API
• React & Next.js communities

Made with ❤️ for the Arabic-speaking community