v3 makes use of React hooks to simplify the consumption of react-speech-recognition:
Replacing the higher order component with a React hook
Introducing commands, functions that get executed when the user says a particular phrase
A clear separation between all parts of react-speech-recognition that are global (e.g. whether the microphone is listening or not) and local (e.g. transcripts). This makes it possible to have multiple components consuming the global microphone input while maintaining their own transcripts and commands
Requires React 16.8
Adds code coverage step to CI
Some default prop values have changed so check those out below
This was a global option in v2 that would cause the microphone to start listening from the beginning by default. In v3, the microphone is initially turned off by default. It can be turned on when your component first renders by either useEffect if you're using hooks or componentDidMount if you're still using class components. It is recommended that you do this close to the root of your application as this affects global state.
This was another global option in v2 that would by default have the microphone permanently listen to the user, even when they finished speaking. This default behaviour did not match the most common usage pattern, which is to use react-speech-recognition for "press to talk" buttons that stop listening once a command has been spoken.
continuous is now an option that can be passed to SpeechRecognition.startListening. It is false by default, but can be overridden like so:
This is a new prop in v3 that is passed into useSpeechRecognition from the consumer. Its default value makes a subtle change to the previous behaviour. When continuous was set to false in v2, the transcript would not be reset when the microphone started listening again. clearTranscriptOnListen changes that, clearing the component's transcript at the beginning of every new discontinuous speech. To replicate the old behaviour, this can be turned off when passing props into useSpeechRecognition:
SpeechRecognition used to inject props into components in v2. These props are still available, but in different forms.
transcript
This is now state returned by useSpeechRecognition. This transcript is local to the component using the hook.
resetTranscript
This is now state returned by useSpeechRecognition. This only resets the component's transcript, not any global state.
startListening
This is now available as SpeechRecognition.startListening.
stopListening
This is now available as SpeechRecognition.stopListening.
abortListening
This is now available as SpeechRecognition.abortListening.
browserSupportsSpeechRecognition
This is now available as the function SpeechRecognition.browserSupportsSpeechRecognition.
listening
This is now state returned by useSpeechRecognition. This is the global listening state.
interimTranscript
This is now state returned by useSpeechRecognition. This transcript is local to the component using the hook.
finalTranscript
This is now state returned by useSpeechRecognition. This transcript is local to the component using the hook.
recognition
This is now returned by the function SpeechRecognition.getRecognition.
Commands
To respond when the user says a particular phrase, you can pass in a list of commands to the useSpeechRecognition hook. Each command is an object with the following properties:
command: This is a string or RegExp representing the phrase you want to listen for
callback: The function that is executed when the command is spoken
matchInterim: Boolean that determines whether "interim" results should be matched against the command. This will make your component respond faster to commands, but also makes false positives more likely - i.e. the command may be detected when it is not spoken. This is false by default and should only be set for simple commands.
Command symbols
To make commands easier to write, the following symbols are supported:
Splats: this is just a * and will match multi-word text:
Example: 'I would like to order *'
The words that match the splat will be passed into the callback, one argument per splat
Named variables: this is written :<name> and will match a single word:
Example: 'I am :height metres tall'
The one word that matches the named variable will be passed into the callback
Optional words: this is a phrase wrapped in parentheses ( and ), and is not required to match the command:
Example: 'Pass the salt (please)'
The above example would match both 'Pass the salt' and 'Pass the salt please'
Example with commands
import React, { useState } from 'react'
import SpeechRecognition, { useSpeechRecognition } from 'react-speech-recognition'
const Dictaphone = () => {
const [message, setMessage] = useState('')
const commands = [
{
command: 'I would like to order *',
callback: (food) => setMessage(`Your order is for: ${food}`)
},
{
command: 'The weather is :condition today',
callback: (condition) => setMessage(`Today, the weather is ${condition}`)
},
{
command: 'My top sports are * and *',
callback: (sport1, sport2) => setMessage(`#1: ${sport1}, #2: ${sport2}`)
},
{
command: 'Pass the salt (please)',
callback: () => setMessage('My pleasure')
},
{
command: 'Hello',
callback: () => setMessage('Hi there!'),
matchInterim: true
}
]
const { transcript } = useSpeechRecognition({ commands })
if (!SpeechRecognition.browserSupportsSpeechRecognition()) {
return null
}
return (
<div>
<p>{message}</p>
<p>{transcript}</p>
</div>
)
}
export default Dictaphone
Migrating from v2 to v3
v3 makes use of React hooks to simplify the consumption of
react-speech-recognition
:react-speech-recognition
that are global (e.g. whether the microphone is listening or not) and local (e.g. transcripts). This makes it possible to have multiple components consuming the global microphone input while maintaining their own transcripts and commandsThe original Dictaphone example
In v2
In v3
autoStart
This was a global option in v2 that would cause the microphone to start listening from the beginning by default. In v3, the microphone is initially turned off by default. It can be turned on when your component first renders by either
useEffect
if you're using hooks orcomponentDidMount
if you're still using class components. It is recommended that you do this close to the root of your application as this affects global state.continuous
This was another global option in v2 that would by default have the microphone permanently listen to the user, even when they finished speaking. This default behaviour did not match the most common usage pattern, which is to use
react-speech-recognition
for "press to talk" buttons that stop listening once a command has been spoken.continuous
is now an option that can be passed toSpeechRecognition.startListening
. It isfalse
by default, but can be overridden like so:clearTranscriptOnListen
This is a new prop in v3 that is passed into
useSpeechRecognition
from the consumer. Its default value makes a subtle change to the previous behaviour. Whencontinuous
was set tofalse
in v2, the transcript would not be reset when the microphone started listening again.clearTranscriptOnListen
changes that, clearing the component's transcript at the beginning of every new discontinuous speech. To replicate the old behaviour, this can be turned off when passing props intouseSpeechRecognition
:Injected props
SpeechRecognition
used to inject props into components in v2. These props are still available, but in different forms.transcript
This is now state returned by
useSpeechRecognition
. This transcript is local to the component using the hook.resetTranscript
This is now state returned by
useSpeechRecognition
. This only resets the component's transcript, not any global state.startListening
This is now available as
SpeechRecognition.startListening
.stopListening
This is now available as
SpeechRecognition.stopListening
.abortListening
This is now available as
SpeechRecognition.abortListening
.browserSupportsSpeechRecognition
This is now available as the function
SpeechRecognition.browserSupportsSpeechRecognition
.listening
This is now state returned by
useSpeechRecognition
. This is the global listening state.interimTranscript
This is now state returned by
useSpeechRecognition
. This transcript is local to the component using the hook.finalTranscript
This is now state returned by
useSpeechRecognition
. This transcript is local to the component using the hook.recognition
This is now returned by the function
SpeechRecognition.getRecognition
.Commands
To respond when the user says a particular phrase, you can pass in a list of commands to the
useSpeechRecognition
hook. Each command is an object with the following properties:command
: This is a string orRegExp
representing the phrase you want to listen forcallback
: The function that is executed when the command is spokenmatchInterim
: Boolean that determines whether "interim" results should be matched against the command. This will make your component respond faster to commands, but also makes false positives more likely - i.e. the command may be detected when it is not spoken. This isfalse
by default and should only be set for simple commands.Command symbols
To make commands easier to write, the following symbols are supported:
*
and will match multi-word text:'I would like to order *'
:<name>
and will match a single word:'I am :height metres tall'
(
and)
, and is not required to match the command:'Pass the salt (please)'
'Pass the salt'
and'Pass the salt please'
Example with commands