Skip to content
Tutorials Center
My learning

Topics

Lesson 104 of 122 ยท Web APIs

Speech Synthesis and Speech Recognition

Make the browser speak with speechSynthesis and listen with SpeechRecognition. Pick voices, control rate and pitch, handle events, and design for privacy.

Browsers can talk and, in many cases, listen. The Web Speech API has two halves that have very different levels of support. Speech synthesis (text to speech) is available in every major browser and works offline with the voices installed on the device. Speech recognition (speech to text) is far patchier: where it exists, it usually sends audio to a cloud service.

Used well, speech makes pages more useful: reading an article aloud, pronouncing vocabulary in a language app, hands-free commands in a kitchen. Used badly, it is noisy and intrusive. This lesson shows how both halves work, the events you need, and how to keep users in control.

Speech output is not a replacement for accessible HTML. Screen reader users already have their own voice and settings, and a page that talks over them is a nuisance. Use speechSynthesis for features people choose to turn on, never for narrating your interface automatically.

Speech synthesis

The entry point is window.speechSynthesis. You create an utterance, a piece of text with settings, and hand it to the speech queue.

JavaScript
const utterance = new SpeechSynthesisUtterance("Hello from the browser!");
utterance.lang = "en-US";
utterance.rate = 1;     // 0.1 to 10, default 1
utterance.pitch = 1;    // 0 to 2, default 1
utterance.volume = 1;   // 0 to 1
speechSynthesis.speak(utterance);

Utterances go into a queue and are spoken one after another. Control the queue with:

Method Effect
speechSynthesis.speak(u) Add an utterance to the queue
speechSynthesis.cancel() Stop everything and clear the queue
speechSynthesis.pause() / resume() Pause and continue the current speech
speechSynthesis.speaking / pending / paused Read-only state flags

Most browsers require a user gesture before they speak, so call speak() from a click handler.

Make the browser speak

If you hear nothing, the sandbox or your system may have no voices or may block audio. The status line still reports what happened, which is why the example listens to the start, end and error events.

Choosing a voice

Voices come from the operating system and browser, so the list differs from device to device. speechSynthesis.getVoices() returns them, but the list often loads asynchronously: it can be empty on the first call. Listen for the voiceschanged event.

List the available voices

Each SpeechSynthesisVoice has name, lang (a BCP 47 tag like en-GB), localService (installed on the device or streamed from a server) and default. When you do not pick a voice, set utterance.lang so the browser chooses a matching voice. A French sentence read with an English voice sounds like a joke.

Useful events

Besides start, end and error, an utterance fires boundary as it passes each word (in browsers that support it). The event gives charIndex, the position in the text, which lets you highlight the word being read.

JavaScript
utterance.addEventListener("boundary", (event) => {
  if (event.name === "word") {
    highlight(event.charIndex); // wrap the word at that index in <mark>
  }
});

Support is uneven, so treat highlighting as an enhancement, not as the only way to follow the text.

Known quirks

  • Long text (hundreds of words) can be cut off in some browsers. Split it into sentences and queue several utterances.
  • Calling speak() repeatedly queues speech. Call cancel() first if you want the new text to replace the old.
  • Speech stops when the page is closed or navigated away; call cancel() in your cleanup code.

Speech recognition

SpeechRecognition (prefixed webkitSpeechRecognition in Chromium and Safari) turns microphone audio into text. Support is limited, results often come from a remote service, and Firefox has not shipped it, so always feature-detect and provide a keyboard fallback.

The following code is read-only here because it needs microphone permission and a network service that the sandboxed preview cannot offer, but this is the whole pattern:

JavaScript
const Recognition = window.SpeechRecognition || window.webkitSpeechRecognition;

if (!Recognition) {
  showMessage("Speech recognition is not available. Please type instead.");
} else {
  const recognition = new Recognition();
  recognition.lang = "en-US";
  recognition.interimResults = true;   // show partial text while the user speaks
  recognition.continuous = false;      // stop after one phrase
  recognition.maxAlternatives = 1;

  recognition.addEventListener("result", (event) => {
    let transcript = "";
    for (const result of event.results) {
      transcript += result[0].transcript;
    }
    output.textContent = transcript;
  });

  recognition.addEventListener("error", (event) => {
    // "not-allowed", "no-speech", "network", "audio-capture", ...
    showMessage("Speech recognition error: " + event.error);
  });

  recognition.addEventListener("end", () => button.textContent = "Start listening");

  button.addEventListener("click", () => recognition.start());
}

Key points:

  • start() needs a user gesture and triggers the microphone permission prompt (see Camera, Microphone and MediaRecorder).
  • Results arrive as a list. Each result holds one or more alternatives with a transcript and a confidence between 0 and 1. With interimResults you get live, changing results followed by a final one (result.isFinal).
  • Common errors: not-allowed (permission denied), no-speech (silence), network (the remote service failed) and audio-capture (no microphone).
  • Recognition ends by itself after a pause. Restart it from the end event if you want continuous dictation.
  • Privacy: audio may leave the device. Tell users, never start listening silently, and do not use it for passwords or other secrets.

You can build a simple voice command layer by matching the transcript against a small list of phrases, but keep every command available through ordinary buttons too.

Designing speech features

  • Make speech opt-in, with an obvious play/stop button. Never autoplay speech on page load.
  • Provide the text alongside the audio, for example the article text next to a "Listen" button.
  • Let users change rate and voice, and remember their choice in Web Storage.
  • Check support ("speechSynthesis" in window) and hide the button if missing.
  • Test on real devices: voice lists, quality and quirks vary widely between systems.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which statement about browser speech APIs is correct?

    speechSynthesis works in all major browsers using local voices. SpeechRecognition is limited and typically sends audio to a server.
  2. 2. Why does speechSynthesis.getVoices() sometimes return an empty array on the first call?

    In several browsers the voice list is populated after load. Re-read it when voiceschanged fires.
  3. 3. What is a good reason to set utterance.lang?

    Without a matching voice or language tag, text may be read with the wrong pronunciation.
  4. 4. What should you do before relying on SpeechRecognition?

    Support varies, a microphone permission is required, and audio may leave the device, so it needs detection, a gesture and a fallback.

Summary

  • speechSynthesis plus SpeechSynthesisUtterance speak text; control rate, pitch, volume, lang and voice, and manage the queue with cancel, pause and resume.
  • getVoices() may fill in late: listen for voiceschanged, and use start, end, error and boundary events for feedback.
  • SpeechRecognition (often prefixed) converts speech to text with interim and final results, but needs permission, a user gesture, a feature check and often a network.
  • Keep speech opt-in, give a text alternative and remember it is not a replacement for accessible HTML.
  • Be transparent about microphone use and where audio goes.

Next lesson: Accessibility Basics, where you make sure everything you build works for every visitor, whatever device or ability they have.