Handle events (.NET)

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. In your app, add event handlers for the events that are exposed by the ISession interface.

Example

public class MyApplication {
    public MyApplication
    // Register event handlers
    Session.SharedSession.RecordingStarted += new RecordingStarted(SharedSession_RecordingStarted);
    Session.SharedSession.RecordingStopped += new RecordingStopped(SharedSession_RecordingStopped);
    Session.SharedSession.ControlDeviceEventReceived += new ControlDeviceEventReceived(SharedSession_ControlDeviceEventReceived);
}
...
// event handlers
void SharedSession_RecordingStarted() {
    ...
}
void SharedSession_RecordingStopped() {
    ...
}
void SharedSession_ControlDeviceEventReceived(ControlDeviceEvent cdEvent) {
    ...
}

The Session class contains the following events:

• RecordingStarted - occurs when recording is started.
• RecordingStopped - occurs when recording is stopped, either on request or because of an error.
• ControlDeviceEventReceived - occurs when a control device event is received.

If your app is notified about session events, you can (among other tasks) implement a record button on your API. The appearance of the button reflects the current recording state (for example, a caption/image to indicate recording is started/stopped). The RecordingStarted and RecordingStopped events notify your app of changes in the recording state, which can be triggered by the user, an error, an idle timeout or any other cause, and enable you to update the appearance of your record button and your internal representation of the recording state.

The ControlDeviceEventReceived event notifies your app if a control device button was 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.

To receive VuiController events, your app must implement event handlers for the events that are exposed by the VuiController classes.

The VuiController class contains the following events:

• ProcessingStarted - called when the user starts their first utterance in any speech-enabled control and the speech recognition process starts.

• ProcessingFinished - called when the last utterance spoken is recognized and the GUI is updated with its results; the speech recognition process is finished, there are no more utterances to be processed.

• ProcessingStartedForControl - called when the user finishes their first utterance in a speech-enabled control and the speech recognition process starts. A reference to the control is supplied as the delegate parameter.

• ProcessingFinishedForControl - called when the last utterance for a speech-enabled control is recognized and the GUI is updated with the recognition results. A reference to the control is supplied as the delegate parameter.

• CommandRecognized – 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.

  placeholderValues - the placeholder identifier 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.

Important information

• These events are always fired in pairs; for every ProcessingStarted and ProcessingStartedForControl call there is always a corresponding ProcessingFinished or ProcessingFinishedForControl 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 form while speech recognition processing is ongoing (to make sure that no recognition results are lost). In this case, the ProcessingStarted and the ProcessingStopped events 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 ProcessingFinishedForControl event, you can make sure that all the relevant recognition results are displayed.

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

• The ProcessingStoppedForControl event is always fired for the control that has the speech focus (for which the ProcessingStartedForControl event was fired earlier). This guarantees that ProcessingStartedForControl and ProcessingStoppedForControl events are always fired in pairs for all controls.

• The ProcessingStartedForControl and ProcessingStoppedForControl callbacks can't track which controls have received recognized results.

Example of processing state events

Consider 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 ProcessingStartedForControl and ProcessingStoppedForControl events work in this scenario:

1. The user says this is a test when Field 1 has the speech focus: A ProcessingStartedForControl event is fired for Field 1.

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

3. When the recognition results for this is another test are displayed, speech recognition processing is finished, therefore a ProcessingFinished event is fired for the control which had the speech focus when the user started to say it, in this case Field 1.

4. The user didn't start saying anything when the speech focus was in Field 2. No ProcessingStartedForControl or ProcessingStoppedForControl events are fired for this control even though Field 2 contains the recognition results.

Conclusion: You can use the onProcessingStartedForControl and onProcessingStoppedForControl events for this scenario but they aren't reliable in the case of voice navigation or while recording is on.