Package Exports

@albertasoft/promptica-speech-to-text

Readme

🎤 Promptica Speech-to-Text

A powerful, flexible, and easy-to-use React speech-to-text library from promptica.ca Features include real-time transcription, multiple language support, and both hook and component-based APIs.

🎯 Zero Configuration Required - Import and use anywhere in your React app. No HTML elements needed. Full flexibility! just signe up in promptica.ca and get a access token.

✨ Features

🎯 Simple Hook API - Easy integration with useSpeechToText()
🎨 Pre-built UI Component - Ready-to-use interface with controls
⚡ Real-time Transcription - Live interim and final results
🌐 Global API - Access from anywhere via window.promptica.speechToText
📱 TypeScript Support - Full type safety and IntelliSense
🔧 Highly Configurable - Customize behavior and callbacks
🎭 Browser Compatible - Works with Chrome, Edge, Safari
🔐 Secure Authentication - Token-based API authentication with encryption
📊 Usage Analytics - Automatic tracking with browser metadata collection
🔒 Code Protection - Built with advanced obfuscation for security

📦 Installation

npm install promptica-speech-to-text
# or
pnpm install promptica-speech-to-text
# or
yarn add promptica-speech-to-text

Note: This is a library - no HTML elements are automatically created. You have full control over where and how to mount components. No <div id="..."> required!

🚀 Quick Start

Option 1: Using the Hook (Custom UI)

Perfect for when you want full control over the UI:

import { useSpeechToText } from 'promptica-speech-to-text';

function MyComponent() {
  const speechToText = useSpeechToText(
    { token: 'your-promptica-token' }, // Authentication
    {
      language: 'en-US',
      continuous: true,
      interimResults: true,
    }
  );

  return (
    <div>
      <button onClick={speechToText.start} disabled={!speechToText.ready}>
        Start Listening
      </button>
      <button onClick={speechToText.stop}>Stop</button>
      <p>Interim: {speechToText.interimTranscript}</p>
      <p>Final: {speechToText.finalTranscript}</p>
      {speechToText.error && <p>Error: {speechToText.error}</p>}
    </div>
  );
}

Option 2: Using the Pre-built UI Component

Use our styled component - just pass configuration:

import { useSpeechToText, SpeechToTextUI } from 'promptica-speech-to-text';

function App() {
  const speech = useSpeechToText({
    language: 'en-US',
    continuous: true,
    interimResults: true,
  });

  const handleTranscriptChange = (transcript: string) => {
    console.log('Current transcript:', transcript);
  };

  const handleFinalTranscript = (finalText: string) => {
    console.log('Final transcript:', finalText);
  };

  return (
    <SpeechToTextUI
      instance={speech}
      showUI={true} // Set to false for headless mode
      onTranscriptChange={handleTranscriptChange}
      onFinalTranscript={handleFinalTranscript}
      placeholder="Click the microphone to start speaking..."
    />
  );
}

Option 3: Headless Mode (No UI at all!)

Perfect for voice commands, accessibility features, or when you want console-only control:

import { useSpeechToText, globalSpeechAPI } from 'promptica-speech-to-text';
import { useEffect } from 'react';

function App() {
  const speech = useSpeechToText({
    language: 'en-US',
    continuous: true,
  });
  
  // Initialize global API for console control
  useEffect(() => {
    globalSpeechAPI.init(speech);
  }, [speech]);

  // Use speech.transcript programmatically
  useEffect(() => {
    if (speech.transcript.includes('hello')) {
      console.log('User said hello!');
    }
  }, [speech.transcript]);

  // No UI rendered - all control via code or console!
  return null;
}

Then control from anywhere (even browser console):

// See all available commands
window.promptica.speechToText.help();

// Check current status
window.promptica.speechToText.getInstanceStatus();

// Start listening
window.promptica.speechToText.start();

// Stop listening
window.promptica.speechToText.stop();

// Change language
window.promptica.speechToText.setLanguage('es-ES');

// Get transcript
const text = window.promptica.speechToText.getTranscript();

// Get available languages
const languages = window.promptica.speechToText.getAvailableLanguages();

// Check browser support
window.promptica.speechToText.checkBrowserSupport();

📖 API Reference

`useSpeechToText(config?, callbacks?)`

The main hook for speech recognition.

Parameters

config (optional): SpeechToTextConfig

{
  continuous?: boolean;        // Keep listening (default: true)
  interimResults?: boolean;    // Show interim results (default: true)
  language?: string;           // Language code (default: 'en-US')
  maxAlternatives?: number;    // Max alternatives (default: 1)
  grammars?: SpeechGrammarList; // Speech grammars
}

callbacks (optional): SpeechToTextCallbacks

{
  onStart?: () => void;
  onEnd?: () => void;
  onResult?: (result: SpeechToTextResult) => void;
  onError?: (error: SpeechRecognitionErrorEvent) => void;
  onNoMatch?: () => void;
  onSoundStart?: () => void;
  onSoundEnd?: () => void;
  onSpeechStart?: () => void;
  onSpeechEnd?: () => void;
  onAudioStart?: () => void;
  onAudioEnd?: () => void;
}

Returns: `SpeechToTextInstance`

{
  start: () => void;                    // Start listening
  stop: () => void;                     // Stop listening
  abort: () => void;                    // Abort recognition
  isListening: boolean;                 // Current listening state
  isSupported: boolean;                 // Browser support check
  transcript: string;                   // Full transcript
  interimTranscript: string;            // Current interim text
  finalTranscript: string;              // All final text
  error: string | null;                 // Last error message
  setConfig: (config) => void;          // Update configuration
  setCallbacks: (callbacks) => void;    // Update callbacks
  clearTranscript: () => void;          // Clear all text
  getLanguages: () => string[];         // Get available languages
}

🎯 Usage Examples

Important: No HTML elements are required! Just import and use. The library gives you full control.

Example 1: Basic Transcription

import { useSpeechToText } from 'promptica-speech-to-text';

function BasicTranscription() {
  const { start, stop, transcript, isListening } = useSpeechToText();

  return (
    <div>
      <button onClick={isListening ? stop : start}>
        {isListening ? 'Stop' : 'Start'}
      </button>
      <p>{transcript}</p>
    </div>
  );
}

Example 2: With Custom Callbacks

import { useSpeechToText } from 'promptica-speech-to-text';

function CustomCallbacks() {
  const [results, setResults] = useState([]);

  const speechToText = useSpeechToText(
    { language: 'en-US', continuous: true },
    {
      onResult: (result) => {
        if (result.isFinal) {
          setResults(prev => [...prev, result.transcript]);
          console.log(`Confidence: ${result.confidence}`);
        }
      },
      onError: (error) => {
        console.error('Speech recognition error:', error);
      },
      onStart: () => console.log('Started listening'),
      onEnd: () => console.log('Stopped listening'),
    }
  );

  return (
    <div>
      <button onClick={speechToText.start}>Start</button>
      <button onClick={speechToText.stop}>Stop</button>
      <ul>
        {results.map((text, i) => (
          <li key={i}>{text}</li>
        ))}
      </ul>
    </div>
  );
}

Example 3: Multi-language Support

import { useSpeechToText } from 'promptica-speech-to-text';

function MultiLanguage() {
  const speechToText = useSpeechToText();
  const [language, setLanguage] = useState('en-US');

  const handleLanguageChange = (lang: string) => {
    setLanguage(lang);
    speechToText.setConfig({ language: lang });
  };

  return (
    <div>
      <select value={language} onChange={(e) => handleLanguageChange(e.target.value)}>
        {speechToText.getLanguages().map(lang => (
          <option key={lang} value={lang}>{lang}</option>
        ))}
      </select>
      <button onClick={speechToText.start}>Start</button>
      <button onClick={speechToText.stop}>Stop</button>
      <p>{speechToText.transcript}</p>
    </div>
  );
}

Example 4: Imperative Handle with Ref

import { forwardRef, useImperativeHandle, useRef } from 'react';
import { useSpeechToText, type SpeechToTextInstance } from 'promptica-speech-to-text';

export interface SpeechToTextRef extends SpeechToTextInstance {}

const SpeechToTextImperative = forwardRef<SpeechToTextRef>((_, ref) => {
  const speechToText = useSpeechToText();
  
  useImperativeHandle(ref, () => speechToText, [speechToText]);

  return (
    <div>
      <div>Status: {speechToText.isListening ? 'Listening' : 'Stopped'}</div>
      <div>Transcript: {speechToText.transcript}</div>
    </div>
  );
});

// Usage
function App() {
  const speechRef = useRef<SpeechToTextRef>(null);

  return (
    <div>
      <button onClick={() => speechRef.current?.start()}>Start</button>
      <button onClick={() => speechRef.current?.stop()}>Stop</button>
      <SpeechToTextImperative ref={speechRef} />
    </div>
  );
}

Example 5: With Form Integration

import { useSpeechToText } from 'promptica-speech-to-text';

function FormIntegration() {
  const [formData, setFormData] = useState({ message: '' });
  const speechToText = useSpeechToText({
    continuous: false,
    interimResults: false,
  });

  useEffect(() => {
    if (speechToText.finalTranscript) {
      setFormData(prev => ({
        ...prev,
        message: prev.message + ' ' + speechToText.finalTranscript,
      }));
      speechToText.clearTranscript();
    }
  }, [speechToText.finalTranscript]);

  return (
    <form>
      <textarea
        value={formData.message}
        onChange={(e) => setFormData({ message: e.target.value })}
        placeholder="Type or speak your message..."
      />
      <button type="button" onClick={speechToText.start}>
        🎤 Voice Input
      </button>
      <button type="submit">Send</button>
    </form>
  );
}

🌍 Supported Languages

en-US - English (United States)
en-GB - English (United Kingdom)
es-ES - Spanish (Spain)
fr-FR - French (France)
de-DE - German (Germany)
it-IT - Italian (Italy)
ja-JP - Japanese (Japan)
ko-KR - Korean (South Korea)
pt-BR - Portuguese (Brazil)
ru-RU - Russian (Russia)
zh-CN - Chinese (Simplified)
zh-TW - Chinese (Traditional)
ar-SA - Arabic (Saudi Arabia)
hi-IN - Hindi (India)
nl-NL - Dutch (Netherlands)
pl-PL - Polish (Poland)
tr-TR - Turkish (Turkey)
sv-SE - Swedish (Sweden)
da-DK - Danish (Denmark)
fi-FI - Finnish (Finland)

🔧 Configuration Options

SpeechToTextUI Props

interface SpeechToTextUIProps {
  onTranscriptChange?: (transcript: string) => void;
  onFinalTranscript?: (transcript: string) => void;
  showInterim?: boolean;           // Show interim results (default: true)
  className?: string;               // Custom container class
  buttonClassName?: string;         // Custom button class
  textareaClassName?: string;       // Custom textarea class
  language?: string;                // Initial language (default: 'en-US')
  continuous?: boolean;             // Continuous listening (default: true)
  placeholder?: string;             // Textarea placeholder
}

⚠️ Browser Support

The Web Speech API is supported in:

✅ Chrome 25+
✅ Edge 79+
✅ Safari 14.1+
❌ Firefox (not supported)

Check browser support:

const { isSupported } = useSpeechToText();

if (!isSupported) {
  return <div>Speech recognition is not supported in this browser.</div>;
}

🐛 Error Handling

const speechToText = useSpeechToText();

// Check for errors
if (speechToText.error) {
  // Common errors:
  // - "no-speech": No speech detected
  // - "audio-capture": Microphone not accessible
  // - "not-allowed": Permission denied
  // - "network": Network error
  console.error('Error:', speechToText.error);
}

📝 TypeScript Support

All components are fully typed. Import types:

import type {
  SpeechToTextConfig,
  SpeechToTextCallbacks,
  SpeechToTextInstance,
  SpeechToTextResult,
  SpeechToTextUIProps,
} from 'promptica-speech-to-text';

🔒 Permissions

The browser will request microphone permission on first use. Ensure your site is served over HTTPS in production.

🎭 Library vs Demo Mode

As a Library (Production)

When users install your library, no HTML elements are required:

// User's app - no HTML element needed!
import { useSpeechToText, SpeechToTextUI } from 'promptica-speech-to-text';

function UserApp() {
  const speech = useSpeechToText();
  
  // User mounts wherever they want
  return <SpeechToTextUI instance={speech} showUI={true} />;
}

Demo Mode (Development)

When running pnpm dev for testing, it automatically mounts to <div id="root"> which is already in index.html. This doesn't affect library users at all!

📖 See detailed explanation

📚 Advanced Usage

Custom Styling

The UI component accepts className props for custom styling:

<SpeechToTextUI
  className="my-container"
  buttonClassName="my-button"
  textareaClassName="my-textarea"
/>

Or use inline styles by modifying the styles object in speechToTextUi.tsx.

Dynamic Configuration

Update configuration on the fly:

const speechToText = useSpeechToText();

// Change language
speechToText.setConfig({ language: 'es-ES' });

// Enable continuous mode
speechToText.setConfig({ continuous: true });

// Multiple configs at once
speechToText.setConfig({
  language: 'fr-FR',
  continuous: false,
  interimResults: true,
});

🤝 Contributing

Contributions are welcome! Feel free to submit issues and pull requests.

📄 License

MIT License - feel free to use in your projects!

🙏 Acknowledgments

Built with React and the Web Speech API. Special thanks to the open-source community.

Made with ❤️ by Promptica

@albertasoft/promptica-speech-to-text