| Platform SDK: Agent |
The Listening Tip is another speech input service provided by Microsoft Agent. When speech input is installed, Agent includes a special tooltip window that appears when the user presses the Listening hotkey or calls the Listen method. The Listening Tip appears only when the speech services are available. If no client has authored a voice command or successfully loads a speech engine, the Listening Tip does not appear. Further, both speech input and the Display Listening Tips option in the Advanced Character Options must be enabled for the tip to appear.
The following table summarizes the display of the Listening Tip when speech recognition is enabled.
| Action | Result |
|---|---|
| User presses the Listening mode hotkey or input-active calls the Listen method | The Listening Tip appears below the active client's character and displays:
-- CharacterName is listening -- If the client hasn't defined a VoiceCaption its Commands object, the value of its Caption property is used. The first line identifying the character is centered. The second line is left justified and breaks to a third line when it exceeds the Listening Tip's maximum width. If an input-active client of the character does not have a caption or defined voice parameters for its Commands object, the Listening Tip displays: -- CharacterName is listening -- If there are no visible characters, the Listening Tip appears adjacent to the character's taskbar icon and displays: -- CharacterName is listening -- If the speech recognition is still initializing, the Listening Tip displays: -- CharacterName is preparing to listen -- If the audio channel is busy, as when the character is audibly speaking or some other application is using the audio channel, the Listening Tip displays: -- CharacterName is not listening -- If there is no language-compatible speech engine installed for the input-active client's character, the Listening Tip displays the following, where Language represents the selected language of the character: -- CharacterName is not listening - If the audio device is not available for other reasons, such as when it is busy or there is some error in attempting to open the audio device, the following tip appears when the Listening mode is activated: -- CharacterName is not listening - If the input-active client application has not defined any Voice settings for commands and has also disabled voice parameters for Agent's global commands, this tip appears: CharacterName is not listening - If all characters are hidden, the Listening Tip displays the following text: CharacterName is listening - |
| User speaks a voice command | If the spoken text matches a client- or server-defined command, the Listening Tip appears below the active client's character and displays:
-- CharacterName is listening - However, when a recognition is passed back and the Listening mode has timed out, but the Listening Tip time-out has not, or if the Listening mode is still in effect, but the audio channel is not yet available (for example, the user is still holding the Listening key or the Listening mode has not timed out, because the character is speaking), the Listening Tip displays: CharacterName is not listening - When the spoken text matches a server-defined command, but the server does not act on it because the command has a low confidence score, the second line of the Listening Tip displays: Didn't understand your request. The first line is centered. The second line is left-justified and breaks to a third line when it exceeds the Listening Tip's maximum width. |
The Listening Tip automatically times out after being presented. If the "Heard" text time-out completes while the user is still holding down the hotkey, the tip reverts to the "listening" text unless the server receives another matching utterance. In this case, the tip displays the new "Heard" text and begins the time-out for that tip text. If the user releases the hotkey and the server is displaying the "Heard" text, the time-out continues and the Listening Tip window is hidden when the time-out interval elapses.
If the server has not yet attempted to load a speech recognition engine, the Listening Tip will not display. Similarly, if the user has disabled the display of the Listening Tip or disabled speech input in Advanced Character Options, the Listening Tip will not be displayed.
The Listening Tip does not appear when the pointer is over the character's taskbar icon. Instead, the standard notification tip window appears and displays the character's name.
Client applications cannot write directly to the Listening Tip, but you can specify alternative text that the server displays on recognition of a matching voice command. To do this, set the Confidence property and the new ConfidenceText property for the command. If spoken input matches the command, but the best match does not exceed the confidence setting, the server uses the text set in the ConfidenceText property in the tip window. If the client does not supply this value, the server displays the text (grammar) it matched.
The Listening Tip text appears in the language based on the input-active client's character language ID setting, regardless of whether there is a language-compatible speech recognition engine available.