diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt index a0eb5cf6675dbce..d75cd8d41b9e3c3 100644 --- a/files/en-us/_redirects.txt +++ b/files/en-us/_redirects.txt @@ -10322,6 +10322,8 @@ /en-US/docs/Web/API/SpeechRecognitionError/message /en-US/docs/Web/API/SpeechRecognitionErrorEvent/message /en-US/docs/Web/API/SpeechRecognitionEvent/SpeechRecognitionEvent.resultIndex /en-US/docs/Web/API/SpeechRecognitionEvent/resultIndex /en-US/docs/Web/API/SpeechRecognitionEvent/SpeechRecognitionEvent.results /en-US/docs/Web/API/SpeechRecognitionEvent/results +/en-US/docs/Web/API/SpeechRecognitionEvent/emma /en-US/docs/Web/API/SpeechRecognitionEvent +/en-US/docs/Web/API/SpeechRecognitionEvent/interpretation /en-US/docs/Web/API/SpeechRecognitionEvent /en-US/docs/Web/API/SpeechSynthesis/SpeechSynthesis.cancel /en-US/docs/Web/API/SpeechSynthesis/cancel /en-US/docs/Web/API/SpeechSynthesis/onvoiceschanged /en-US/docs/Web/API/SpeechSynthesis/voiceschanged_event /en-US/docs/Web/API/SpeechSynthesisUtterance/onboundary /en-US/docs/Web/API/SpeechSynthesisUtterance/boundary_event diff --git a/files/en-us/_wikihistory.json b/files/en-us/_wikihistory.json index 0dd57726b6bc56f..5e8f33084b617f2 100644 --- a/files/en-us/_wikihistory.json +++ b/files/en-us/_wikihistory.json @@ -58699,14 +58699,6 @@ "modified": "2020-10-15T21:40:31.633Z", "contributors": ["Sheppy", "lucian95", "sgiles", "chrisdavidmills"] }, - "Web/API/SpeechRecognitionEvent/emma": { - "modified": "2020-10-15T21:40:30.616Z", - "contributors": ["sideshowbarker", "ExE-Boss", "chrisdavidmills"] - }, - "Web/API/SpeechRecognitionEvent/interpretation": { - "modified": "2020-10-15T21:40:31.763Z", - "contributors": ["sideshowbarker", "ExE-Boss", "chrisdavidmills"] - }, "Web/API/SpeechRecognitionEvent/resultIndex": { "modified": "2020-10-15T21:40:31.951Z", "contributors": ["sideshowbarker", "ExE-Boss", "chrisdavidmills"] diff --git a/files/en-us/web/api/speechgrammar/index.md b/files/en-us/web/api/speechgrammar/index.md index 770900c96907c97..fb9d340695dfeac 100644 --- a/files/en-us/web/api/speechgrammar/index.md +++ b/files/en-us/web/api/speechgrammar/index.md @@ -9,9 +9,12 @@ browser-compat: api.SpeechGrammar {{APIRef("Web Speech API")}}{{deprecated_header}} -The **`SpeechGrammar`** interface of the [Web Speech API](/en-US/docs/Web/API/Web_Speech_API) represents a set of words or patterns of words that we want the recognition service to recognize. +The **`SpeechGrammar`** interface of the [Web Speech API](/en-US/docs/Web/API/Web_Speech_API) represents a set of words or patterns of words for the recognition service to recognize. -Grammar is defined using [JSpeech Grammar Format](https://www.w3.org/TR/jsgf/) (**JSGF**.) Other formats may also be supported in the future. +Grammar is defined using [JSpeech Grammar Format](https://www.w3.org/TR/jsgf/) (**JSGF**). + +> [!NOTE] +> The concept of grammar has been removed from the Web Speech API. Related features remain in the specification and are still recognized by supporting browsers for backwards compatibility, but they have no effect on speech recognition services. ## Constructor diff --git a/files/en-us/web/api/speechgrammar/speechgrammar/index.md b/files/en-us/web/api/speechgrammar/speechgrammar/index.md index 170817b20153d46..245d62c1799fd81 100644 --- a/files/en-us/web/api/speechgrammar/speechgrammar/index.md +++ b/files/en-us/web/api/speechgrammar/speechgrammar/index.md @@ -25,22 +25,6 @@ new SpeechGrammar() None. -## Examples - -```js -const grammar = - "#JSGF V1.0; grammar colors; public = aqua | azure | beige | bisque | black | blue | brown | chocolate | coral | crimson | cyan | fuchsia | ghostwhite | gold | goldenrod | gray | green | indigo | ivory | khaki | lavender | lime | linen | magenta | maroon | moccasin | navy | olive | orange | orchid | peru | pink | plum | purple | red | salmon | sienna | silver | snow | tan | teal | thistle | tomato | turquoise | violet | white | yellow ;"; -const recognition = new SpeechRecognition(); -const speechRecognitionList = new SpeechGrammarList(); -speechRecognitionList.addFromString(grammar, 1); -recognition.grammars = speechRecognitionList; - -const newGrammar = new SpeechGrammar(); -newGrammar.src = - "#JSGF V1.0; grammar names; public = chris | kirsty | mike;"; -speechRecognitionList[1] = newGrammar; // should add the new SpeechGrammar object to the list -``` - ## Specifications This API has no official W3C or WHATWG specification. diff --git a/files/en-us/web/api/speechgrammar/src/index.md b/files/en-us/web/api/speechgrammar/src/index.md index ca9a3cbb2f7069a..ad079ddd853dec8 100644 --- a/files/en-us/web/api/speechgrammar/src/index.md +++ b/files/en-us/web/api/speechgrammar/src/index.md @@ -17,20 +17,6 @@ is used to get or set a string that contains the grammar within the `SpeechGramm A string representing the grammar. -## Examples - -```js -const grammar = - "#JSGF V1.0; grammar colors; public = aqua | azure | beige | bisque | black | blue | brown | chocolate | coral | crimson | cyan | fuchsia | ghostwhite | gold | goldenrod | gray | green | indigo | ivory | khaki | lavender | lime | linen | magenta | maroon | moccasin | navy | olive | orange | orchid | peru | pink | plum | purple | red | salmon | sienna | silver | snow | tan | teal | thistle | tomato | turquoise | violet | white | yellow ;"; -const recognition = new SpeechRecognition(); -const speechRecognitionList = new SpeechGrammarList(); -speechRecognitionList.addFromString(grammar, 1); -recognition.grammars = speechRecognitionList; - -console.log(speechRecognitionList[0].src); // should return the same as the contents of the grammar variable -console.log(speechRecognitionList[0].weight); // should return 1 - the same as the weight set in addFromString. -``` - ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/speechgrammar/weight/index.md b/files/en-us/web/api/speechgrammar/weight/index.md index fcf2697d28c681e..b4163a4291d9108 100644 --- a/files/en-us/web/api/speechgrammar/weight/index.md +++ b/files/en-us/web/api/speechgrammar/weight/index.md @@ -18,20 +18,6 @@ The optional **`weight`** property of the A float representing the weight of the grammar, in the range 0.0–1.0. -## Examples - -```js -const grammar = - "#JSGF V1.0; grammar colors; public = aqua | azure | beige | bisque | black | blue | brown | chocolate | coral | crimson | cyan | fuchsia | ghostwhite | gold | goldenrod | gray | green | indigo | ivory | khaki | lavender | lime | linen | magenta | maroon | moccasin | navy | olive | orange | orchid | peru | pink | plum | purple | red | salmon | sienna | silver | snow | tan | teal | thistle | tomato | turquoise | violet | white | yellow ;"; -const recognition = new SpeechRecognition(); -const speechRecognitionList = new SpeechGrammarList(); -speechRecognitionList.addFromString(grammar, 1); -recognition.grammars = speechRecognitionList; - -console.log(speechRecognitionList[0].src); // should return the same as the contents of the grammar variable -console.log(speechRecognitionList[0].weight); // should return 1 - the same as the weight set in addFromString. -``` - ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/speechgrammarlist/addfromstring/index.md b/files/en-us/web/api/speechgrammarlist/addfromstring/index.md index 220eeca06f18946..14f74aa4d26fbd0 100644 --- a/files/en-us/web/api/speechgrammarlist/addfromstring/index.md +++ b/files/en-us/web/api/speechgrammarlist/addfromstring/index.md @@ -37,17 +37,6 @@ addFromString(string, weight) None ({{jsxref("undefined")}}). -## Examples - -```js -const grammar = - "#JSGF V1.0; grammar colors; public = aqua | azure | beige | bisque | black | blue | brown | chocolate | coral | crimson | cyan | fuchsia | ghostwhite | gold | goldenrod | gray | green | indigo | ivory | khaki | lavender | lime | linen | magenta | maroon | moccasin | navy | olive | orange | orchid | peru | pink | plum | purple | red | salmon | sienna | silver | snow | tan | teal | thistle | tomato | turquoise | violet | white | yellow ;"; -const recognition = new SpeechRecognition(); -const speechRecognitionList = new SpeechGrammarList(); -speechRecognitionList.addFromString(grammar, 1); -recognition.grammars = speechRecognitionList; -``` - ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/speechgrammarlist/addfromuri/index.md b/files/en-us/web/api/speechgrammarlist/addfromuri/index.md index f5d881183955a52..fd7bd20954fd982 100644 --- a/files/en-us/web/api/speechgrammarlist/addfromuri/index.md +++ b/files/en-us/web/api/speechgrammarlist/addfromuri/index.md @@ -40,19 +40,6 @@ addFromURI(src, weight) None ({{jsxref("undefined")}}). -## Examples - -```js -const grammar = - "#JSGF V1.0; grammar colors; public = aqua | azure | beige | bisque | black | blue | brown | chocolate | coral | crimson | cyan | fuchsia | ghostwhite | gold | goldenrod | gray | green | indigo | ivory | khaki | lavender | lime | linen | magenta | maroon | moccasin | navy | olive | orange | orchid | peru | pink | plum | purple | red | salmon | sienna | silver | snow | tan | teal | thistle | tomato | turquoise | violet | white | yellow ;"; -const recognition = new SpeechRecognition(); -const speechRecognitionList = new SpeechGrammarList(); -speechRecognitionList.addFromString(grammar, 1); -recognition.grammars = speechRecognitionList; - -speechRecognitionList.addFromURI("http://www.example.com/grammar.txt"); // adds a second grammar to the list. -``` - ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/speechgrammarlist/index.md b/files/en-us/web/api/speechgrammarlist/index.md index c0a1cf689ae69e4..fca5303f4a92279 100644 --- a/files/en-us/web/api/speechgrammarlist/index.md +++ b/files/en-us/web/api/speechgrammarlist/index.md @@ -11,7 +11,10 @@ browser-compat: api.SpeechGrammarList The **`SpeechGrammarList`** interface of the [Web Speech API](/en-US/docs/Web/API/Web_Speech_API) represents a list of {{domxref("SpeechGrammar")}} objects containing words or patterns of words that we want the recognition service to recognize. -Grammar is defined using [JSpeech Grammar Format](https://www.w3.org/TR/jsgf/) (**JSGF**.) Other formats may also be supported in the future. +Grammar is defined using [JSpeech Grammar Format](https://www.w3.org/TR/jsgf/) (**JSGF**). + +> [!NOTE] +> The concept of grammar has been removed from the Web Speech API. Related features remain in the specification and are still recognized by supporting browsers for backwards compatibility, but they have no effect on speech recognition services. ## Constructor @@ -34,8 +37,6 @@ Grammar is defined using [JSpeech Grammar Format](https://www.w3.org/TR/jsgf/) ( ## Examples -In our simple [Speech color changer](https://github.com/mdn/dom-examples/tree/main/web-speech-api/speech-color-changer) example, we create a new `SpeechRecognition` object instance using the {{domxref("SpeechRecognition.SpeechRecognition", "SpeechRecognition()")}} constructor, create a new `SpeechGrammarList`, add our grammar string to it using the {{domxref("SpeechGrammarList.addFromString")}} method, and set it to be the grammar that will be recognized by the `SpeechRecognition` instance using the {{domxref("SpeechRecognition.grammars")}} property. - ```js const grammar = "#JSGF V1.0; grammar colors; public = aqua | azure | beige | bisque | black | blue | brown | chocolate | coral | crimson | cyan | fuchsia | ghostwhite | gold | goldenrod | gray | green | indigo | ivory | khaki | lavender | lime | linen | magenta | maroon | moccasin | navy | olive | orange | orchid | peru | pink | plum | purple | red | salmon | sienna | silver | snow | tan | teal | thistle | tomato | turquoise | violet | white | yellow ;"; diff --git a/files/en-us/web/api/speechgrammarlist/item/index.md b/files/en-us/web/api/speechgrammarlist/item/index.md index 40ea72d2f79d080..35724b543cc4480 100644 --- a/files/en-us/web/api/speechgrammarlist/item/index.md +++ b/files/en-us/web/api/speechgrammarlist/item/index.md @@ -29,19 +29,6 @@ item(index) A {{domxref("SpeechGrammar")}} object. -## Examples - -```js -const grammar = - "#JSGF V1.0; grammar colors; public = aqua | azure | beige | bisque | black | blue | brown | chocolate | coral | crimson | cyan | fuchsia | ghostwhite | gold | goldenrod | gray | green | indigo | ivory | khaki | lavender | lime | linen | magenta | maroon | moccasin | navy | olive | orange | orchid | peru | pink | plum | purple | red | salmon | sienna | silver | snow | tan | teal | thistle | tomato | turquoise | violet | white | yellow ;"; -const recognition = new SpeechRecognition(); -const speechRecognitionList = new SpeechGrammarList(); -speechRecognitionList.addFromString(grammar, 1); -recognition.grammars = speechRecognitionList; - -const myFirstGrammar = speechRecognitionList[0]; // variable contain the object created above -``` - ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/speechgrammarlist/length/index.md b/files/en-us/web/api/speechgrammarlist/length/index.md index 33597cca2f04592..f2aa231b91d30b3 100644 --- a/files/en-us/web/api/speechgrammarlist/length/index.md +++ b/files/en-us/web/api/speechgrammarlist/length/index.md @@ -19,19 +19,6 @@ The **`length`** read-only property of the A number indicating the number of {{domxref("SpeechGrammar")}} objects contained in the {{domxref("SpeechGrammarList")}}. -## Examples - -```js -const grammar = - "#JSGF V1.0; grammar colors; public = aqua | azure | beige | bisque | black | blue | brown | chocolate | coral | crimson | cyan | fuchsia | ghostwhite | gold | goldenrod | gray | green | indigo | ivory | khaki | lavender | lime | linen | magenta | maroon | moccasin | navy | olive | orange | orchid | peru | pink | plum | purple | red | salmon | sienna | silver | snow | tan | teal | thistle | tomato | turquoise | violet | white | yellow ;"; -const recognition = new SpeechRecognition(); -const speechRecognitionList = new SpeechGrammarList(); -speechRecognitionList.addFromString(grammar, 1); -recognition.grammars = speechRecognitionList; - -speechRecognitionList.length; // should return 1. -``` - ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/speechgrammarlist/speechgrammarlist/index.md b/files/en-us/web/api/speechgrammarlist/speechgrammarlist/index.md index 36e88ee747d414e..c4f20f8e4824117 100644 --- a/files/en-us/web/api/speechgrammarlist/speechgrammarlist/index.md +++ b/files/en-us/web/api/speechgrammarlist/speechgrammarlist/index.md @@ -23,24 +23,6 @@ new SpeechGrammarList() None. -## Examples - -In our simple [Speech color changer](https://github.com/mdn/dom-examples/tree/main/web-speech-api/speech-color-changer) example, we create a new `SpeechRecognition` object -instance using the {{domxref("SpeechRecognition.SpeechRecognition", "SpeechRecognition()")}} constructor, create a new {{domxref("SpeechGrammarList")}}, add -our grammar string to it using the {{domxref("SpeechGrammarList.addFromString")}} -method, and set it to be the grammar that will be recognized by the -`SpeechRecognition` instance using the -{{domxref("SpeechRecognition.grammars")}} property. - -```js -const grammar = - "#JSGF V1.0; grammar colors; public = aqua | azure | beige | bisque | black | blue | brown | chocolate | coral | crimson | cyan | fuchsia | ghostwhite | gold | goldenrod | gray | green | indigo | ivory | khaki | lavender | lime | linen | magenta | maroon | moccasin | navy | olive | orange | orchid | peru | pink | plum | purple | red | salmon | sienna | silver | snow | tan | teal | thistle | tomato | turquoise | violet | white | yellow ;"; -const recognition = new SpeechRecognition(); -const speechRecognitionList = new SpeechGrammarList(); -speechRecognitionList.addFromString(grammar, 1); -recognition.grammars = speechRecognitionList; -``` - ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/speechrecognition/abort/index.md b/files/en-us/web/api/speechrecognition/abort/index.md index 5efe9ceea6bbc52..6f701f2c0a0b736 100644 --- a/files/en-us/web/api/speechrecognition/abort/index.md +++ b/files/en-us/web/api/speechrecognition/abort/index.md @@ -29,17 +29,14 @@ None ({{jsxref("undefined")}}). ## Examples ```js -const grammar = - "#JSGF V1.0; grammar colors; public = aqua | azure | beige | bisque | black | blue | brown | chocolate | coral | crimson | cyan | fuchsia | ghostwhite | gold | goldenrod | gray | green | indigo | ivory | khaki | lavender | lime | linen | magenta | maroon | moccasin | navy | olive | orange | orchid | peru | pink | plum | purple | red | salmon | sienna | silver | snow | tan | teal | thistle | tomato | turquoise | violet | white | yellow ;"; const recognition = new SpeechRecognition(); -const speechRecognitionList = new SpeechGrammarList(); -speechRecognitionList.addFromString(grammar, 1); -recognition.grammars = speechRecognitionList; const diagnostic = document.querySelector(".output"); const bg = document.querySelector("html"); +const startBtn = document.querySelector(".start"); +const abortBtn = document.querySelector(".abort"); -document.body.onclick = () => { +startBtn.onclick = () => { recognition.start(); console.log("Ready to receive a color command."); }; diff --git a/files/en-us/web/api/speechrecognition/available_static/index.md b/files/en-us/web/api/speechrecognition/available_static/index.md new file mode 100644 index 000000000000000..e75e32c2558fffe --- /dev/null +++ b/files/en-us/web/api/speechrecognition/available_static/index.md @@ -0,0 +1,139 @@ +--- +title: "SpeechRecognition: available() static method" +short-title: available() +slug: Web/API/SpeechRecognition/available_static +page-type: web-api-static-method +browser-compat: api.SpeechRecognition.available +--- + +{{APIRef("Web Speech API")}} + +The **`available()`** static method of the [Web Speech API](/en-US/docs/Web/API/Web_Speech_API) checks whether the specified languages are available for speech recognition. + +To install a language pack for speech recognition locally, you need to use the {{domxref("SpeechRecognition.install_static", "SpeechRecognition.install()")}} method. + +Access to the `available()` method is controlled by the {{httpheader("Permissions-Policy/on-device-speech-recognition", "on-device-speech-recognition")}} {{httpheader("Permissions-Policy")}} directive. Specifically, where a defined policy blocks usage, any attempts to call the method will fail. + +## Syntax + +```js-nolint +available(options) +``` + +### Parameters + +- `options` + - : An object specifying options for the availability check. Possible properties include: + - `langs` + - : An array of one or more strings containing {{glossary("BCP 47 language tag", "BCP 47 language tags")}}, each representing a language that you want to check availability of for speech recognition. Passing an empty `langs` array will not throw an error, but the return value will always resolve to `unavailable`. + - `processLocally` {{optional_inline}} + - : A boolean that specifies whether you are checking availability of the specified languages for [on-device speech recognition](/en-US/docs/Web/API/Web_Speech_API/Using_the_Web_Speech_API#on-device_speech_recognition) (`true`) or availability of the specified languages for on-device _or_ remote speech recognition (`false`). Defaults to `false`. + > [!NOTE] + > It is not possible to use `available()` to determine whether a remote service is guaranteed to support the specified languages. A value of `false` means that either an on-device _or_ remote speech recognition service supports the specified languages. + +### Return value + +A {{domxref("Promise")}} that resolves with an enumerated value indicating the availability of the specified languages for speech recognition. + +Possible values are as follows. + +- `available` + - : Indicates that support for all the specified languages is available. + - If `processLocally` is set to `true`, `available` means that speech recognition is available for those languages on-device (the required language packs have been downloaded and installed on the user's computer). + - If `processLocally` is set to `false`, `available` means that speech recognition is available for those languages either on-device or remotely. +- `downloading` + - : Indicates that support for the specified languages is available on-device, and the relevant language pack for at least one language is in the process of being downloaded. Only relevant when `processLocally` is `true`. +- `downloadable` + - : Indicates that support for the specified languages is available on-device, but the relevant language pack for at least one language has not yet been downloaded. Only relevant when `processLocally` is `true`. +- `unavailable` + - : Indicates that support for at least one of the specified languages is not available. + - If `processLocally` is set to `true`, `unavailable` means that on-device speech recognition is not available for at least one of the specified languages. + - If `processLocally` is set to `false`, `unavailable` means that speech recognition is not available for at least one of the specified languages either on-device or remotely. + +#### Final return value for multiple languages with different statuses + +Only a single status value is returned, even if multiple languages are specified in the `langs` array. If different specified languages have different availability statuses, the final returned status will be the "furthest away" status to `available` of any of the languages, in the order shown in the following lists. + +If `processLocally` is `false`: + +- If all languages are `available`, then return `available`. +- Otherwise, return `unavailable`. + +If `processLocally` is `true`: + +- If all languages are `available`, return `available`. +- If at least one language is `downloading`, return `downloading`. +- If at least one language is `downloadable`, return `downloadable`. +- If at least one language is `unavailable`, return `unavailable`. + +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : The current document is not fully active. +- `SyntaxError` {{domxref("DOMException")}} + - : One or more of the strings specified in `langs` is not a valid BCP 47 language tag. + +## Examples + +### Checking on-device availability and installing language packs + +For on-device speech recognition to occur, the browser needs to have a language pack installed for the language you are trying to recognize. If you run the `start()` method after specifying `processLocally = true` and you haven't got the correct language pack installed, it will fail with a [`language-not-supported`](/en-US/docs/Web/API/SpeechRecognitionErrorEvent/error#language-not-supported) error. + +To get the correct language pack installed, there are two steps to follow. + +1. You need to check whether the language pack is available on the user's computer using the `available()` method. +2. You need to install the language pack if it isn't available using the {{domxref("SpeechRecognition.install_static", "SpeechRecognition.install()")}} method. + +Both of the above steps are handled using the following code snippet: + +```js +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 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 the language is not available, and a suitable language pack is not available to download, so we 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 run `start()` and log a message to the console when the app is ready to receive speech. +- If the value is something else (`downloadable` or `downloading`), we print a diagnostic message to inform the user that a language code download is commencing, then run the `install()` method to handle the download. + +The `install()` method works in a similar way to the `available()` method, except that its options object only takes the `langs` array. When run, it starts downloading the `en-US` language pack and returns a {{jsxref("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](https://github.com/mdn/dom-examples/tree/main/web-speech-api/on-device-speech-color-changer) ([run the demo live](https://mdn.github.io/dom-examples/web-speech-api/speech-color-changer/)). See [Using the Web Speech API](/en-US/docs/Web/API/Web_Speech_API/Using_the_Web_Speech_API) for a full explanation. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Web Speech API](/en-US/docs/Web/API/Web_Speech_API) +- {{domxref("SpeechRecognition.processLocally")}} +- {{domxref("SpeechRecognition.install_static", "SpeechRecognition.install()")}} diff --git a/files/en-us/web/api/speechrecognition/continuous/index.md b/files/en-us/web/api/speechrecognition/continuous/index.md index d50e8f6bac38e36..281e3c9b608d340 100644 --- a/files/en-us/web/api/speechrecognition/continuous/index.md +++ b/files/en-us/web/api/speechrecognition/continuous/index.md @@ -25,12 +25,7 @@ continuous (single result each time.) This code is excerpted from our [Speech color changer](https://github.com/mdn/dom-examples/blob/main/web-speech-api/speech-color-changer/script.js) example. ```js -const grammar = - "#JSGF V1.0; grammar colors; public = aqua | azure | beige | bisque | black | blue | brown | chocolate | coral | crimson | cyan | fuchsia | ghostwhite | gold | goldenrod | gray | green | indigo | ivory | khaki | lavender | lime | linen | magenta | maroon | moccasin | navy | olive | orange | orchid | peru | pink | plum | purple | red | salmon | sienna | silver | snow | tan | teal | thistle | tomato | turquoise | violet | white | yellow ;"; const recognition = new SpeechRecognition(); -const speechRecognitionList = new SpeechGrammarList(); -speechRecognitionList.addFromString(grammar, 1); -recognition.grammars = speechRecognitionList; recognition.continuous = false; recognition.lang = "en-US"; recognition.interimResults = false; diff --git a/files/en-us/web/api/speechrecognition/grammars/index.md b/files/en-us/web/api/speechrecognition/grammars/index.md index c3d7cbf8c11adc9..5364b52e9346b81 100644 --- a/files/en-us/web/api/speechrecognition/grammars/index.md +++ b/files/en-us/web/api/speechrecognition/grammars/index.md @@ -13,16 +13,15 @@ The **`grammars`** property of the {{domxref("SpeechGrammar")}} objects that represent the grammars that will be understood by the current `SpeechRecognition`. +> [!NOTE] +> The concept of grammar has been removed from the Web Speech API. Related features remain in the specification and are still recognized by supporting browsers for backwards compatibility, but they have no effect on speech recognition services. + ## Value -A {{domxref("SpeechGrammarList")}} containing the {{domxref("SpeechGrammar")}} objects -that represent your grammar for your app. +A {{domxref("SpeechGrammarList")}} containing the {{domxref("SpeechGrammar")}} objects that represent the grammars of your app. ## Examples -This code is excerpted from our -[Speech color changer](https://github.com/mdn/dom-examples/blob/main/web-speech-api/speech-color-changer/script.js) example. - ```js const grammar = "#JSGF V1.0; grammar colors; public = aqua | azure | beige | bisque | black | blue | brown | chocolate | coral | crimson | cyan | fuchsia | ghostwhite | gold | goldenrod | gray | green | indigo | ivory | khaki | lavender | lime | linen | magenta | maroon | moccasin | navy | olive | orange | orchid | peru | pink | plum | purple | red | salmon | sienna | silver | snow | tan | teal | thistle | tomato | turquoise | violet | white | yellow ;"; @@ -30,10 +29,6 @@ const recognition = new SpeechRecognition(); const speechRecognitionList = new SpeechGrammarList(); speechRecognitionList.addFromString(grammar, 1); recognition.grammars = speechRecognitionList; -// recognition.continuous = false; -recognition.lang = "en-US"; -recognition.interimResults = false; -recognition.maxAlternatives = 1; // … ``` diff --git a/files/en-us/web/api/speechrecognition/index.md b/files/en-us/web/api/speechrecognition/index.md index e0a1c1856b37f29..5a6f8e4b7437ab2 100644 --- a/files/en-us/web/api/speechrecognition/index.md +++ b/files/en-us/web/api/speechrecognition/index.md @@ -23,8 +23,6 @@ The **`SpeechRecognition`** interface of the [Web Speech API](/en-US/docs/Web/AP _`SpeechRecognition` also inherits properties from its parent interface, {{domxref("EventTarget")}}._ -- {{domxref("SpeechRecognition.grammars")}} - - : Returns and sets a collection of {{domxref("SpeechGrammar")}} objects that represent the grammars that will be understood by the current `SpeechRecognition`. - {{domxref("SpeechRecognition.lang")}} - : Returns and sets the language of the current `SpeechRecognition`. If not specified, this defaults to the HTML [`lang`](/en-US/docs/Web/HTML/Reference/Global_attributes/lang) attribute value, or the user agent's language setting if that isn't set either. - {{domxref("SpeechRecognition.continuous")}} @@ -33,6 +31,24 @@ _`SpeechRecognition` also inherits properties from its parent interface, {{domxr - : Controls whether interim results should be returned (`true`) or not (`false`.) Interim results are results that are not yet final (e.g., the {{domxref("SpeechRecognitionResult.isFinal")}} property is `false`.) - {{domxref("SpeechRecognition.maxAlternatives")}} - : Sets the maximum number of {{domxref("SpeechRecognitionAlternative")}}s provided per result. The default value is 1. +- {{domxref("SpeechRecognition.phrases")}} + - : Sets an array of {{domxref("SpeechRecognitionPhrase")}} objects to be used for [speech recognition contextual biasing](/en-US/docs/Web/API/Web_Speech_API/Using_the_Web_Speech_API#speech_recognition_contextual_biasing). +- {{domxref("SpeechRecognition.processLocally")}} + - : Specifies whether speech recognition must be performed locally on the user's device. + +### Deprecated properties + +The concept of grammar has been removed from the Web Speech API. Related features remain in the specification and are still recognized by supporting browsers for backwards compatibility, but they have no effect on speech recognition services. + +- {{domxref("SpeechRecognition.grammars")}} {{deprecated_inline}} + - : Returns and sets a collection of {{domxref("SpeechGrammar")}} objects that represent the grammars understood by the current `SpeechRecognition`. + +## Static methods + +- {{domxref("SpeechRecognition.available_static", "SpeechRecognition.available()")}} + - : Checks whether the specified languages are available for speech recognition. +- {{domxref("SpeechRecognition.install_static", "SpeechRecognition.install()")}} + - : Installs the required language packs for on-device speech recognition of the specified languages. ## Instance methods @@ -41,9 +57,9 @@ _`SpeechRecognition` also inherits methods from its parent interface, {{domxref( - {{domxref("SpeechRecognition.abort()")}} - : Stops the speech recognition service from listening to incoming audio, and doesn't attempt to return a {{domxref("SpeechRecognitionResult")}}. - {{domxref("SpeechRecognition.start()")}} - - : Starts the speech recognition service listening to incoming audio with intent to recognize grammars associated with the current `SpeechRecognition`. + - : Starts the speech recognition service to listen for incoming audio (from a microphone or an audio track) and returns the results of that recognition. - {{domxref("SpeechRecognition.stop()")}} - - : Stops the speech recognition service from listening to incoming audio, and attempts to return a {{domxref("SpeechRecognitionResult")}} using the audio captured so far. + - : Stops the speech recognition service from listening for incoming audio and attempts to return a {{domxref("SpeechRecognitionResult")}} based on the results captured so far. ## Events @@ -51,51 +67,35 @@ Listen to these events using [`addEventListener()`](/en-US/docs/Web/API/EventTar - [`audiostart`](/en-US/docs/Web/API/SpeechRecognition/audiostart_event) - : Fired when the user agent has started to capture audio. - Also available via the `onaudiostart` property. - [`audioend`](/en-US/docs/Web/API/SpeechRecognition/audioend_event) - : Fired when the user agent has finished capturing audio. - Also available via the `onaudioend` property. - [`end`](/en-US/docs/Web/API/SpeechRecognition/end_event) - : Fired when the speech recognition service has disconnected. - Also available via the `onend` property. - [`error`](/en-US/docs/Web/API/SpeechRecognition/error_event) - : Fired when a speech recognition error occurs. - Also available via the `onerror` property. - [`nomatch`](/en-US/docs/Web/API/SpeechRecognition/nomatch_event) - : Fired when the speech recognition service returns a final result with no significant recognition. This may involve some degree of recognition, which doesn't meet or exceed the {{domxref("SpeechRecognitionAlternative.confidence","confidence")}} threshold. - Also available via the `onnomatch` property. - [`result`](/en-US/docs/Web/API/SpeechRecognition/result_event) - : Fired when the speech recognition service returns a result — a word or phrase has been positively recognized and this has been communicated back to the app. - Also available via the `onresult` property. - [`soundstart`](/en-US/docs/Web/API/SpeechRecognition/soundstart_event) - : Fired when any sound — recognizable speech or not — has been detected. - Also available via the `onsoundstart` property. - [`soundend`](/en-US/docs/Web/API/SpeechRecognition/soundend_event) - : Fired when any sound — recognizable speech or not — has stopped being detected. - Also available via the `onsoundend` property. - [`speechstart`](/en-US/docs/Web/API/SpeechRecognition/speechstart_event) - : Fired when sound that is recognized by the speech recognition service as speech has been detected. - Also available via the `onspeechstart` property. - [`speechend`](/en-US/docs/Web/API/SpeechRecognition/speechend_event) - : Fired when speech recognized by the speech recognition service has stopped being detected. - Also available via the `onspeechend` property. - [`start`](/en-US/docs/Web/API/SpeechRecognition/start_event) - - : Fired when the speech recognition service has begun listening to incoming audio with intent to recognize grammars associated with the current `SpeechRecognition`. - Also available via the `onstart` property. + - : Fired when the speech recognition service begins listening for audio to recognize. ## Examples -In our simple [Speech color changer](https://github.com/mdn/dom-examples/tree/main/web-speech-api/speech-color-changer) example, we create a new `SpeechRecognition` object instance using the {{domxref("SpeechRecognition.SpeechRecognition", "SpeechRecognition()")}} constructor, create a new {{domxref("SpeechGrammarList")}}, and set it to be the grammar that will be recognized by the `SpeechRecognition` instance using the {{domxref("SpeechRecognition.grammars")}} property. +In our [Speech color changer](https://mdn.github.io/dom-examples/web-speech-api/speech-color-changer) example, we create a new `SpeechRecognition` object instance using the {{domxref("SpeechRecognition.SpeechRecognition", "SpeechRecognition()")}} constructor. -After some other values have been defined, we then set it so that the recognition service starts when a click event occurs (see {{domxref("SpeechRecognition.start()")}}.) When a result has been successfully recognized, the {{domxref("SpeechRecognition.result_event", "result")}} event fires, we extract the color that was spoken from the event object, and then set the background color of the {{htmlelement("html")}} element to that color. +After some other values have been defined, we then set it so that the recognition service starts when a button is clicked (see {{domxref("SpeechRecognition.start()")}}). When a result has been successfully recognized, the {{domxref("SpeechRecognition.result_event", "result")}} event fires, we extract the color that was spoken from the event object, and then set the background color of the {{htmlelement("html")}} element to that color. ```js -const grammar = - "#JSGF V1.0; grammar colors; public = aqua | azure | beige | bisque | black | blue | brown | chocolate | coral | crimson | cyan | fuchsia | ghostwhite | gold | goldenrod | gray | green | indigo | ivory | khaki | lavender | lime | linen | magenta | maroon | moccasin | navy | olive | orange | orchid | peru | pink | plum | purple | red | salmon | sienna | silver | snow | tan | teal | thistle | tomato | turquoise | violet | white | yellow ;"; const recognition = new SpeechRecognition(); -const speechRecognitionList = new SpeechGrammarList(); -speechRecognitionList.addFromString(grammar, 1); -recognition.grammars = speechRecognitionList; recognition.continuous = false; recognition.lang = "en-US"; recognition.interimResults = false; @@ -103,8 +103,9 @@ recognition.maxAlternatives = 1; const diagnostic = document.querySelector(".output"); const bg = document.querySelector("html"); +const startBtn = document.querySelector("button"); -document.body.onclick = () => { +startBtn.onclick = () => { recognition.start(); console.log("Ready to receive a color command."); }; diff --git a/files/en-us/web/api/speechrecognition/install_static/index.md b/files/en-us/web/api/speechrecognition/install_static/index.md new file mode 100644 index 000000000000000..ba80f6694336cbd --- /dev/null +++ b/files/en-us/web/api/speechrecognition/install_static/index.md @@ -0,0 +1,109 @@ +--- +title: "SpeechRecognition: install() static method" +short-title: install() +slug: Web/API/SpeechRecognition/install_static +page-type: web-api-static-method +browser-compat: api.SpeechRecognition.install +--- + +{{APIRef("Web Speech API")}} + +The **`install()`** static method of the [Web Speech API](/en-US/docs/Web/API/Web_Speech_API) installs the required language packs for [on-device speech recognition](/en-US/docs/Web/API/Web_Speech_API/Using_the_Web_Speech_API#on-device_speech_recognition) of the specified languages. + +To check existing availability of the language packs for on-device speech recognition, you can use the {{domxref("SpeechRecognition.available_static", "SpeechRecognition.available()")}} method. + +Access to the `install()` method is controlled by the {{httpheader("Permissions-Policy/on-device-speech-recognition", "on-device-speech-recognition")}} {{httpheader("Permissions-Policy")}} directive. Specifically, where a defined policy blocks usage, any attempts to call the method will fail. + +## Syntax + +```js-nolint +install(options) +``` + +### Parameters + +- `options` + - : An object specifying options for the installation. Possible properties include: + - `langs` + - : An array of one or more strings containing {{glossary("BCP 47 language tag", "BCP 47 language tags")}}, each representing a language that you want to install the language pack for. + +### Return value + +A {{domxref("Promise")}} that resolves with a boolean value indicating whether installation was successful. The conditions that result in each return value are as follows: + +- `true` + - : All installation attempts succeeded for the requested languages, or the languages were already installed. +- `false` + - : One or more of the requested languages are not supported, any of the language packs for supported languages failed to install, or an empty array was passed for the `langs` option. + +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : The current document is not fully active. +- `SyntaxError` {{domxref("DOMException")}} + - : One or more of the strings specified in `langs` is not a valid BCP 47 language tag. + +## Examples + +### Checking on-device availability and installing language packs + +For on-device speech recognition to occur, the browser needs to have a language pack installed for the language you are trying to recognize. If you run the `start()` method after specifying `processLocally = true` and you haven't got the correct language pack installed, it will fail with a [`language-not-supported`](/en-US/docs/Web/API/SpeechRecognitionErrorEvent/error#language-not-supported) error. + +To get the correct language pack installed, there are two steps to follow. + +1. You need to check whether the language pack is available on the user's computer using the {{domxref("SpeechRecognition.available_static", "SpeechRecognition.available()")}} method. +2. You need to install the language pack if it isn't available using the `install()` method. + +Both of the above steps are handled using the following code snippet: + +```js +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 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 the language is not available, and a suitable language pack is not available to download, so we 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 run `start()` and log a message to the console when the app is ready to receive speech. +- If the value is something else (`downloadable` or `downloading`), we print a diagnostic message to inform the user that a language code download is commencing, then run the `install()` method to handle the download. + +The `install()` method works in a similar way to the `available()` method, except that its options object only takes the `langs` array. When run, it starts downloading the `en-US` language pack and returns a {{jsxref("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](https://github.com/mdn/dom-examples/tree/main/web-speech-api/on-device-speech-color-changer) ([run the demo live](https://mdn.github.io/dom-examples/web-speech-api/speech-color-changer/)). See [Using the Web Speech API](/en-US/docs/Web/API/Web_Speech_API/Using_the_Web_Speech_API) for a full explanation. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Web Speech API](/en-US/docs/Web/API/Web_Speech_API) +- {{domxref("SpeechRecognition.processLocally")}} +- {{domxref("SpeechRecognition.available_static", "SpeechRecognition.available()")}} diff --git a/files/en-us/web/api/speechrecognition/interimresults/index.md b/files/en-us/web/api/speechrecognition/interimresults/index.md index c9488e2ca88a711..1926f177916f62e 100644 --- a/files/en-us/web/api/speechrecognition/interimresults/index.md +++ b/files/en-us/web/api/speechrecognition/interimresults/index.md @@ -27,13 +27,7 @@ results are returned, and `false` means they aren't. This code is excerpted from our [Speech color changer](https://github.com/mdn/dom-examples/blob/main/web-speech-api/speech-color-changer/script.js) example. ```js -const grammar = - "#JSGF V1.0; grammar colors; public = aqua | azure | beige | bisque | black | blue | brown | chocolate | coral | crimson | cyan | fuchsia | ghostwhite | gold | goldenrod | gray | green | indigo | ivory | khaki | lavender | lime | linen | magenta | maroon | moccasin | navy | olive | orange | orchid | peru | pink | plum | purple | red | salmon | sienna | silver | snow | tan | teal | thistle | tomato | turquoise | violet | white | yellow ;"; const recognition = new SpeechRecognition(); -const speechRecognitionList = new SpeechGrammarList(); -speechRecognitionList.addFromString(grammar, 1); -recognition.grammars = speechRecognitionList; -// recognition.continuous = false; recognition.lang = "en-US"; recognition.interimResults = false; recognition.maxAlternatives = 1; diff --git a/files/en-us/web/api/speechrecognition/lang/index.md b/files/en-us/web/api/speechrecognition/lang/index.md index 6e174a40c0c8dd7..a86ee06e7bb8dc3 100644 --- a/files/en-us/web/api/speechrecognition/lang/index.md +++ b/files/en-us/web/api/speechrecognition/lang/index.md @@ -15,20 +15,14 @@ value, or the user agent's language setting if that isn't set either. ## Value -A string representing the {{glossary("BCP 47 language tag")}} for the current `SpeechRecognition`. +A string representing the language for the current `SpeechRecognition`. The value should be a valid {{glossary("BCP 47 language tag")}}. ## Examples This code is excerpted from our [Speech color changer](https://github.com/mdn/dom-examples/blob/main/web-speech-api/speech-color-changer/script.js) example. ```js -const grammar = - "#JSGF V1.0; grammar colors; public = aqua | azure | beige | bisque | black | blue | brown | chocolate | coral | crimson | cyan | fuchsia | ghostwhite | gold | goldenrod | gray | green | indigo | ivory | khaki | lavender | lime | linen | magenta | maroon | moccasin | navy | olive | orange | orchid | peru | pink | plum | purple | red | salmon | sienna | silver | snow | tan | teal | thistle | tomato | turquoise | violet | white | yellow ;"; const recognition = new SpeechRecognition(); -const speechRecognitionList = new SpeechGrammarList(); -speechRecognitionList.addFromString(grammar, 1); -recognition.grammars = speechRecognitionList; -// recognition.continuous = false; recognition.lang = "en-US"; recognition.interimResults = false; recognition.maxAlternatives = 1; diff --git a/files/en-us/web/api/speechrecognition/maxalternatives/index.md b/files/en-us/web/api/speechrecognition/maxalternatives/index.md index d1b9ab7012393af..3ffbdedd7b80b33 100644 --- a/files/en-us/web/api/speechrecognition/maxalternatives/index.md +++ b/files/en-us/web/api/speechrecognition/maxalternatives/index.md @@ -24,13 +24,7 @@ A number representing the maximum returned alternatives for each result. This code is excerpted from our [Speech color changer](https://github.com/mdn/dom-examples/blob/main/web-speech-api/speech-color-changer/script.js) example. ```js -const grammar = - "#JSGF V1.0; grammar colors; public = aqua | azure | beige | bisque | black | blue | brown | chocolate | coral | crimson | cyan | fuchsia | ghostwhite | gold | goldenrod | gray | green | indigo | ivory | khaki | lavender | lime | linen | magenta | maroon | moccasin | navy | olive | orange | orchid | peru | pink | plum | purple | red | salmon | sienna | silver | snow | tan | teal | thistle | tomato | turquoise | violet | white | yellow ;"; const recognition = new SpeechRecognition(); -const speechRecognitionList = new SpeechGrammarList(); -speechRecognitionList.addFromString(grammar, 1); -recognition.grammars = speechRecognitionList; -// recognition.continuous = false; recognition.lang = "en-US"; recognition.interimResults = false; recognition.maxAlternatives = 1; diff --git a/files/en-us/web/api/speechrecognition/phrases/index.md b/files/en-us/web/api/speechrecognition/phrases/index.md new file mode 100644 index 000000000000000..f488b6a09909a2a --- /dev/null +++ b/files/en-us/web/api/speechrecognition/phrases/index.md @@ -0,0 +1,62 @@ +--- +title: "SpeechRecognition: phrases property" +short-title: phrases +slug: Web/API/SpeechRecognition/phrases +page-type: web-api-instance-property +browser-compat: api.SpeechRecognition.phrases +--- + +{{APIRef("Web Speech API")}} + +The **`phrases`** property of the +{{domxref("SpeechRecognition")}} interface sets an array of {{domxref("SpeechRecognitionPhrase")}} objects to be used for [speech recognition contextual biasing](/en-US/docs/Web/API/Web_Speech_API/Using_the_Web_Speech_API#speech_recognition_contextual_biasing). + +## Value + +An `ObservableArray` of {{domxref("SpeechRecognitionPhrase")}} objects. + +## Examples + +### Basic usage + +The following code first creates an array containing the phrases to boost and their {{domxref("SpeechRecognitionPhrase.boost", "boost")}} values. We convert this data to an `ObservableArray` of `SpeechRecognitionPhrase` objects by mapping the original array to {{domxref("SpeechRecognitionPhrase.SpeechRecognitionPhrase", "SpeechRecognitionPhrase()")}} constructor calls: + +```js +const phraseData = [ + { phrase: "azure", boost: 5.0 }, + { phrase: "khaki", boost: 3.0 }, + { phrase: "tan", boost: 2.0 }, +]; + +const phraseObjects = phraseData.map( + (p) => new SpeechRecognitionPhrase(p.phrase, p.boost), +); +``` + +After creating a {{domxref("SpeechRecognition")}} instance, we can then plug our contextual biasing phrases into it by setting the `phraseObjects` array as the value of the `SpeechRecognition.phrases` property: + +```js +const recognition = new SpeechRecognition(); +recognition.continuous = false; +recognition.lang = "en-US"; +recognition.interimResults = false; +recognition.processLocally = true; +recognition.phrases = phraseObjects; + +// … +``` + +This code is excerpted from our [on-device speech color changer](https://github.com/mdn/dom-examples/tree/main/web-speech-api/on-device-speech-color-changer) ([run the demo live](https://mdn.github.io/dom-examples/web-speech-api/speech-color-changer/)). See [Using the Web Speech API](/en-US/docs/Web/API/Web_Speech_API/Using_the_Web_Speech_API) for a full explanation. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Web Speech API](/en-US/docs/Web/API/Web_Speech_API) +- {{domxref("SpeechRecognitionPhrase")}} diff --git a/files/en-us/web/api/speechrecognition/processlocally/index.md b/files/en-us/web/api/speechrecognition/processlocally/index.md new file mode 100644 index 000000000000000..5acc3352efacc9f --- /dev/null +++ b/files/en-us/web/api/speechrecognition/processlocally/index.md @@ -0,0 +1,46 @@ +--- +title: "SpeechRecognition: processLocally property" +short-title: processLocally +slug: Web/API/SpeechRecognition/processLocally +page-type: web-api-instance-property +browser-compat: api.SpeechRecognition.processLocally +--- + +{{APIRef("Web Speech API")}} + +The **`processLocally`** property of the +{{domxref("SpeechRecognition")}} interface specifies whether speech recognition must be performed locally on the user's device. + +See [On-device speech recognition](/en-US/docs/Web/API/Web_Speech_API/Using_the_Web_Speech_API#on-device_speech_recognition) for more information. + +## Value + +A boolean value. + +- If set to `true`, speech recognition done via the `SpeechRecognition` object must be done locally. +- If set to `false` (the default), the user agent can choose whether to do the processing locally or remotely. + +## Examples + +### Basic usage + +The following code creates a new `SpeechRecognition` object instance using the {{domxref("SpeechRecognition.SpeechRecognition", "SpeechRecognition()")}} constructor, then specifies that it should use local processing by setting `processLocally` to `true`: + +```js +const recognition = new SpeechRecognition(); +recognition.processLocally = true; +``` + +This code is excerpted from our [on-device speech color changer](https://github.com/mdn/dom-examples/tree/main/web-speech-api/on-device-speech-color-changer) ([run the demo live](https://mdn.github.io/dom-examples/web-speech-api/speech-color-changer/)). See [Using the Web Speech API](/en-US/docs/Web/API/Web_Speech_API/Using_the_Web_Speech_API) for a full explanation. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Web Speech API](/en-US/docs/Web/API/Web_Speech_API) diff --git a/files/en-us/web/api/speechrecognition/speechrecognition/index.md b/files/en-us/web/api/speechrecognition/speechrecognition/index.md index 08d7aa09dd1ee1b..b0c89370627df22 100644 --- a/files/en-us/web/api/speechrecognition/speechrecognition/index.md +++ b/files/en-us/web/api/speechrecognition/speechrecognition/index.md @@ -26,13 +26,7 @@ None. This code is excerpted from our [Speech color changer](https://github.com/mdn/dom-examples/blob/main/web-speech-api/speech-color-changer/script.js) example. ```js -const grammar = - "#JSGF V1.0; grammar colors; public = aqua | azure | beige | bisque | black | blue | brown | chocolate | coral | crimson | cyan | fuchsia | ghostwhite | gold | goldenrod | gray | green | indigo | ivory | khaki | lavender | lime | linen | magenta | maroon | moccasin | navy | olive | orange | orchid | peru | pink | plum | purple | red | salmon | sienna | silver | snow | tan | teal | thistle | tomato | turquoise | violet | white | yellow ;"; const recognition = new SpeechRecognition(); -const speechRecognitionList = new SpeechGrammarList(); -speechRecognitionList.addFromString(grammar, 1); -recognition.grammars = speechRecognitionList; -// recognition.continuous = false; recognition.lang = "en-US"; recognition.interimResults = false; recognition.maxAlternatives = 1; diff --git a/files/en-us/web/api/speechrecognition/start/index.md b/files/en-us/web/api/speechrecognition/start/index.md index fc00377bd1c85ef..4e8850302cfee14 100644 --- a/files/en-us/web/api/speechrecognition/start/index.md +++ b/files/en-us/web/api/speechrecognition/start/index.md @@ -8,53 +8,101 @@ browser-compat: api.SpeechRecognition.start {{APIRef("Web Speech API")}} -The **`start()`** method of the [Web Speech API](/en-US/docs/Web/API/Web_Speech_API) starts the speech -recognition service listening to incoming audio with intent to recognize grammars -associated with the current {{domxref("SpeechRecognition")}}. +The **`start()`** method of the [Web Speech API](/en-US/docs/Web/API/Web_Speech_API) starts the speech recognition service to listen for incoming audio (from a microphone or an audio track) and returns the results of that recognition. ## Syntax ```js-nolint start() +start(audioTrack) ``` ### Parameters -None. +- `audioTrack` {{optional_inline}} + - : A {{domxref("MediaStreamTrack")}} instance to perform speech recognition on. If not specified, the service attempts to recognize audio from the user's microphone instead. ### Return value None ({{jsxref("undefined")}}). +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : Thrown if an `audioTrack` is specified and one or both of the following are true: + - The track's {{domxref("MediaStreamTrack.kind", "kind")}} property is not `audio`. + - The track's {{domxref("MediaStreamTrack.readyState", "readyState")}} property is not `live`. + ## Examples +### Recognizing speech from a microphone + +In our [Speech color changer](https://mdn.github.io/dom-examples/web-speech-api/speech-color-changer) example, we create a new `SpeechRecognition` object instance using the {{domxref("SpeechRecognition.SpeechRecognition", "SpeechRecognition()")}} constructor. Later on, we create a `click` event handler on a ` + +

...diagnostic messages

``` -The CSS provides a very simple responsive styling so that it looks OK across devices. +The CSS provides a basic responsive styling so that it looks OK across devices. ### JavaScript @@ -44,21 +50,19 @@ Let's look at the JavaScript in a bit more detail. #### Prefixed properties -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 that may be supported in future: +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: ```js const SpeechRecognition = window.SpeechRecognition || window.webkitSpeechRecognition; -const SpeechGrammarList = - window.SpeechGrammarList || window.webkitSpeechGrammarList; const SpeechRecognitionEvent = window.SpeechRecognitionEvent || window.webkitSpeechRecognitionEvent; ``` -#### The grammar +#### Color list -The next part of our code defines the grammar we want our app to recognize. The following variable is defined to hold our grammar: +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: ```js const colors = [ @@ -73,42 +77,24 @@ const colors = [ "coral", // … ]; -const grammar = `#JSGF V1.0; grammar colors; public = ${colors.join( - " | ", -)};`; ``` -The grammar format used is [JSpeech Grammar Format](https://www.w3.org/TR/jsgf/) (**JSGF**) — you can find a lot more about it at the previous link to its spec. However, for now let's just run through it quickly: - -- The lines are separated by semicolons, just like in JavaScript. -- The first line — `#JSGF V1.0;` — states the format and version used. This always needs to be included first. -- The second line indicates a type of term that we want to recognize. `public` declares that it is a public rule, the string in angle brackets defines the recognized name for this term (`color`), and the list of items that follow the equals sign are the alternative values that will be recognized and accepted as appropriate values for the term. Note how each is separated by a pipe character. -- You can have as many terms defined as you want on separate lines following the above structure, and include fairly complex grammar definitions. For this basic demo, we are just keeping things simple. +#### Creating a speech recognition instance -#### Plugging the grammar into our speech recognition - -The next thing to do is define a speech recognition instance to control the recognition for our application. This is done using the {{domxref("SpeechRecognition.SpeechRecognition()","SpeechRecognition()")}} constructor. We also create a new speech grammar list to contain our grammar, using the {{domxref("SpeechGrammarList.SpeechGrammarList()","SpeechGrammarList()")}} constructor. +Next, we define a speech recognition instance to control the recognition in our application. We do this by using the {{domxref("SpeechRecognition.SpeechRecognition()","SpeechRecognition()")}} constructor. ```js const recognition = new SpeechRecognition(); -const speechRecognitionList = new SpeechGrammarList(); -``` - -We add our `grammar` to the list using the {{domxref("SpeechGrammarList.addFromString()")}} method. This accepts as parameters the string we want to add, plus optionally a weight value that specifies the importance of this grammar in relation of other grammars available in the list (can be from 0 to 1 inclusive.) The added grammar is available in the list as a {{domxref("SpeechGrammar")}} object instance. - -```js -speechRecognitionList.addFromString(grammar, 1); ``` -We then add the {{domxref("SpeechGrammarList")}} to the speech recognition instance by setting it to the value of the {{domxref("SpeechRecognition.grammars")}} property. We also set a few other properties of the recognition instance before we move on: +We then set a few properties of the recognition instance: -- {{domxref("SpeechRecognition.continuous")}}: Controls whether continuous results are captured (`true`), or just a single result each time recognition is started (`false`). -- {{domxref("SpeechRecognition.lang")}}: Sets the language of the recognition. Setting this is good practice, and therefore recommended. -- {{domxref("SpeechRecognition.interimResults")}}: Defines whether the speech recognition system should return interim results, or just final results. Final results are good enough for this simple demo. -- {{domxref("SpeechRecognition.maxAlternatives")}}: Sets the number of alternative potential matches that should be returned per result. This can sometimes be useful, say if a result is not completely clear and you want to display a list if alternatives for the user to choose the correct one from. But it is not needed for this simple demo, so we are just specifying one (which is actually the default anyway.) +- {{domxref("SpeechRecognition.continuous")}}: Controls whether results are captured continuously (`true`) or only once each time a recognition starts (`false`). +- {{domxref("SpeechRecognition.lang")}}: Sets the language of the recognition. Setting this explicitly is the recommended best practice. +- {{domxref("SpeechRecognition.interimResults")}}: Defines whether the speech recognition system should return interim results or only final results. For this demo, final results are good enough. +- {{domxref("SpeechRecognition.maxAlternatives")}}: Sets the number of alternative potential matches that should be returned per result. This can sometimes be useful, say if a result is not completely clear and you want to display a list of alternatives for the user to choose from. But it's not needed for this demo, so we're just specifying one (which is the default anyway). ```js -recognition.grammars = speechRecognitionList; recognition.continuous = false; recognition.lang = "en-US"; recognition.interimResults = false; @@ -117,21 +103,25 @@ recognition.maxAlternatives = 1; #### Starting the speech recognition -After grabbing references to the output {{htmlelement("div")}} and the HTML element (so we can output diagnostic messages and update the app background color later on), we implement an onclick handler so that when the screen is tapped/clicked, the speech recognition service will start. This is achieved by calling {{domxref("SpeechRecognition.start()")}}. The `forEach()` method is used to output colored indicators showing what colors to try saying. +After grabbing references to the output paragraph, the `` element, the instruction paragraph, and the `