javax.speech.recognition
Interface RecognizerProperties

All Superinterfaces:

EngineProperties

public interface RecognizerProperties
extends EngineProperties

Enables control of the properties of a Recognizer. The RecognizerProperties object is obtained by calling the getRecognizerProperties method of a Recognizer.

RecognizerProperties inherits the following behavior from the EngineProperties interface (described in detail in the EngineProperties documentation):

• Each property has a get and set method (JavaBeans property method patterns).
• Calls to set methods may be asynchronous (they may return before the property change takes effect). The Engine will apply a change as soon as possible.
• An EnginePropertyListener may be attached to receive EnginePropertyEvents.
• Engines may ignore changes to properties or apply maximum and minimum limits. If an Engine does not apply a property change request, this is reflected in the corresponding EnginePropertyEvent.
• The get methods return the current setting - not a pending value.
• Where appropriate, property settings are persistent across sessions.

SpeakerProfile Interaction

For Recognizers that support a SpeakerManager (see getSpeakerProfiles), the RecognizerProperties may be stored and loaded as part of the data associated with a SpeakerProfile. SpeakerManager methods that affect the current SpeakerProfile may also affect RecognizerProperties. EnginePropertyEvents will also occur in this context.

See Also:

getRecognizerProperties, EngineProperties, SpeakerManager, SpeakerProfile, getSpeakerProfiles

Field Summary

static int	ADAPT_PAUSED A value signifying that adaptation may occur while PAUSED.
static int	ADAPT_RESUMED A value signifying that adaptation may occur while RESUMED.
static int	ENDPOINT_AUTOMATIC A value signifying that no application action is required for endpointing.
static int	ENDPOINT_MANUAL A value signifying that the application must pause and resume audio for each utterance.
static int	ENDPOINT_PUSH_TO_START A value signifying that the endpoint is determined by a push-to-start approach.
static int	ENDPOINT_PUSH_TO_TALK A value signifying that the endpoint is determined by a push-to-talk approach.
static int	ENDPOINT_SPEECH_DETECTION A value signifying that the endpoint detection is based on the speech signal.
static int	MAX_ACCURACY A value signifying maximum accuracy vs. speed during recognition.
static int	MAX_CONFIDENCE A value signifying that maximum confidence is required for recognition.
static int	MAX_SENSITIVITY A value signifying maximum sensitivity to noise during recognition.
static int	MIN_ACCURACY A value signifying minimum accuracy vs. speed during recognition.
static int	MIN_CONFIDENCE A value signifying that minimum confidence is required for recognition.
static int	MIN_SENSITIVITY A value signifying minimum sensitivity to noise during recognition.
static int	NORM_ACCURACY A value signifying normal accuracy vs. speed during recognition.
static int	NORM_CONFIDENCE A value signifying that normal confidence is required for recognition.
static int	NORM_SENSITIVITY A value signifying normal sensitivity to noise during recognition.
static int	UNKNOWN_CONFIDENCE A value signifying that the confidence value is unknown.

Fields inherited from interface EngineProperties

MAX_PRIORITY, MAX_UNTRUSTED_PRIORITY, MIN_PRIORITY, NORM_TRUSTED_PRIORITY, NORM_UNTRUSTED_PRIORITY

Method Summary

int	getAdaptation() Gets the adaptation property.
int	getCompleteTimeout() Gets the completeTimeout property.
int	getConfidenceThreshold() Gets the confidenceThreshold property.
int	getEndpointStyle() Gets the endpointStyle property.
int	getIncompleteTimeout() Gets the incompleteTimeout property.
int	getNumResultAlternatives() Gets the numResultAlternatives property.
int	getPriority() Gets the priority property.
int	getSensitivity() Gets the sensitivity property.
int	getSpeedVsAccuracy() Gets the speedVsAccuracy property.
boolean	isResultAudioProvided() Gets the resultAudioProvided property.
boolean	isTrainingProvided() Gets the trainingProvided property.
void	setAdaptation(int adaptation) Sets the adaptation property.
void	setCompleteTimeout(int completeTimeout) Sets the completeTimeout property.
void	setConfidenceThreshold(int confidenceThreshold) Sets the confidenceThreshold property.
void	setEndpointStyle(int endpointStyle) Sets the endpointStyle property.
void	setIncompleteTimeout(int incompleteTimeout) Sets the incompleteTimeout property.
void	setNumResultAlternatives(int numResultAlternatives) Sets the numResultAlternatives property.
void	setPriority(int priority) Sets the priority property.
void	setResultAudioProvided(boolean resultAudioProvided) Sets the resultAudioProvided property.
void	setSensitivity(int sensitivity) Sets the sensitivity property.
void	setSpeedVsAccuracy(int speedVsAccuracy) Sets the speedVsAccuracy property.
void	setTrainingProvided(boolean trainingProvided) Sets the trainingProvided property.

Methods inherited from interface EngineProperties

addEnginePropertyListener, getBase, removeEnginePropertyListener, reset, setBase

Field Detail

UNKNOWN_CONFIDENCE

static final int UNKNOWN_CONFIDENCE

A value signifying that the confidence value is unknown.

See Also:

setConfidenceThreshold, Constant Field Values

MIN_CONFIDENCE

static final int MIN_CONFIDENCE

A value signifying that minimum confidence is required for recognition.

See Also:

setConfidenceThreshold, Constant Field Values

NORM_CONFIDENCE

static final int NORM_CONFIDENCE

A value signifying that normal confidence is required for recognition.

See Also:

setConfidenceThreshold, Constant Field Values

MAX_CONFIDENCE

static final int MAX_CONFIDENCE

A value signifying that maximum confidence is required for recognition.

See Also:

setConfidenceThreshold, Constant Field Values

MIN_SENSITIVITY

static final int MIN_SENSITIVITY

A value signifying minimum sensitivity to noise during recognition.

See Also:

setSensitivity, Constant Field Values

NORM_SENSITIVITY

static final int NORM_SENSITIVITY

A value signifying normal sensitivity to noise during recognition.

See Also:

setSensitivity, Constant Field Values

MAX_SENSITIVITY

static final int MAX_SENSITIVITY

A value signifying maximum sensitivity to noise during recognition.

See Also:

setSensitivity, Constant Field Values

MIN_ACCURACY

static final int MIN_ACCURACY

A value signifying minimum accuracy vs. speed during recognition.

See Also:

setSpeedVsAccuracy, Constant Field Values

NORM_ACCURACY

static final int NORM_ACCURACY

A value signifying normal accuracy vs. speed during recognition.

See Also:

setSpeedVsAccuracy, Constant Field Values

MAX_ACCURACY

static final int MAX_ACCURACY

A value signifying maximum accuracy vs. speed during recognition.

See Also:

setSpeedVsAccuracy, Constant Field Values

ADAPT_PAUSED

static final int ADAPT_PAUSED

A value signifying that adaptation may occur while PAUSED.

See Also:

setAdaptation, Engine.PAUSED, Constant Field Values

ADAPT_RESUMED

static final int ADAPT_RESUMED

A value signifying that adaptation may occur while RESUMED.

See Also:

setAdaptation, Engine.RESUMED, Constant Field Values

ENDPOINT_AUTOMATIC

static final int ENDPOINT_AUTOMATIC

A value signifying that no application action is required for endpointing. In this case, the application need only call resume once after allocate and after adding any RuleGrammars. The Recognizer finds endpoints within a continuous audio stream. This can apply to any of the endpoint styles as described in setEndpointStyle.

Some resource limited implementations may require ENDPOINT_MANUAL.

See Also:

setEndpointStyle, resume, allocate, RuleGrammar, ENDPOINT_MANUAL, Constant Field Values

ENDPOINT_MANUAL

static final int ENDPOINT_MANUAL

A value signifying that the application must pause and resume audio for each utterance. Some resource limited implementations may require the application to explicitly control the input audio stream with resume and pause for each utterance.

If the endpointStyle is ENDPOINT_MANUAL & ENDPOINT_PUSH_TO_TALK, the application should call resume when a button is pressed and call pause when the button is released.

If the endpointStyle is ENDPOINT_MANUAL & ENDPOINT_PUSH_TO_START, the application should call resume when a button is pressed and call pause when resultUpdate provides a ResultEvent with a FinalResult.

This style may not be combined with ENDPOINT_SPEECH_DETECTION. Implementations may support ENDPOINT_PUSH_TO_TALK and ENDPOINT_PUSH_TO_START with ENDPOINT_AUTOMATIC style.

See Also:

setEndpointStyle, resultUpdate, resume, pause, ResultEvent, FinalResult, ENDPOINT_AUTOMATIC, ENDPOINT_PUSH_TO_TALK, ENDPOINT_PUSH_TO_START, ENDPOINT_SPEECH_DETECTION, Constant Field Values

ENDPOINT_SPEECH_DETECTION

static final int ENDPOINT_SPEECH_DETECTION

A value signifying that the endpoint detection is based on the speech signal. In this case, the Recognizer determines where an utterance begins and ends using the speech signal itself. For example, a Recognizer can use differences in audio energy levels to determine the begin and end of speech.

See Also:

setEndpointStyle, Constant Field Values

ENDPOINT_PUSH_TO_TALK

static final int ENDPOINT_PUSH_TO_TALK

A value signifying that the endpoint is determined by a push-to-talk approach. With this approach, the user must explicitly push and hold a button (either physical or virtual) to signify the beginning and end of speech.

See the description of ENDPOINT_MANUAL for details.

See Also:

setEndpointStyle, ENDPOINT_MANUAL, Constant Field Values

ENDPOINT_PUSH_TO_START

static final int ENDPOINT_PUSH_TO_START

A value signifying that the endpoint is determined by a push-to-start approach. With this approach, the user must explicitly push a button (either physical or virtual) to signify the beginning of speech. The end of speech is determined automatically from the speech signal itself. For example, a Recognizer can use differences in audio energy levels to determine the end of speech.

See the description of ENDPOINT_MANUAL for details.

See Also:

setEndpointStyle, ENDPOINT_MANUAL, Constant Field Values

Method Detail

getAdaptation

int getAdaptation()

Gets the adaptation property.

Returns:

a constant used to control adaptation behavior

See Also:

setAdaptation

getCompleteTimeout

int getCompleteTimeout()

Gets the completeTimeout property.

Returns:

a timeout value in milliseconds

See Also:

setCompleteTimeout

getConfidenceThreshold

int getConfidenceThreshold()

Gets the confidenceThreshold property.

Returns:

an integer confidence threshold

See Also:

setConfidenceThreshold

getEndpointStyle

int getEndpointStyle()

Gets the endpointStyle property.

Returns:

an integer constant representing an endpoint style

See Also:

setEndpointStyle

getIncompleteTimeout

int getIncompleteTimeout()

Gets the incompleteTimeout property.

Returns:

a timeout value in milliseconds

See Also:

setIncompleteTimeout

getNumResultAlternatives

int getNumResultAlternatives()

Gets the numResultAlternatives property.

Returns:

the number of alternatives

See Also:

setNumResultAlternatives

getPriority

int getPriority()

Gets the priority property.

Specified by:

getPriority in interface EngineProperties

Returns:

the priority for this Engine instance

See Also:

setPriority

getSensitivity

int getSensitivity()

Gets the sensitivity property.

Returns:

the sensitivity value

See Also:

setSensitivity

getSpeedVsAccuracy

int getSpeedVsAccuracy()

Gets the speedVsAccuracy property.

Returns:

the value of this property

See Also:

setSpeedVsAccuracy

isResultAudioProvided

boolean isResultAudioProvided()

Gets the resultAudioProvided property.

Returns:

true if result audio is provided

See Also:

setResultAudioProvided

isTrainingProvided

boolean isTrainingProvided()

Gets the trainingProvided property.

Returns:

true if training information is provided

See Also:

setTrainingProvided

setAdaptation

void setAdaptation(int adaptation)
                   throws IllegalArgumentException

Sets the adaptation property. This value determines when a Recognizer may adapt to the audio signal.

Adaptation to the audio signal can improve recognition accuracy. However, it is sometimes better to ignore the audio when it does not represent normal operating conditions. For example, if music plays when PAUSED but not RESUMED, then adaptation while PAUSED may degrade recognition accuracy.

A value of ADAPT_PAUSED allows the Recognizer to adapt while PAUSED. A value of ADAPT_RESUMED allows the Recognizer to adapt while RESUMED. A value of (ADAPT_PAUSED | ADAPT_RESUMED) allows the Recognizer to always adapt.

The default value of this property is implementation dependent. Applications should set this value for interaction appropriate for the task.

The requested value may be rejected or limited.

Parameters:

adaptation - the desired adaptation value

Throws:

IllegalArgumentException - if the property value is not valid

See Also:

getAdaptation, ADAPT_PAUSED, ADAPT_RESUMED, PAUSED, RESUMED, addEnginePropertyListener

setCompleteTimeout

void setCompleteTimeout(int completeTimeout)
                        throws IllegalArgumentException

Sets the completeTimeout property. This timeout value, in milliseconds, determines the length of silence required following user speech before the Recognizer finalizes a Result (with a RESULT_ACCEPTED or RESULT_REJECTED event). The completeTimeout property is used when the speech is a complete match to an active Grammar. By contrast, the incompleteTimeout property is used when the speech is an incomplete match to an active Grammar.

A long completeTimeout value delays Result completion and therefore makes response time slow. A short completeTimeout value may lead to an utterance being broken up inappropriately. Reasonable completeTimeout values are typically in the range of 300 milliseconds (0.3 seconds) to 1000 milliseconds (1.0 seconds), depending on the application.

The default value of this property is implementation dependent. Applications should set this value for interaction appropriate for the task.

The requested value may be rejected or limited.

Parameters:

completeTimeout - the timeout value in milliseconds

Throws:

IllegalArgumentException - if the property value is not a positive integer

See Also:

getCompleteTimeout, setIncompleteTimeout, addEnginePropertyListener, RESULT_ACCEPTED, RESULT_REJECTED, Result

setConfidenceThreshold

void setConfidenceThreshold(int confidenceThreshold)
                            throws IllegalArgumentException

Sets the confidenceThreshold property. The confidenceThreshold value can vary between MIN_CONFIDENCE and MAX_CONFIDENCE. A value of NORM_CONFIDENCE is the default for the Recognizer. A value of MAX_CONFIDENCE requires the Recognizer to have maximum confidence in its Results or otherwise reject them. A value of MIN_CONFIDENCE requires only low confidence so fewer Results are rejected.

The requested value may be rejected or limited.

Parameters:

confidenceThreshold - a value specifying the confidence threshold

Throws:

IllegalArgumentException - if the property value is out of range

See Also:

getConfidenceThreshold, addEnginePropertyListener, MIN_CONFIDENCE, NORM_CONFIDENCE, MAX_CONFIDENCE, Result

setEndpointStyle

void setEndpointStyle(int endpointStyle)
                      throws IllegalArgumentException

Sets the endpointStyle property. The endpointStyle is set to an integer constant representing the endpoint style of the Recognizer. This determines how a Recognizer knows when an utterance begins and ends. An application may decide to change its style of interaction based on this value.

Acceptable input styles are ENDPOINT_SPEECH_DETECTION, ENDPOINT_PUSH_TO_TALK, and ENDPOINT_PUSH_TO_START. These values are mutually exclusive.

The input styles may be modified by the behavior styles ENDPOINT_AUTOMATIC and ENDPOINT_MANUAL. These values are mutually exclusive.

The constant descriptions provide more detail. Not all Recognizers support all styles. If more than one mutually exclusive style is specified, then the Recognizer will choose its preferred style.

The requested value may be rejected or limited.

Parameters:

endpointStyle - a value specifying the endpoint style

Throws:

IllegalArgumentException - if the property value is not valid

See Also:

getEndpointStyle, ENDPOINT_AUTOMATIC, ENDPOINT_MANUAL, ENDPOINT_SPEECH_DETECTION, ENDPOINT_PUSH_TO_TALK, ENDPOINT_PUSH_TO_START

setIncompleteTimeout

void setIncompleteTimeout(int incompleteTimeout)
                          throws IllegalArgumentException

Sets the incompleteTimeout property. The incompleteTimeout value, in milliseconds, determines the required length of silence following user speech after which a Recognizer finalizes a Result.

The incompleteTimeout applies when the speech prior to the silence is an incomplete match of the active Grammars. In this case, once the timeout is triggered, the partial result is rejected (with a RESULT_REJECTED event).

The incompleteTimeout also applies when the speech prior to the silence is a complete match of an active Grammar, but where it is possible to speak further and still match the Grammar. For example, in a Grammar for digit sequences for telephone numbers it might be legal to speak either 7 or 10 digits. If the user pauses briefly after speaking 7 digits then the incomplete timeout applies because the user may then continue with a further 3 digits.

By contrast, the completeTimeout is used when the speech is a complete match to an active Grammar and no further words can be spoken.

A long incompleteTimeout value delays Result completion and therefore slows response time. A short incompleteTimeout value may lead to an utterance being broken up inappropriately.

The incompleteTimeout is usually longer than the completeTimeout to allow users to pause mid-utterance (for example, to breathe).

The default value of this property is implementation dependent. Applications should set this value for interaction appropriate for the task.

The requested value may be rejected or limited.

Parameters:

incompleteTimeout - the timeout value in milliseconds

Throws:

IllegalArgumentException - if the property value is not a positive integer

See Also:

getIncompleteTimeout, setCompleteTimeout, addEnginePropertyListener, RESULT_REJECTED, Result

setNumResultAlternatives

void setNumResultAlternatives(int numResultAlternatives)
                              throws IllegalArgumentException

Sets the numResultAlternatives property. This property indicates the preferred maximum number of N-best alternatives in FinalResult objects. A value of 1 indicates that the application wants only the best result. A value of 0 indicates that the application wants all available alternatives.

Recognizers are not required to provide this number of alternatives for every Result and the number of alternatives may vary from Result to Result. Recognizers should only provide alternative tokens that are considered reasonable: that is, the alternatives should be above the confidenceThreshold property value (unless the Result is REJECTED).

Providing alternatives requires additional computing resources. Applications should only request the number of alternatives that they are likely to use.

The default value of this property is 1.

The requested value may be rejected or limited.

Parameters:

numResultAlternatives - the desired number of FinalRuleResult alternatives

Throws:

IllegalArgumentException - if the parameter is not a positive integer

See Also:

getNumResultAlternatives, getAlternativeTokens, addEnginePropertyListener, FinalResult, REJECTED

setPriority

void setPriority(int priority)
                 throws IllegalArgumentException

Sets the priority property.

The priority values range between MIN_PRIORITY and MAX_PRIORITY. The priority used may be lower than the priority requested (rejected or limited). In this case, the return value will differ from the value requested.

Trusted applications may use the full range of priority values. Untrusted applications have a maximum of MAX_UNTRUSTED_PRIORITY, which is less than MAX_PRIORITY.

The default priority values for trusted and untrusted applications are NORM_TRUSTED_PRIORITY and NORM_UNTRUSTED_PRIORITY, respectively.

The priority property should be used with care to avoid starvation of other applications.

Changing the priority may be asynchronous, so any resulting focus change may not occur immediately.

The priority property may determine the order in which Engine instances interact. For example, focus gain and loss may be affected by priority.

A trusted application could use a higher priority to avoid losing focus during a user's answer to an important question.

Specified by:

setPriority in interface EngineProperties

Parameters:

priority - the priority for this engine

Throws:

IllegalArgumentException - if the property value is out of range

See Also:

getPriority, EngineManager, addEnginePropertyListener, MIN_PRIORITY, NORM_TRUSTED_PRIORITY, NORM_UNTRUSTED_PRIORITY, MAX_UNTRUSTED_PRIORITY, MAX_PRIORITY

setResultAudioProvided

void setResultAudioProvided(boolean resultAudioProvided)

Sets the resultAudioProvided property. If set to true, the Recognizer is requested to provide audio with FinalResult objects. If available, the audio is provided through the getAudio methods of the FinalResult interface.

Some Recognizers that can provide audio for a FinalResult cannot provide audio for all Results. Applications must test audio availability for each individual Result as described in the getAudio methods.

A Recognizer that does not provide audio will limit the value to false. The default value for this property is false.

The requested value may be rejected or limited.

Parameters:

resultAudioProvided - the value for this property

See Also:

isResultAudioProvided, FinalResult, getAudio, addEnginePropertyListener

setSensitivity

void setSensitivity(int sensitivity)
                    throws IllegalArgumentException

Sets the sensitivity property. The sensitivity can vary between MIN_SENSITIVITY and MAX_SENSITIVITY. A value of NORM_SENSITIVITY is the default for the Recognizer. A value of MAX_SENSITIVITY makes the Recognizer more sensitive to quiet input, but also more sensitive to noise. A value of MIN_SENSITIVITY may require the user to speak louder, but makes the Recognizer less sensitive to background noise.

Some Recognizers set the gain automatically during use, or through a setup "Wizard". For these Recognizers, the sensitivity adjustment should be used only in extreme cases where the automatic settings are not adequate.

The requested value may be rejected or limited.

Parameters:

sensitivity - the value for this property

Throws:

IllegalArgumentException - if the property value is not valid

See Also:

getSensitivity, addEnginePropertyListener, MIN_SENSITIVITY, NORM_SENSITIVITY, MAX_SENSITIVITY

setSpeedVsAccuracy

void setSpeedVsAccuracy(int speedVsAccuracy)
                        throws IllegalArgumentException

Sets the speedVsAccuracy property. A value of NORM_ACCURACY is the default compromise between speed and accuracy for the Recognizer. A value of MIN_ACCURACY minimizes response time. A value of MAX_ACCURACY maximizes recognition accuracy.

Why are speed and accuracy a trade-off? A Recognizer determines what a user says by testing different possible sequences of words (with legal sequences being defined by the active Grammars). If the Recognizer tests more sequences it is more likely to find the correct sequence, but the additional processing makes it slower. Increasing Grammar complexity and decreasing the computer power both make this trade-off more important. Conversely, a simpler Grammar or more powerful computer make the trade-off less important.

The requested value may be rejected or limited.

Parameters:

speedVsAccuracy - the value for this property

Throws:

IllegalArgumentException - if the property value is out of range

See Also:

getSpeedVsAccuracy, addEnginePropertyListener, MIN_ACCURACY, NORM_ACCURACY, MAX_ACCURACY

setTrainingProvided

void setTrainingProvided(boolean trainingProvided)

Sets the trainingProvided property. If true, request a Recognizer to provide training information for FinalResult objects through the tokenCorrection method.

Not all Recognizers support training. Also, Recognizers that do support training are not required to support training data for all Results.

A Recognizer that does not support training will limit the value to false. The default value for this property is false.

The requested value may be rejected or limited.

Parameters:

trainingProvided - the value for this property

See Also:

isTrainingProvided, tokenCorrection, addEnginePropertyListener, FinalResult