javax.speech.recognition
Class RecognizerEvent

Object
  SpeechEvent
      EngineEvent
          RecognizerEvent

public class RecognizerEvent
extends EngineEvent

Event issued by a Recognizer to indicate a change in state or other activity. A RecognizerEvent is issued to each RecognizerListener attached to a Recognizer using the addRecognizerListener method in the Recognizer interface.

See Also:

Recognizer, RecognizerListener, addRecognizerListener, removeRecognizerListener

Field Summary

static int	CHANGES_COMMITTED Event issued before a Recognizer enters the RESUMED state when there are successful Grammar updates.
static int	CHANGES_REJECTED Event issued before a Recognizer enters the RESUMED state when there are unsuccessful Grammar updates.
static int	DEFAULT_MASK The default mask for events in this class.
static int	RECOGNIZER_BUFFERING Event issued when the Recognizer has detected that the internal audio buffer is free after a previous RECOGNIZER_NOT_BUFFERING event.
static int	RECOGNIZER_LISTENING Event issued when a Recognizer enters the LISTENING substate of the RESUMED state.
static int	RECOGNIZER_NOT_BUFFERING Event issued when the Recognizer has detected that the internal audio buffer is full.
static int	RECOGNIZER_PROCESSING Event issued when a Recognizer changes from the LISTENING substate to the PROCESSING substate to indicate that it is actively processing a recognition Result.
static int	RECOGNIZER_STOPPED Event issued when the Recognizer has processed all audio for the current audio stream.
static int	SPEECH_STARTED Event issued when a Recognizer detects the possible start of speech in the incoming audio.
static int	SPEECH_STOPPED Event issued when a Recognizer detects the possible end of speech or noise in the incoming audio that it previously indicated with a SPEECH_STARTED event.
static int	UNKNOWN_AUDIO_POSITION Value returned from the getAudioPosition method when the audio position is unknown or not supported.

Fields inherited from class EngineEvent

ENGINE_ALLOCATED, ENGINE_ALLOCATING_RESOURCES, ENGINE_DEALLOCATED, ENGINE_DEALLOCATING_RESOURCES, ENGINE_DEFOCUSED, ENGINE_ERROR, ENGINE_FOCUSED, ENGINE_PAUSED, ENGINE_RESUMED

Fields inherited from class SpeechEvent

DISABLE_ALL, ENABLE_ALL

Constructor Summary

RecognizerEvent(Recognizer source, int id, long oldEngineState, long newEngineState, Throwable problem, GrammarException grammarException, long audioPosition)
Constructs a RecognizerEvent to indicate a change in state or other activity.

Method Summary

long	getAudioPosition() Gets the audio position for this RecognizerEvent.
GrammarException	getGrammarException() Returns a non-null GrammarException for a CHANGES_REJECTED event.
String	paramString() Returns a parameter String that contains the event ID in text form.
String	toString() Returns a printable String.

Methods inherited from class EngineEvent

getEngineError, getNewEngineState, getOldEngineState

Methods inherited from class SpeechEvent

getId, getSource

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

RECOGNIZER_PROCESSING

public static final int RECOGNIZER_PROCESSING

Event issued when a Recognizer changes from the LISTENING substate to the PROCESSING substate to indicate that it is actively processing a recognition Result.

The transition occurs immediately before the RESULT_CREATED event is issued to ResultListeners.

The causes and timing of this event are described in the normal event cycle for a Recognizer.

See Also:

Recognizer, LISTENING, PROCESSING, ResultListener, RESULT_CREATED, getEngineState, getId, Constant Field Values

RECOGNIZER_LISTENING

public static final int RECOGNIZER_LISTENING

Event issued when a Recognizer enters the LISTENING substate of the RESUMED state.

This event occurs after a call to the resume method and an ENGINE_RESUMED event. It may also be proceeded by a CHANGES_COMMITTED or CHANGES_REJECTED event.

The transition to the PROCESSING state is triggered when the Recognizer detects speech in the incoming audio stream that may match an active Grammar.

The causes and timing of this event are described in the normal event cycle for a Recognizer.

See Also:

Recognizer, resume, RESUMED, ENGINE_RESUMED, LISTENING, PROCESSING, CHANGES_COMMITTED, CHANGES_REJECTED, getEngineState, getId, Constant Field Values

CHANGES_COMMITTED

public static final int CHANGES_COMMITTED

Event issued before a Recognizer enters the RESUMED state when there are successful Grammar updates.

This event occurs after a call to resume when changes to the definition and activatable property of all of a Recognizer's Grammars have been applied. The Recognizer waits in the LISTENING substate for incoming speech and uses the new Grammar definitions for recognition after entering the PROCESSING substate once speech is detected.

Immediately following the CHANGES_COMMITTED event, GRAMMAR_CHANGES_COMMITTED events are issued to the GrammarListeners of each changed Grammar.

If any errors are detected in any Grammar's definition during the resume, a CHANGES_REJECTED event is issued rather than CHANGES_COMMITTED.

See Also:

CHANGES_REJECTED, Recognizer, resume, LISTENING, PROCESSING, Grammar, GRAMMAR_CHANGES_COMMITTED, getEngineState, getId, Constant Field Values

CHANGES_REJECTED

public static final int CHANGES_REJECTED

Event issued before a Recognizer enters the RESUMED state when there are unsuccessful Grammar updates. This event occurs after a call to resume when changes to the definition and activatable property of all of a Recognizer's Grammars are normally applied.

If any errors are detected in any Grammar's definition during the resume, a CHANGES_REJECTED event is issued rather than CHANGES_COMMITTED. All Grammar updates are rejected and the Recognizer continues to use any previously committed Grammars. The getGrammarException method retrieves the associated GrammarException.

A GRAMMAR_CHANGES_REJECTED event is issued to all changed Grammars. This associates a non-null GrammarException with Grammars containing errors.

See Also:

getGrammarException, CHANGES_COMMITTED, Recognizer, resume, LISTENING, Grammar, GRAMMAR_CHANGES_COMMITTED, GRAMMAR_CHANGES_REJECTED, getEngineState, getId, Constant Field Values

SPEECH_STARTED

public static final int SPEECH_STARTED

Event issued when a Recognizer detects the possible start of speech in the incoming audio. Applications may use this event to display visual feedback to a user indicating that the Recognizer is PROCESSING.

It is sometimes difficult to quickly distinguish between speech and other noises (e.g. coughs, microphone bumps), so the SPEECH_STARTED event is not always followed by a Result.

If a RESULT_CREATED event is issued for the detected speech, it will usually occur soon after the SPEECH_STARTED event but may be delayed for a number of reasons including:

• The Recognizer may be slower than real time and lag audio input.
• The Recognizer may defer issuing a RESULT_CREATED until it is confident that it has detected speech that matches one of the active Grammars - in some cases the RESULT_CREATED event may be issued at the end of the spoken utterance.

Some Recognizers allow a user to speak more than one command without a break. In these cases, a single SPEECH_STARTED event may be followed by more than one RESULT_CREATED event and Result finalization before the SPEECH_STOPPED event is issued.

In longer speech, short pauses in the user's speech may lead to a SPEECH_STOPPED event followed by a SPEECH_STARTED event as the user resumes speaking. These events do not always indicate that the current Result will be finalized.

See Also:

Recognizer, LISTENING, PROCESSING, recognizerUpdate, SPEECH_STOPPED, getId, getAudioPosition, Result, RESULT_CREATED, Constant Field Values

SPEECH_STOPPED

public static final int SPEECH_STOPPED

Event issued when a Recognizer detects the possible end of speech or noise in the incoming audio that it previously indicated with a SPEECH_STARTED event. This event always follows a SPEECH_STARTED event. See that event description for more detail.

See Also:

Recognizer, recognizerUpdate, SPEECH_STARTED, getId, getAudioPosition, Constant Field Values

RECOGNIZER_NOT_BUFFERING

public static final int RECOGNIZER_NOT_BUFFERING

Event issued when the Recognizer has detected that the internal audio buffer is full. When this event is received, all audio is lost until a RECOGNIZER_BUFFERING event is issued.

This event, if it happens, most likely occurs in the PAUSED state. It may, however, occur in the LISTENING and PROCESSING substates of RESUMED if limited resources cause overflow of the audio buffer.

See Also:

recognizerUpdate, RECOGNIZER_BUFFERING, getAudioPosition, getId, PAUSED, RESUMED, LISTENING, PROCESSING, Constant Field Values

RECOGNIZER_BUFFERING

public static final int RECOGNIZER_BUFFERING

Event issued when the Recognizer has detected that the internal audio buffer is free after a previous RECOGNIZER_NOT_BUFFERING event. Audio is again processed after this event. This event follows a RECOGNIZER_NOT_BUFFERING event.

See Also:

recognizerUpdate, RECOGNIZER_NOT_BUFFERING, getId, getAudioPosition, Constant Field Values

RECOGNIZER_STOPPED

public static final int RECOGNIZER_STOPPED

Event issued when the Recognizer has processed all audio for the current audio stream. This event always occurs after an AUDIO_STOPPED event (indicating that the audio stream has ended) and after any ResultEvents for the associated audio.

See Also:

recognizerUpdate, AUDIO_STOPPED, getId, getAudioPosition, Constant Field Values

UNKNOWN_AUDIO_POSITION

public static final int UNKNOWN_AUDIO_POSITION

Value returned from the getAudioPosition method when the audio position is unknown or not supported.

See Also:

getAudioPosition, Constant Field Values

DEFAULT_MASK

public static final int DEFAULT_MASK

The default mask for events in this class.

The following events, in addition to events in EngineEvent.DEFAULT_MASK, are delivered by default: CHANGES_COMMITTED, CHANGES_REJECTED, RECOGNIZER_LISTENING, RECOGNIZER_PROCESSING, SPEECH_STARTED, SPEECH_STOPPED, RECOGNIZER_STOPPED.

See Also:

EngineEvent, EngineEvent.DEFAULT_MASK, CHANGES_COMMITTED, CHANGES_REJECTED, RECOGNIZER_LISTENING, RECOGNIZER_PROCESSING, SPEECH_STARTED, SPEECH_STOPPED, RECOGNIZER_STOPPED, setEngineMask, Constant Field Values

Constructor Detail

RecognizerEvent

public RecognizerEvent(Recognizer source,
                       int id,
                       long oldEngineState,
                       long newEngineState,
                       Throwable problem,
                       GrammarException grammarException,
                       long audioPosition)
                throws IllegalArgumentException

Constructs a RecognizerEvent to indicate a change in state or other activity.

oldEngineState and newEngineState are 0 if the Engine states are unknown or undefined.

problem applies to ENGINE_ERROR and must be null for other events.

grammarException applies to CHANGES_REJECTED and must be null for other events.

audioPosition applies to SPEECH_STARTED, SPEECH_STOPPED, RECOGNIZER_BUFFERING, and RECOGNIZER_NOT_BUFFERING. For these events, audioPosition must be a non-negative integer or UNKNOWN_AUDIO_POSITION. For all other events, audioPosition it must be UNKNOWN_AUDIO_POSITION.

Parameters:

source - the Recognizer that issued the event

id - the event identifier

oldEngineState - the Engine state prior to this event

newEngineState - the Engine state following this event

problem - non-null for ENGINE_ERROR, otherwise null

grammarException - non-null for CHANGES_REJECTED, otherwise null

audioPosition - the audio position for applicable events, otherwise UNKNOWN_AUDIO_POSITION

Throws:

IllegalArgumentException - if called with an inappropriate event identifier or an invalid parameter value

See Also:

getSource, getId, getOldEngineState, getNewEngineState, getEngineError, getGrammarException, getAudioPosition, ENGINE_ERROR, CHANGES_COMMITTED, CHANGES_REJECTED, SPEECH_STARTED, SPEECH_STOPPED, RECOGNIZER_NOT_BUFFERING, RECOGNIZER_BUFFERING, UNKNOWN_AUDIO_POSITION, resume

Method Detail

getGrammarException

public GrammarException getGrammarException()

Returns a non-null GrammarException for a CHANGES_REJECTED event.

This method applies to a CHANGES_REJECTED event. For all other events, this method returns null.

Returns:

a GrammarException object

See Also:

resume, CHANGES_REJECTED

getAudioPosition

public long getAudioPosition()

Gets the audio position for this RecognizerEvent. The audio position is the time in milliseconds measuring the amount of audio processed since the audio began.

Valid values when known are 0 and above. If the value is not known, a value of UNKNOWN_AUDIO_POSITION is returned.

This method is valid for the events SPEECH_STARTED, SPEECH_STOPPED, RECOGNIZER_BUFFERING, RECOGNIZER_NOT_BUFFERING. For all other events, this method returns UNKNOWN_AUDIO_POSITION;

Returns:

the audio position in milliseconds

See Also:

UNKNOWN_AUDIO_POSITION, SPEECH_STARTED, SPEECH_STOPPED, RECOGNIZER_BUFFERING, RECOGNIZER_NOT_BUFFERING

paramString

public String paramString()

Returns a parameter String that contains the event ID in text form.

This method is useful for event-logging and for debugging. The method toString may provide more detail.

Overrides:

paramString in class EngineEvent

Returns:

a String that contains the event ID in text form

See Also:

toString

toString

public String toString()

Returns a printable String. Useful for event-logging and debugging.

The method paramString also provides printable information.

Specified by:

toString in class SpeechEvent

Returns:

A printable string.

See Also:

paramString