sodcalculator

10 Tech How-To

Prototype a Browser Voice Tutor & Debug Silence

Guide 10-51694 · Updated · Step by step

This guide shows you how to build a working voice tutor in the browser using the Web Speech API, and how to systematically debug the most common issue: silence. You’ll create a page that listens to the user, checks their answer against a target phrase, and speaks feedback. You’ll need basic HTML, CSS, and JavaScript knowledge, plus a browser that supports the Web Speech API (Chrome, Edge, or Safari).

What You’ll Need

  • A code editor (VS Code, Sublime, or even Notepad)
  • A modern browser: Chrome, Edge, or Safari (Firefox has limited support)
  • A microphone that works (test it in your OS settings first)
  • A local web server (optional but recommended; you can use a simple Python server or VS Code’s Live Server extension)

Step-by-Step

  1. Create the HTML structure. Make a new file called voice-tutor.html. Add a button to start listening, a text area to show the transcript, and a div for the tutor’s spoken feedback. Wrap the script at the bottom of the body.
  2. Set up the speech recognition object. In your script, check if window.SpeechRecognition or window.webkitSpeechRecognition exists. Create an instance and set its properties: recognition.lang = 'en-US', recognition.interimResults = false, and recognition.maxAlternatives = 1.
  3. Define the target phrase and feedback function. Store a target string, e.g., const target = "The mitochondria is the powerhouse of the cell". Write a function checkAnswer(transcript) that compares the transcript to the target (case-insensitive, trim whitespace). If they match, speak “Correct!”; otherwise, speak “Try again. The phrase is …” and show the transcript on screen.
  4. Add event handlers for recognition. Attach onresult to get the transcript from event.results[0][0].transcript. Attach onerror to handle errors (we’ll cover common ones in Troubleshooting). Attach onend to reset the button state.
  5. Create the speech synthesis function. Use window.speechSynthesis. Create a SpeechSynthesisUtterance with the feedback text, set utterance.lang = 'en-US', and call speechSynthesis.speak(utterance). Optionally, pick a voice that’s not the default for more natural sound.
  6. Wire up the start button. On click, call recognition.start(). Disable the button while listening and re-enable it in the onend handler.
  7. Test in a browser. Open the file (or serve it via local server). Click the button, speak the target phrase, and see if you get feedback. If you hear nothing, proceed to the debugging steps below.

Common Mistakes

  • Not checking for browser support. Firefox and some older browsers don’t support SpeechRecognition. Always check and show a message if unsupported.
  • Forgetting to set the language. If you don’t set lang, the recognition may use the browser’s default, which might not match the user’s accent or the target phrase.
  • Using interimResults = true and not handling it. Interim results come in chunks and can be confusing. Keep it false for simplicity.
  • Not handling the onerror event. If an error occurs (like ‘no-speech’), the recognition stops silently. Always log and display an error message.
  • Not calling speechSynthesis.cancel() before speaking. If the user speaks again while the tutor is still talking, the audio overlaps. Cancel any ongoing speech first.

Tips

  • Use a local server. Some browsers restrict microphone access on file:// URLs. Use a simple server like python -m http.server in the same folder.
  • Test with different browsers. Chrome and Edge handle speech recognition differently; test on both to see which works best for your use case.
  • Add a visual indicator. Show a pulsing red dot or “Listening…” text while recognition is active. This helps users know when to speak.
  • Preprocess the transcript. Remove punctuation and extra spaces before comparing. Use transcript.toLowerCase().replace(/[^a-z0-9\s]/g, '').
  • Handle the case where the user says nothing. Set a timeout to stop recognition after 5 seconds of silence and prompt them to try again.

Troubleshooting

Silence: no recognition at all. First, check the browser console for errors. If you see “not-allowed”, the microphone permission is blocked. Go to the site settings and allow microphone access. If you’re on file://, switch to a local server. Also, ensure the microphone is working in another app.

Silence: recognition works but no speech output. Check if speechSynthesis is available. In some browsers, it requires a user gesture (like a click) before it will speak. Make sure you call speak() inside the click handler or after a user interaction. Also, some browsers have a bug where speechSynthesis doesn’t work if the tab is not focused. Click on the page first.

Silence: only some phrases are recognized. The recognition engine may have trouble with uncommon words or accents. Try simplifying the target phrase or provide a hint on screen. Also, check that the lang matches the user’s microphone language.

Error: ‘no-speech’ or ‘audio-capture’. This means the browser didn’t hear anything. Ask the user to speak louder, move closer to the mic, or check the mic level in the OS. Also, make sure no other app is using the mic.

Error: ‘network’. Speech recognition in Chrome uses Google’s servers. If you’re offline or behind a strict firewall, it may fail. Try a different network or use a fallback that just does text input.

Error: ‘service-not-allowed’. The browser may block the service if the page isn’t secure (HTTPS). Use a localhost server or deploy to a HTTPS site.

Frequently Asked Questions

Why does my microphone not work in Firefox?

Firefox does not support the Web Speech API for recognition. You’ll need to use a third-party service or ask users to use Chrome/Edge.

Can I use this offline?

Speech recognition in Chrome requires an internet connection because it processes audio on Google’s servers. Speech synthesis, however, often works offline with built-in voices.

How do I change the voice of the tutor?

Use speechSynthesis.getVoices() to get a list, then find a voice that matches your desired language and set utterance.voice = voice. Note that voices load asynchronously; listen for the voiceschanged event.

Why does the recognition stop after a few seconds of silence?

By default, the browser stops listening if it doesn’t hear speech for a while. You can adjust recognition.continuous = true to keep it running, but then you’ll need to handle multiple results.

Can I make the tutor speak before the user speaks?

Yes, just call speak() with a prompt like “Please say the phrase” before starting recognition. This is a good way to guide the user.

What if the user speaks a different dialect or accent?

Set recognition.lang to a more specific locale like ‘en-US’ or ‘en-GB’ to improve accuracy. You can also offer a language selector in the UI.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →