# react-dictate-button [![npm version](https://badge.fury.io/js/react-dictate-button.svg)](https://badge.fury.io/js/react-dictate-button) [![Build Status](https://travis-ci.org/compulim/react-dictate-button.svg?branch=master)](https://travis-ci.org/compulim/react-dictate-button) A button to start speech recognition using [Web Speech API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Speech_API/Using_the_Web_Speech_API), with an easy to understand event lifecycle. # Breaking changes ## [2.0.0] - 2021-05-15 - Requires [`react@>=16.8.0`](https://npmjs.com/package/react) and [`core-js@3`](https://npmjs.com/package/core-js`) - Modifying props while recognition has started will no longer abort recognition immediately, props will be updated in next recognition - `SpeechGrammarList` is only constructed when `grammar` props is present - If `speechRecognition` prop is not present, capability detection is now done through `window.mediaDevices.getUserMedia` # Demo Try out this component at [github.io/compulim/react-dictate-button](https://github.io/compulim/react-dictate-button/). # Background Reasons why we need to build our own component, instead of using [existing packages](https://www.npmjs.com/search?q=react%20speech) on NPM: - Most browsers required speech recognition (or WebRTC) to be triggered by a user event (button click) - Bring your own engine for [Web Speech API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Speech_API/Using_the_Web_Speech_API) - Enable speech recognition on unsupported browsers by bridging it with [cloud-based service](https://npmjs.com/package/web-speech-cognitive-services) - Support grammar list thru [JSpeech Grammar Format](https://www.w3.org/TR/jsgf/) - Ability to interrupt recognition - Ability to [morph into other elements](#customization-thru-morphing) # How to use First, install our production version by `npm install react-dictate-button`. Or our development version by `npm install react-dictate-button@master`. ```jsx import DictateButton from 'react-dictate-button'; export default () => ( Start/stop ); ``` ## Props | Name | Type | Default | Description | | ------------------- | ------------------------ | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `className` | `string` | `undefined` | Class name to apply to the button | | `disabled` | `boolean` | `false` | `true` to abort ongoing recognition and disable the button, otherwise, `false` | | `extra` | `{ [key: string]: any }` | `{}` | Additional properties to set to [`SpeechRecognition`](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition) before `start`, useful when bringing your own [`SpeechRecognition`](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition) | | `grammar` | `string` | `undefined` | Grammar list in [JSGF format](https://developer.mozilla.org/en-US/docs/Web/API/SpeechGrammarList/addFromString) | | `lang` | `string` | `undefined` | Language to recognize, for example, `'en-US'` or [`navigator.language`](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorLanguage/language) | | `speechGrammarList` | `any` | `window.SpeechGrammarList` (or vendor-prefixed) | Bring your own [`SpeechGrammarList`](https://developer.mozilla.org/en-US/docs/Web/API/SpeechGrammarList) | | `speechRecognition` | `any` | `window.SpeechRecognition` (or vendor-prefixed) | Bring your own [`SpeechRecognition`](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition) | > Note: change of `extra`, `grammar`, `lang`, `speechGrammarList`, and `speechRecognition` will not take effect until next speech recognition is started. ## Events

Name	Signature	Description
`onClick`	(event: MouseEvent) => void	Emit when the user click on the button, `preventDefault` will stop recognition from starting
`onDictate`	({ result: { confidence: number, transcript: number }, type: 'dictate' }) => void	Emit when recognition is completed
`onError`	(event: SpeechRecognitionErrorEvent) => void	Emit when error has occurred or recognition is interrupted, see below
`onProgress`	({ abortable: boolean, results: [{ confidence: number, transcript: number }], type: 'progress' }) => void	Emit for interim results, the array contains every segments of recognized text
`onRawEvent`	(event: SpeechRecognitionEvent) => void	Emit for handling raw events from `SpeechRecognition`

## Hooks > Although previous versions exported a React Context, it is recommended to use the hooks interface. | Name | Signature | Description | | --------------- | ----------- | --------------------------------------------------------------------------------------- | | `useAbortable` | `[boolean]` | If ongoing speech recognition can be aborted, `true`, otherwise, `false` | | `useReadyState` | `[number]` | Returns the current state of recognition, refer to [this section](#function-as-a-child) | | `useSupported` | `[boolean]` | If speech recognition is supported, `true`, otherwise, `false` | ### Checks if speech recognition is supported To determines whether speech recognition is supported in the browser: - If `speechRecognition` prop is `undefined` - If both [`window.navigator.mediaDevices`](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices) and [`window.navigator.mediaDevices.getUserMedia`](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia) are falsy, it is not supported - Probably the browser is not on a secure HTTP connection - If both `window.SpeechRecognition` and vendor-prefixed are falsy, it is not supported - If recognition failed once with `not-allowed` error code, it is not supported - Otherwise, it is supported > Even the browser is on an insecure HTTP connection, `window.SpeechRecognition` (or vendor-prefixed) will continue to be truthy. Instead, `mediaDevices.getUserMedia` is used for capability detection. ### Event lifecycle One of the design aspect is to make sure events are easy to understand and deterministic. First rule of thumb is to make sure `onProgress` will lead to either `onDictate` or `onError`. Here are some samples of event firing sequence (tested on Chrome 67): - Happy path: speech is recognized 1. `onProgress({})` (just started, therefore, no `results`) 2. `onProgress({ results: [] })` 3. `onDictate({ result: ... })` - Heard some sound, but nothing can be recognized 1. `onProgress({})` 2. `onDictate({})` (nothing is recognized, therefore, no `result`) - Nothing is heard (audio device available but muted) 1. `onProgress({})` 2. `onError({ error: 'no-speech' })` - Recognition aborted 1. `onProgress({})` 2. `onProgress({ results: [] })` 3. While speech is getting recognized, set `props.disabled` to `false`, abort recognition 4. `onError({ error: 'aborted' })` - Not authorized to use speech or no audio device is availablabortable: truee 1. `onError({ error: 'not-allowed' })` ## Function as a child Instead of passing child elements, you can pass a function to render different content based on ready state. This is called [function as a child](https://reactjs.org/docs/render-props.html#using-props-other-than-render). | Ready state | Description | | ----------- | -------------------------------------------------------------------------- | | `0` | Not started | | `1` | Starting recognition engine, recognition is not ready until it turn to `2` | | `2` | Recognizing | | `3` | Stopping | For example, ```jsx {({ readyState }) => readyState === 0 ? 'Start' : readyState === 1 ? 'Starting...' : readyState === 2 ? 'Listening...' : 'Stopping...' } ``` # Customization thru morphing You can build your own component by copying our layout code, without messing around the [logic code behind the scene](packages/component/src/Composer.js). For details, please refer to [`DictateButton.js`](packages/component/src/DictateButton.js), [`DictateCheckbox.js`](packages/component/src/DictateCheckbox.js), and [`DictationTextbox.js`](packages/playground/src/DictationTextbox.js). ## Checkbox version In addition to `

react-dictate-button

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Sick of boring JavaScript newsletters?

Downloads in past