React Speech Recognition Hook

Common errors

• regeneratorRuntime is not defined

  cause Missing `regenerator-runtime` polyfill, often in older environments or specific build setups (e.g., Next.js).
  fix Install `regenerator-runtime` (`npm i --save regenerator-runtime`) and import it at the very top of your application's entry file (e.g., `import 'regenerator-runtime/runtime';` in `_app.js` for Next.js or `index.js` for other React apps).

• SpeechRecognition is not defined (or similar reference error)

  cause Attempting to use `SpeechRecognition` object properties or methods without importing it as a default export, or in a browser that doesn't support the Web Speech API without a polyfill.
  fix Ensure you `import SpeechRecognition, { useSpeechRecognition } from 'react-speech-recognition';` and check `browserSupportsSpeechRecognition` before using the API. Consider applying a polyfill if cross-browser compatibility is needed.

• Microphone is blocked / Microphone access denied

  cause The user has explicitly denied microphone access, or the application is running in an insecure context (HTTP) where microphone access is prohibited by the browser.
  fix Deploy your application over HTTPS. Ensure the UI clearly prompts the user for microphone permission and handles the `isMicrophoneAvailable` state, guiding users to enable permissions if denied.

Warnings

• gotcha The Web Speech API has limited cross-browser support, with Chrome providing the most robust experience. Other browsers (like Firefox, Safari) may require polyfills for full functionality or might not support it at all without extra configuration. Always check `browserSupportsSpeechRecognition`.
  Fix: Implement a polyfill (e.g., `web-speech-cognitive-services`) for broader browser support by calling `SpeechRecognition.applyPolyfill()` early in your application lifecycle. Provide fallback UI when not supported.
• breaking The `browserSupportsSpeechRecognition` state will now return `false` on browsers that do not support the APIs required for Speech Recognition polyfills (e.g., Internet Explorer), even if a polyfill is used. If a recognition implementation is already listening when a polyfill is applied, it will be disconnected and turned off to prevent multiple recognizers running.
  Fix: Ensure your application correctly handles the `browserSupportsSpeechRecognition` state, especially when integrating polyfills, to display appropriate fallback content or UI elements.
• gotcha Microphone access requires user permission. The library now exposes `isMicrophoneAvailable` which becomes `false` if the user denies access. Attempting to start listening without prior user interaction (e.g., on component mount) may be blocked by browsers, resulting in errors or silent failure.
  Fix: Check `isMicrophoneAvailable` and render appropriate UI feedback. Always initiate `startListening` in response to a direct user action, such as a button click, to comply with browser security policies.
• gotcha Continuous listening (`continuous: true`) has varying levels of support and behavior across browsers. On Chrome for Android, it can lead to frequent microphone restarts and an annoying 'beeping' sound, which is an OS-level behavior not controllable by the browser.
  Fix: Use `browserSupportsContinuousListening` to detect support. Avoid continuous listening on platforms where it's known to be problematic, or provide a 'push-to-talk' alternative.
• gotcha In production environments, the Web Speech API requires a secure context (HTTPS) to function correctly. It will not work over plain HTTP, even on local IP addresses, and microphone access will be blocked.
  Fix: Always deploy applications using `react-speech-recognition` over HTTPS. For local development on non-localhost IPs, you might need to configure browser flags or trust certificates.

Install

• npm install react-speech-recognition npm
• yarn add react-speech-recognition yarn
• pnpm add react-speech-recognition pnpm

Imports

• useSpeechRecognition
  wrong:

  import { useSpeechRecognition } from 'react-speech-recognition'; // Missing default export for SpeechRecognition object

  correct:

  import SpeechRecognition, { useSpeechRecognition } from 'react-speech-recognition';

  The primary hook for accessing speech recognition state and functions. It's often imported alongside the `SpeechRecognition` object, which provides global control methods.
• SpeechRecognition
  wrong:

  import { SpeechRecognition } from 'react-speech-recognition'; // Incorrectly imported as a named export

  correct:

  import SpeechRecognition, { useSpeechRecognition } from 'react-speech-recognition';

  This is the default export, providing global methods like `startListening`, `stopListening`, and `applyPolyfill`. It should be imported as a default, not a named export.
• applyPolyfill
  wrong:

  import { applyPolyfill } from 'react-speech-recognition';

  correct:

  import SpeechRecognition from 'react-speech-recognition';
  SpeechRecognition.applyPolyfill(MyCustomSpeechRecognition);

  The `applyPolyfill` method is a static method on the default `SpeechRecognition` object, used to integrate custom Web Speech API implementations for broader browser support.

Quickstart

This quickstart demonstrates basic speech-to-text functionality, including starting/stopping recognition, resetting the transcript, handling browser support, microphone availability, and defining simple voice commands.

import React from 'react';
import SpeechRecognition, { useSpeechRecognition } from 'react-speech-recognition';

const Dictaphone = () => {
  const commands = [
    {
      command: ['hello', 'hi'],
      callback: () => alert('Hello there!')
    },
    {
      command: 'open * website',
      callback: (website) => {
        window.open(`https://www.${website.split(' ').join('')}.com`);
      }
    },
    {
      command: ['clear', 'reset'],
      callback: () => resetTranscript()
    }
  ];

  const { 
    transcript, 
    listening, 
    resetTranscript, 
    browserSupportsSpeechRecognition, 
    isMicrophoneAvailable,
    finalTranscript
  } = useSpeechRecognition({
    commands,
    continuous: false // Set to true for continuous listening, but be aware of browser quirks
  });

  if (!browserSupportsSpeechRecognition) {
    return <span>Browser doesn't support speech recognition. Consider a polyfill.</span>;
  }

  if (!isMicrophoneAvailable) {
    return <span>Microphone is not available or permission was denied.</span>;
  }

  return (
    <div>
      <p>Microphone: {listening ? 'ON' : 'OFF'}</p>
      <button onClick={() => SpeechRecognition.startListening({ language: 'en-US' })}>Start</button>
      <button onClick={SpeechRecognition.stopListening}>Stop</button>
      <button onClick={resetTranscript}>Reset Transcript</button>
      <p>Transcript: {transcript}</p>
      <p>Final Transcript: {finalTranscript}</p>
    </div>
  );
};

export default Dictaphone;