SpeechRecognition: available() static method
The available() static method of the SpeechRecognition interface checks whether the specified languages are available for speech recognition at the given quality level.
To install the language packs needed for on-device speech recognition of those languages, use the SpeechRecognition.install() method.
A language pack is the data a browser needs to recognize speech in a particular language.
Access to the available() method is controlled by the on-device-speech-recognition Permissions-Policy directive.
If a policy blocks access, the promise returned by available() resolves to unavailable.
Syntax
available(options)
Parameters
options-
An object specifying options for the availability check. Possible properties include:
langs-
An array of one or more strings containing BCP 47 language tags, each representing a language to check for availability. If
langsis an empty array, the promise resolves tounavailable. See Browser compatibility for browser-specific differences. qualityOptional-
An enumerated value that indicates the approximate use case of your speech recognition app, and therefore the required level of complexity of the language pack and speech recognition service. Possible values are:
command-
Level 1: Short isolated phrases with limited vocabulary and a single speaker. Use cases include voice commands for apps. This is the default value.
dictation-
Level 2: Continuous speech with moderate background noise and a single primary speaker. Use cases include dictating long-form text inputs such as SMS messages, email bodies, or strings for translation.
conversation-
Level 3: Continuous speech with complex vocabulary, high background noise, and multiple primary speakers. Use cases include transcribing meetings and continuous live captioning.
processLocallyOptional-
A boolean that specifies whether to check availability of the languages only for on-device speech recognition (
true) or for on-device or remote speech recognition (false). The default value isfalse.Note: It is not possible to use
available()to guarantee that a remote service supports the specified languages. A value offalsemeans that either an on-device or a remote speech recognition service supports them.
Return value
A Promise that resolves with an enumerated value indicating the availability of the specified languages for speech recognition.
Possible values include:
available-
Indicates that all the specified languages are supported at the given
qualitylevel.- If
processLocallyis set totrue,availablemeans that speech recognition is available for those languages on-device (the required language packs have been downloaded and installed on the user's device). - If
processLocallyis set tofalse,availablemeans that speech recognition is available for those languages either on-device or remotely.
- If
downloading-
Indicates that all the specified languages are supported at the given
qualitylevel for on-device processing, and that the relevant language pack for at least one language is in the process of being downloaded. Only relevant whenprocessLocallyistrue. downloadable-
Indicates that support for the specified languages is available on-device, at the specified
qualitylevel, but the relevant language pack for at least one language has not yet been downloaded, or the site hasn't yet calledinstall()for it (see the following note). Only relevant whenprocessLocallyistrue. -
Indicates that at least one of the specified languages is not supported at the given
qualitylevel.- If
processLocallyis set totrue,unavailablemeans that on-device speech recognition is not available for at least one of the specified languages. - If
processLocallyis set tofalse,unavailablemeans that speech recognition is not available for at least one of the specified languages either on-device or remotely.
- If
Note:
To protect user privacy, browsers hide whether a language pack is already on the user's device until the site has called install() for that language.
Until then, available() returns downloadable instead of available or downloading, even if the language pack is installed or downloading.
Calling install() for a language pack that's already installed doesn't download it again, and later calls to available() return its true status.
Final return value for multiple languages with different statuses
Only one status value is returned, even if multiple languages are specified in the langs array.
If the specified languages have different availability statuses, the final return value is the status furthest from available among those languages.
The following lists show how the final status is chosen, checking each rule in order:
If processLocally is false:
- If all languages are
available, returnavailable. - Otherwise, return
unavailable.
If processLocally is true:
- If at least one language is
unavailable, returnunavailable. - Otherwise, if at least one language is
downloadable, returndownloadable. - Otherwise, if at least one language is
downloading, returndownloading. - Otherwise, return
available.
Exceptions
InvalidStateErrorDOMException-
The current document is not fully active.
SyntaxErrorDOMException-
One or more of the strings specified in
langsaren't valid BCP 47 language tags.
Examples
>Checking on-device availability and installing language packs
For on-device speech recognition to work, the browser must have a language pack installed for the language you want to recognize.
If you call start() after setting processLocally to true but the correct language pack isn't installed, recognition fails and an error event fires with a service-not-allowed error code.
To install the correct language pack, follow these two steps:
- Use the
available()method to check whether the language pack is installed on the user's device. - If it isn't installed, use the
SpeechRecognition.install()method to install it.
These steps are handled using the following code snippet:
startBtn.addEventListener("click", () => {
// Check availability of target language
SpeechRecognition.available({ langs: ["en-US"], processLocally: true }).then(
(result) => {
if (result === "unavailable") {
diagnostic.textContent = `en-US not available to download at this time. Sorry!`;
} else if (result === "available") {
recognition.start();
console.log("Ready to receive a color command.");
} else {
diagnostic.textContent = `en-US language pack downloading`;
SpeechRecognition.install({
langs: ["en-US"],
processLocally: true,
}).then((result) => {
if (result) {
diagnostic.textContent = `en-US language pack downloaded. Try again.`;
} else {
diagnostic.textContent = `en-US language pack failed to download. Try again later.`;
}
});
}
},
);
});
We first run the available() method, specifying one language (langs: ["en-US"]) to check availability for, and processLocally: true. We test for three different possibilities of the return value:
- If the resulting value is
unavailable, it means that no suitable language pack is available to download. We also print an appropriate message to the output. - If the resulting value is
available, it means that the language pack is available locally, so recognition can begin. In this case, we runstart()and log a message to the console when the app is ready to receive speech. - If the value is something else (
downloadableordownloading), we print a diagnostic message to inform the user that a language pack download is starting, then run theinstall()method to handle the download.
The install() method starts the en-US language pack downloading and returns a Promise that resolves with a boolean indicating whether the specified language packs were downloaded and installed successfully (true) or not (false).
This code is excerpted from our on-device speech color changer (run the demo live). See Using the Web Speech API for a full explanation.
Checking on-device model capabilities
The following code snippet modifies the previous example.
It calls available() with the quality option set to dictation, to check whether on-device recognition supports this quality level.
If the result is unavailable, we set the SpeechRecognition object's processLocally property to false (assuming it was previously true), which allows the browser to use a remote recognition service if it has one, and then call start().
If the result is available, we call start() to begin on-device recognition.
If the result is any other value, we call install() with the quality option set to dictation to install the required language packs.
startBtn.addEventListener("click", () => {
// Check availability of on-device target language dictation quality
SpeechRecognition.available({
langs: ["en-US"],
processLocally: true,
quality: "dictation",
}).then((result) => {
if (result === "unavailable") {
diagnostic.textContent = `On-device recognition for dictation not available. Falling back to any available recognition service.`;
recognition.processLocally = false;
recognition.start();
} else if (result === "available") {
recognition.start();
console.log("Ready to receive a color command.");
} else {
diagnostic.textContent = `en-US language pack downloading`;
SpeechRecognition.install({
langs: ["en-US"],
processLocally: true,
quality: "dictation",
}).then((result) => {
if (result) {
diagnostic.textContent = `en-US language pack downloaded. Try again.`;
} else {
diagnostic.textContent = `en-US language pack failed to download. Try again later.`;
}
});
}
});
});
Specifications
| Specification |
|---|
| Web Speech API> # dom-speechrecognition-available> |