Getting started with the Speech Recognition API in Javascript

The JavaScript API Speech Recognition enables web developers to incorporate speech recognition into your web page. This API allows fine control and flexibility over the speech recognition capabilities in Chrome version 25 and later. This API is experimental, that means that it's not available on every browser. Even in Chrome, there are some attributes of the API that aren't supported. For more information visit Can I Use Speech Recognition.

In this article you will learn how to use the Speech Recognition API, in its most basic expression.

Implementation

To get started, you will need to know wheter the browser supports the API or not. To do this, you can verify if the window object in the browser has the webkitSpeechRecognition property using any of the following snippets:

if (!('webkitSpeechRecognition' in window)) {
    alert("Unable to use the Speech Recognition API");
}

// Or

if (!window.hasOwnProperty("webkitSpeechRecognition")) {
    alert("Unable to use the Speech Recognition API");
}

// Or

if(typeof(webkitSpeechRecognition) != "function"){
    alert("Unable to use the Speech Recognition API");
}

Once you verify, you can start to work with this API. Create a new instance of the webkitSpeechRecognition class and set the basic properties:

// Create a new instance of SpeechRecognition
var recognition = new webkitSpeechRecognition();
// Define whether continuous results are returned for each recognition
// or only a single result. Defaults to false
recognition.continuous = true;
// Controls whether interim results should be returned 
// Interim results are results that are not yet final 
// (e.g. the SpeechRecognitionResult.isFinal property is false.)
recognition.interimResults = true;
// Returns and sets the language of the current SpeechRecognition. 
// If not specified, this defaults to the HTML lang attribute value
// or the user agent's language setting if that isn't set either.
// There are a lot of supported languages (go to supported languages at the end of the article)
recognition.lang = "en-US";

Now that the basic options are set, you will need to add some event handlers. In this case we are going add the basic listeners as onerror, onstart , onend and onresult (event used to retrieve the recognized text).

onerror

// Fired when an error happens with the speech recognition
// With all the following erro codes:
// info-blocked
// info-denied
// no-speech
// aborted
// audio-capture
// network
// not-allowed
// service-not-allowed
// bad-grammar
// language-not-supported
// recognition_overlap 
recognition.onerror = function(event) {
    console.error(event);
};

onstart

// will run when the speech recognition 
// service has began listening to incoming audio 
recognition.onstart = function() {
    console.log('Speech recognition service has started');
};

onend

// run when the speech recognition service has disconnected
// (automatically or forced with recognition.stop())
recognition.onend = function() {
    console.log('Speech recognition service disconnected');
};

onresult

// This event is triggered when the speech recognition service
// returns a result — a word or phrase has been positively 
//recognized and this has been communicated back to your app
recognition.onresult = function(event) {
    var interim_transcript = '';
    var final_transcript = '';

    for (var i = event.resultIndex; i < event.results.length; ++i) {
        // Verify if the recognized text is the last with the isFinal property
        if (event.results[i].isFinal) {
            final_transcript += event.results[i][0].transcript;
        } else {
            interim_transcript += event.results[i][0].transcript;
        }
    }

    // Choose which result may be useful for you

    console.log("Interim: ", interim_transcript);

    console.log("Final: ",final_transcript);

    console.log("Simple: ", event.results[0][0].transcript);
};

The onresult event receives as first parameter a custom even object. The results are stored in the event.results property (an object of type SpeechRecognitionResultList that stores the SpeechRecognitionResult objects, this in turn contains instances of SpeechRecognitionAlternative with the transcript property that contains the text).

As the final step, you need to start it by executing the start method of the recognition object or to stop it once it's running executing the stop method:

// start the speech recognition
recognition.start();

// Stop the speech recognition
recognition.stop();

Now the entire functional snippet to use the speech recognition API should look like:

var recognition = new webkitSpeechRecognition();
recognition.continuous = true;
recognition.interimResults = true;
recognition.lang = "en-US";

recognition.onerror = function(event) {
    console.error(event);
};

recognition.onstart = function() {
    console.log('Speech recognition service has started');
};

recognition.onend = function() {
    console.log('Speech recognition service disconnected');
};

recognition.onresult = function(event) {
    var interim_transcript = '';
    var final_transcript = '';

    for (var i = event.resultIndex; i < event.results.length; ++i) {
        // Verify if the recognized text is the last with the isFinal property
        if (event.results[i].isFinal) {
            final_transcript += event.results[i][0].transcript;
        } else {
            interim_transcript += event.results[i][0].transcript;
        }
    }

    // Choose which result may be useful for you

    console.log("Interim: ", interim_transcript);

    console.log("Final: ",final_transcript);

    console.log("Simple: ", event.results[0][0].transcript);
};

recognition.start();

Once you execute the start method, the microphone permission dialog will be shown in the Browser.

Go ahead and test it in your web or local server. You can see a live demo of the Speech Recognition API working in the browser in all the available languages from the official Chrome Demos here.

Supported languages

Currently, the API supports 40 languages in Chrome. Some languages have specifical codes according to the region (the identifiers follow the BCP-47 format):

You can use the following object if you need the previous table in Javascript and you can iterate it as shown in the example:

var allAvailableLanguages = [
    {
        "language": "Afrikaans",
        "countryCodes": [
            {
                "langCode": "af-ZA",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Bahasa Indonesia",
        "countryCodes": [
            {
                "langCode": "id-ID",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Bahasa Melayu",
        "countryCodes": [
            {
                "langCode": "ms-MY",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Català",
        "countryCodes": [
            {
                "langCode": "ca-ES",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Čeština",
        "countryCodes": [
            {
                "langCode": "cs-CZ",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Dansk",
        "countryCodes": [
            {
                "langCode": "da-DK",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Deutsch",
        "countryCodes": [
            {
                "langCode": "de-DE",
                "country": "Default"
            }
        ]
    },
    {
        "language": "English",
        "countryCodes": [
            {
                "langCode": "en-AU",
                "country": "Australia"
            },
            {
                "langCode": "en-CA",
                "country": "Canada"
            },
            {
                "langCode": "en-IN",
                "country": "India"
            },
            {
                "langCode": "en-NZ",
                "country": "New Zealand"
            },
            {
                "langCode": "en-ZA",
                "country": "South Africa"
            },
            {
                "langCode": "en-GB",
                "country": "United Kingdom"
            },
            {
                "langCode": "en-US",
                "country": "United States"
            }
        ]
    },
    {
        "language": "Español",
        "countryCodes": [
            {
                "langCode": "es-AR",
                "country": "Argentina"
            },
            {
                "langCode": "es-BO",
                "country": "Bolivia"
            },
            {
                "langCode": "es-CL",
                "country": "Chile"
            },
            {
                "langCode": "es-CO",
                "country": "Colombia"
            },
            {
                "langCode": "es-CR",
                "country": "Costa Rica"
            },
            {
                "langCode": "es-EC",
                "country": "Ecuador"
            },
            {
                "langCode": "es-SV",
                "country": "El Salvador"
            },
            {
                "langCode": "es-ES",
                "country": "España"
            },
            {
                "langCode": "es-US",
                "country": "Estados Unidos"
            },
            {
                "langCode": "es-GT",
                "country": "Guatemala"
            },
            {
                "langCode": "es-HN",
                "country": "Honduras"
            },
            {
                "langCode": "es-MX",
                "country": "México"
            },
            {
                "langCode": "es-NI",
                "country": "Nicaragua"
            },
            {
                "langCode": "es-PA",
                "country": "Panamá"
            },
            {
                "langCode": "es-PY",
                "country": "Paraguay"
            },
            {
                "langCode": "es-PE",
                "country": "Perú"
            },
            {
                "langCode": "es-PR",
                "country": "Puerto Rico"
            },
            {
                "langCode": "es-DO",
                "country": "República Dominicana"
            },
            {
                "langCode": "es-UY",
                "country": "Uruguay"
            },
            {
                "langCode": "es-VE",
                "country": "Venezuela"
            }
        ]
    },
    {
        "language": "Euskara",
        "countryCodes": [
            {
                "langCode": "eu-ES",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Filipino",
        "countryCodes": [
            {
                "langCode": "fil-PH",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Français",
        "countryCodes": [
            {
                "langCode": "fr-FR",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Galego",
        "countryCodes": [
            {
                "langCode": "gl-ES",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Hrvatski",
        "countryCodes": [
            {
                "langCode": "hr_HR",
                "country": "Default"
            }
        ]
    },
    {
        "language": "IsiZulu",
        "countryCodes": [
            {
                "langCode": "zu-ZA",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Íslenska",
        "countryCodes": [
            {
                "langCode": "is-IS",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Italiano",
        "countryCodes": [
            {
                "langCode": "it-IT",
                "country": "Italia"
            },
            {
                "langCode": "it-CH",
                "country": "Svizzera"
            }
        ]
    },
    {
        "language": "Lietuvių",
        "countryCodes": [
            {
                "langCode": "lt-LT",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Magyar",
        "countryCodes": [
            {
                "langCode": "hu-HU",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Nederlands",
        "countryCodes": [
            {
                "langCode": "nl-NL",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Norsk bokmål",
        "countryCodes": [
            {
                "langCode": "nb-NO",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Polski",
        "countryCodes": [
            {
                "langCode": "pl-PL",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Português",
        "countryCodes": [
            {
                "langCode": "pt-BR",
                "country": "Brasil"
            },
            {
                "langCode": "pt-PT",
                "country": "Portugal"
            }
        ]
    },
    {
        "language": "Română",
        "countryCodes": [
            {
                "langCode": "ro-RO",
                "country": "Default"
            }
        ]
    },
    {
        "language": "SlovenšÄina",
        "countryCodes": [
            {
                "langCode": "sl-SI",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Slovenčina",
        "countryCodes": [
            {
                "langCode": "sk-SK",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Suomi",
        "countryCodes": [
            {
                "langCode": "fi-FI",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Svenska",
        "countryCodes": [
            {
                "langCode": "sv-SE",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Tiếng Việt",
        "countryCodes": [
            {
                "langCode": "vi-VN",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Türkçe",
        "countryCodes": [
            {
                "langCode": "tr-TR",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Ελληνικά",
        "countryCodes": [
            {
                "langCode": "el-GR",
                "country": "Default"
            }
        ]
    },
    {
        "language": "български",
        "countryCodes": [
            {
                "langCode": "bg-BG",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Pусский",
        "countryCodes": [
            {
                "langCode": "ru-RU",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Српски",
        "countryCodes": [
            {
                "langCode": "sr-RS",
                "country": "Default"
            }
        ]
    },
    {
        "language": "Українська",
        "countryCodes": [
            {
                "langCode": "uk-UA",
                "country": "Default"
            }
        ]
    },
    {
        "language": "한국어",
        "countryCodes": [
            {
                "langCode": "ko-KR",
                "country": "Default"
            }
        ]
    },
    {
        "language": "中文",
        "countryCodes": [
            {
                "langCode": "cmn-Hans-CN",
                "country": "普通话 (中国大陆)"
            },
            {
                "langCode": "cmn-Hans-HK",
                "country": "普通话 (香港)"
            },
            {
                "langCode": "cmn-Hant-TW",
                "country": "中文 (台灣)"
            },
            {
                "langCode": "yue-Hant-HK",
                "country": "粵語 (香港)"
            }
        ]
    },
    {
        "language": "日本語",
        "countryCodes": [
            {
                "langCode": "ja-JP",
                "country": "Default"
            }
        ]
    },
    {
        "language": "हिन्दी",
        "countryCodes": [
            {
                "langCode": "hi-IN",
                "country": "Default"
            }
        ]
    },
    {
        "language": "ภาษาไทย",
        "countryCodes": [
            {
                "langCode": "th-TH",
                "country": "Default"
            }
        ]
    }
];

allAvailableLanguages.forEach(function(item){
    if(item.countryCodes.length > 1){
        var allCountries = "";
        console.log(item.language + " ("+item.countryCodes.length+" country(s)) ");
        
        item.countryCodes.forEach(function(countryItem){
            console.log("   "+countryItem.country + " | "+ countryItem.langCode); 
        });
        
    }else{
        console.log(item.language + " ["+item.countryCodes[0].langCode+"]");
    }
});

Whose output in the console will be:

// Afrikaans [af-ZA]
// Bahasa Indonesia [id-ID]
// Bahasa Melayu [ms-MY]
// Català [ca-ES]
// Čeština [cs-CZ]
// Dansk [da-DK]
// Deutsch [de-DE]
// English (7 country(s)) 
//     Australia | en-AU
//     Canada | en-CA
//     India | en-IN
//     New Zealand | en-NZ
//     South Africa | en-ZA
//     United Kingdom | en-GB
//     United States | en-US
// Español (20 country(s)) 
//     Argentina | es-AR
//     Bolivia | es-BO
//     Chile | es-CL
//     Colombia | es-CO
//     Costa Rica | es-CR
//     Ecuador | es-EC
//     El Salvador | es-SV
//     España | es-ES
//     Estados Unidos | es-US
//     Guatemala | es-GT
//     Honduras | es-HN
//     México | es-MX
//     Nicaragua | es-NI
//     Panamá | es-PA
//     Paraguay | es-PY
//     Perú | es-PE
//     Puerto Rico | es-PR
//     República Dominicana | es-DO
//     Uruguay | es-UY
//     Venezuela | es-VE
// Euskara [eu-ES]
// Filipino [fil-PH]
// Français [fr-FR]
// Galego [gl-ES]
// Hrvatski [hr_HR]
// IsiZulu [zu-ZA]
// Íslenska [is-IS]
// Italiano (2 country(s)) 
//     Italia | it-IT
//     Svizzera | it-CH
// Lietuvių [lt-LT]
// Magyar [hu-HU]
// Nederlands [nl-NL]
// Norsk bokmål [nb-NO]
// Polski [pl-PL]
// Português (2 country(s)) 
//     Brasil | pt-BR
//     Portugal | pt-PT
// Română [ro-RO]
// SlovenšÄina [sl-SI]
// Slovenčina [sk-SK]
// Suomi [fi-FI]
// Svenska [sv-SE]
// Tiếng Việt [vi-VN]
// Türkçe [tr-TR]
// Ελληνικά [el-GR]
// български [bg-BG]
// Pусский [ru-RU]
// Српски [sr-RS]
// Українська [uk-UA]
// 한국어 [ko-KR]
// 中文 (4 country(s)) 
//     普通话 (中国大陆) | cmn-Hans-CN
//     普通话 (香港) | cmn-Hans-HK
//     中文 (台灣) | cmn-Hant-TW
//     粵語 (香港) | yue-Hant-HK
// 日本語 [ja-JP]
// हिन्दी [hi-IN]
// ภาษาไทย [th-TH]

Happy coding !