HTML: Markup language
CSS: Styling language
JavaScript: Scripting language
Web APIs: Programming interfaces
Learn web development
Get to know MDN better
The Web Speech API provides two distinct areas of functionality — speech recognition and speech synthesis (also known as text to speech, or TTS) — which open up interesting possibilities for accessibility and control. This article provides an introduction to both the areas, along with demos.
Speech recognition involves receiving audio from a device's microphone (or from an audio track), which is then checked by a speech recognition service. When the service successfully recognizes a word or phrase, it returns a text string (or a list of strings) that you can use to initiate further actions.
The Web Speech API has a main controller interface for this — SpeechRecognition — and several related interfaces for representing results.
Generally, the speech recognition system available on the user's device is used for the speech recognition. Most modern operating systems have a speech recognition system for iss
uing voice commands, such as Dictation on macOS or Copilot on Windows.
By default, using speech recognition on a web page involves a server-based recognition engine. Your audio is sent to a web service for recognition processing, so it won't work offline.
To improve privacy and performance, you can specify that speech recognition be performed on the device. This ensures that neither the audio nor the transcribed speech are sent to a third-party service for processing. We cover the on-device functionality in more detail in the On-device speech recognition section.
To demonstrate how to use speech recognition, we've created a sample app called Speech color changer. After you press the Start recognition button, say an HTML color keyword. The app's background color will change to that color.
To run the demo, navigate to the live demo URL in a supporting browser.
The HTML and CSS for the app are basic. There's a title, an instruction paragraph (<p>), a control <button>, and an output paragraph where we display diagnostic messages, including the words that our app recognized.
The CSS provides a basic responsive styling so that it looks OK across devices.
Let's look at the JavaScript in a bit more detail.
Some browsers currently support speech recognition with prefixed properties. Therefore, at the start of our code, we include these lines to allow for both prefixed properties and unprefixed versions:
The next part of our code defines a few sample colors that we print to the
UI to give users an idea of what to say:
Next, we define a speech recognition instance to control the recognition in our app. We do this by using the SpeechRecognition() constructor.
We then set a few properties of the recognition instance:
After grabbing references to the output paragraph, the <html> element, the instruction paragraph, and the <button>, we implement an onclick handler. When a user presses the button, the speech recognition service starts by calling SpeechRecognition.start(). We've also used a forEach() method to output colored indicators showing what colors users can try to say.
Once the speech recognition has started, several event handlers become available, which you can use to retrieve results and other related information (see Events for SpeechRecognition). The most common one is the result event, which fires after a successful result is received:
The second line is a bit complex, so we'll explain each part here:
We also use the speechend event to stop the speech recognition service (using SpeechRecognition.stop()) after a single word has been recognized:
The last two handlers cover cases where the spoken term isn't recognized or an error occurs with the recognition. The nomatch event is supposed to handle the first case, although in most cases the recognition engine will return something, even if it is unintelligible:
The error event handles cases when there is an actual error with the recognition — the SpeechRecognitionErrorEvent.error property contains the error returned:
Speech recognition is usually performed using an online service. This means that an audio recording is sent to a server for processing, and the results are then returned to the browser. This has a couple of problems:
To mitigate these problems, the Web Speech API lets you specify that speech recognition should be handled on-device by the browser. This req
uires a one-time language pack download for each language you want to recognize; once installed, the functionality will be available offline.
This section explains how to use on-device speech recognition.
To demonstrate on-device speech recognition, we've created a sample app called On-device speech color changer (run the demo live).
This demo works in a very similar fashion to the online speech color changer demo discussed earlier, with the differences noted below.
Note: In the original speech color changer demo, we included extra lines to handle browsers that support the Web Speech API only with vendor-prefixed properties (see the Prefixed properties section for more details). In the on-device version of the demo, prefix-handling code is not needed because the implementations that support this functionality do so without prefixes.
To specify that you want to use the browser's on-device processing, set the SpeechRecognition.processLocally property to true before starting any speech recognition (the default value is false):
For on-device speech recognition to work, the browser must have a language pack installed for the language you want to recognize. If you run the start() method after specifying processLocally = true but the correct language pack isn't installed, the function call will fail with a language-not-supported error.
To get the correct language pack installed, ensure you follow these two steps:
These steps are handled in the following click event handler on the app's control <button>:
The available() method takes an option