Share via

Handle events (Browser)

Your app can be notified about various events that happen during speech recognition.

Session events

Your app can be notified whenever recording is started or stopped during a session, or when microphone buttons are pressed:

function NUSA_onRecordingStarted() { }  

function NUSA_onRecordingStopped() { }

function NUSA_onControlDeviceEventReceived(eventButtonId) { }

There are predefined JavaScript functions you can overwrite to handle the events.

The NUSA_onRecordingStarted() and NUSA_onRecordingStopped() callbacks notify your app of changes in the recording state, which can be triggered by the user, a call to the NUSA_stopRecording() function, an error, an idle timeout or any other cause, and enable you to update your internal representation of the recording state.

The NUSA_onControlDeviceEventReceived() callback notifies your app if a microphone button is pressed by the user. Your app can then trigger actions such as opening or closing a report. For more information, see: Microphone button handling.

VuiController events

Your app can be notified about events related to individual VuiForms:

function NUSA_onProcessingStarted() { }

function NUSA_onProcessingFinished() { }

Important information

  • These events are always fired in pairs; for example, for every NUSA_onProcessingStarted() call there is always a corresponding NUSA_onProcessingFinished() call.

  • If your app is notified about VuiController events you can (among other tasks) change the GUI based on whether the speech recognition process is ongoing or has finished, either globally or for a specific control.

    Globally: For example, you want to stop the user navigating away from the current speech-enabled page while speech recognition processing is ongoing (to make sure that no recognition results are lost). In this case, the NUSA_onProcessingStarted() and the NUSA_onProcessingFinished() callbacks can be used to disable and enable navigation between forms.

    Specific control: For example, the GUI layout of your app changes based on whether the sound is recorded into a specific control. In this case, wait to change the GUI until all the utterances recorded into that control are completely recognized. By performing the GUI change from the NUSA_onProcessingFinished() callback, you can make sure that all the relevant recognition results are displayed.

  • The NUSA_onProcessingStarted() and NUSA_onProcessingFinished() events (global and text control-specific) are reliable only if recording has already been stopped; the user might start speaking again after the NUSA_onProcessingFinished event is fired.

  • NUSA_onProcessingStarted() and NUSA_onProcessingFinished() events are always fired in pairs: When recording starts (with no recognition results pending from previous recording) and when all recognition results have been processed.

  • The NUSA_onProcessingStarted() and NUSA_onProcessingFinished() callbacks can't detect which controls received recognition results.

  • The NUSA_onCommandRecognized(cmdId, spokenPhrase, content, placeholderIds, placeholderValues) { } event is called when an application command has been recognized. The following information is delivered by the event about the recognized voice command:

    id - the identifier of the recognized command.

    spokenPhrase - the actual phrase that was recognized.

    content – deprecated, this parameter is always empty.

    placeholderIds and placeholderValues - the placeholder identifiers and value pairs that are present in the recognized voice command.

For more information, see the application commands concept and the application commands use case.

Text control events

Your app can be notified about events related to individual text controls (within a VuiForm):

function NUSA_onProcessingStartedForElement(element)

function NUSA_onProcessingFinishedForElement(element)

  • These events are always fired in pairs; for example, for every NUSA_onProcessingStartedForElement(element) call there is always a corresponding NUSA_onProcessingFinishedForElement(element) call.

  • The NUSA_onProcessingStartedForElement(element) and NUSA_onProcessingFinishedForElement(element) events track which controls receive the recognition results.

Example of text-processing events

Let's look at the following scenario:

  • There are two controls in the form: Field 1 and Field 2. Field 1 has the speech focus when recording is started.

  • The user records three utterances without waiting for the results: this is a test, next field and this is another test. Then recording is stopped.

  • When all speech recognition processing is finished, Field 1 contains "This is a test", Field 2 contains "This is another test" and Field 2 has the speech focus.

How the events work in this scenario:

  1. Field 1 has the speech focus and the user says this is a test: NUSA_onProcessingStarted() and NUSA_onProcessingStartedForElement(field1) events are fired.

  2. Field 1 has the speech focus and the user says next field and this is another test: Speech recognition processing is ongoing, therefore no finished events are fired.

  3. Field 2 has the speech focus, the NUSA_onProcessingStartedForElement(field2) event is fired.

  4. "This is a test" is written in Field 1 and speech recognition processing is finished for the control, the NUSA_onProcessingFinishedForElement(field1) event is fired.

  5. "This is another test" is written in Field 2 and speech recognition processing is finished for the control, the NUSA_onProcessingFinishedForElement(field2) event is fired.

  6. Speech recognition processing is finished for the VuiForm, the NUSA_onProcessingFinished() event is fired.

See also

Dynamically modified controls

  • Last updated on