javax.telephony.media.async
Interface Async_ASR

All Superinterfaces:

ASRConstants, MediaConstants, ResourceConstants

public interface Async_ASR

extends ASRConstants

Asynchronous version of ASR Resource methods.

The Automatic Speech Recognition (ASR) resource performs recognition and/or training. An ASR resource that performs recognition has associated with it a recognition algorithm which uses a context to recognize words from utterances presented in an input media stream, returning recognition results to the application.

Since:

JTAPI-1.4

See Also:

ASR Interface

Fields inherited from interface javax.telephony.media.ASRConstants

a_AutomaticTraining, a_ContextType, a_Date, a_DefaultRules, a_DetectionType, a_EchoCancellation, a_IntermediateResults, a_Label, a_Language, a_LoadableContext, a_LoadedContext, a_NumberRepetitions, a_NumberWordsRequested, a_OutputType, a_PrivateRules, a_PublicRules, a_RepeatRecognition, a_ResourceName, a_ResourceVendor, a_ResourceVersion, a_ResultPresentation, a_Rules, a_Size, a_SpeakerType, a_SpecificUtterance, a_Spotting, a_Trainable, a_Training, a_TrainingModifiable, a_TrainingType, a_UtteranceType, a_UtteranceValidation, a_Variant, e_BadContainerName, e_BadContext, e_Exists, e_IncorrectContext, e_NoExists, e_NotSupported, ev_ContextCopy, ev_ContextCreate, ev_ContextGetParameters, ev_ContextRemove, ev_ContextSetParameters, ev_GetFinalResults, ev_GetResults, ev_GetRuleExpansion, ev_Idle, ev_IntermediateResultsReady, ev_InvalidUtterance, ev_RecognitionStarted, ev_Recognize, ev_RetrieveRecognition, ev_SetRuleExpansion, ev_Start, ev_Stop, ev_UpdateParameters, ev_ValidUtterance, ev_WordCommit, ev_WordCreate, ev_WordDeleteLastUtterance, ev_WordDeleteTraining, ev_WordDestroy, ev_WordTrain, p_ActiveContexts, p_ActiveRules, p_ActiveWords, p_AutomaticTraining, p_ContextType, p_DetectionType, p_Duration, p_EchoCancellation, p_EnabledEvents, p_FinalTimeout, p_GrammarBargeInThreshold, p_InitialTimeout, p_Label, p_Language, p_LoadedContexts, p_LoadedWords, p_NumberRepetitions, p_NumberWordsRequested, p_OutputType, p_PlayInput, p_PrivateRules, p_PublicRules, p_ResultPresentation, p_ResultType, p_Rules, p_Size, p_SpeakerType, p_SpecificUtterance, p_Spotting, p_StartPaused, p_State, p_StoreInput, p_TopChoices, p_Trainable, p_TrainingType, p_UpdateParametersList, p_UtteranceType, p_Variant, q_Complete, q_Failure, q_InitialTimeout, q_Rejected, q_Silence, q_Stop, q_Success, q_Unsuccessful, q_Warning, rtca_Idle, rtca_Start, rtca_Stop, rtca_UpdateParameters, rtcc_GrammarBargeIn, rtcc_InvalidUtterance, rtcc_Recognize, rtcc_RecognizeStarted, rtcc_Silence, rtcc_SpecificUtterance, rtcc_SpeechDetected, rtcc_TrainStarted, rtcc_ValidUtteranceFinal, rtcc_ValidUtteranceFound, rtcc_WordTrain, rtcc_WordTrained, v_AddTraining, v_Class, v_Collision, v_Complete, v_Continuous, v_Dependent, v_Discrete, v_Final, v_FromResource, v_Garbage, v_GrammarTag, v_Identification, v_Idle, v_Immutable, v_Inconsistent, v_Independent, v_Intermediate, v_Mutable, v_Noisy, v_Normal, v_NotModifiable, v_NotReady, v_Phonetic, v_Ready, v_RecognitionPaused, v_Recognizing, v_ResultsAvailable, v_Retrain, v_Silence, v_Speech, v_Success, v_Text, v_ToResource, v_ToResourceTraining, v_Training, v_TrainingPaused, v_TypeI, v_TypeII, v_Verification, v_WordTrained

Fields inherited from interface javax.telephony.media.ResourceConstants

e_Disconnected, FOREVER, q_Disconnected, q_RTC, rtcc_Disconnected, rtcc_TriggerRTC, v_Forever

Fields inherited from interface javax.telephony.media.MediaConstants

e_OK, q_Duration, q_Standard

Method Summary

Async_ASREvent	async_contextCopy(java.lang.String contextResource, java.lang.String containerContext, Symbol direction) Copy a Context from a Resource to a Container, or from a Container to a Resource.
Async_ASREvent	async_contextCreate(java.lang.String resourceContext, Symbol trainingType, java.util.Dictionary contextParams) Creates a new context on the ASR Resource.
Async_ASREvent	async_contextGetParameters(java.lang.String resourceContext, Symbol[] keys) Retrieve context parameter values for a Context loaded in this resource.
Async_ASREvent	async_contextRemove(java.lang.String resourceContext) Remove an existing Context from an ASR Resource.
Async_ASREvent	async_contextSetParameters(java.lang.String resourceContext, java.util.Dictionary contextParams) This function sets the parameters associated with a particular Context that is loaded on a Resource.
Async_ASREvent	async_getFinalResults() Non-blocking version of getFinalResults().
Async_ASREvent	async_getResults() Non-blocking version of getResults().
Async_ASREvent	async_getRuleExpansion(java.lang.String grammarContext, java.lang.String ruleName) Non-blocking version of getRuleExpansion().
Async_ASREvent	async_idleASR() Non-blocking version of idleASR().
Async_ASREvent	async_recognize(RTC[] rtcs, java.util.Dictionary optargs) Non-blocking version of recognize().
Async_ASREvent	async_setRuleExpansion(java.lang.String grammarContext, java.lang.String ruleName, java.lang.String ruleExpansion) Non-blocking version of setRuleExpansion().
Async_ASREvent	async_startASR() Non-blocking version of startASR().
Async_ASREvent	async_stopASR() Non-blocking version of stopASR().
Async_ASREvent	async_updateParameters() Non-blocking verions of updateParameters().
Async_ASREvent	async_wordCommit(java.lang.String wordContext, java.lang.String wordTemp, java.lang.String wordString) Commits a Word, as trained, into a Context.
Async_ASREvent	async_wordCreate(java.lang.String wordContext, java.lang.String wordTemp) Create a new Word within a loaded Context.
Async_ASREvent	async_wordDeleteLastUtterance(java.lang.String wordContext, java.lang.String wordTemp) Prevent the previous utterance from contributing to training.
Async_ASREvent	async_wordDeleteTraining(java.lang.String wordContext, java.lang.String wordString) Delete all training associated with a Word in the specified Context.
Async_ASREvent	async_wordDestroy(java.lang.String wordContext, java.lang.String wordString) Remove a word from a loaded Context.
Async_ASREvent	async_wordTrain(java.lang.String wordContext, java.lang.String wordString) Train a Word in a Context.

Method Detail

async_recognize

public Async_ASREvent async_recognize(RTC[] rtcs,
                                      java.util.Dictionary optargs)

Non-blocking version of recognize().

Initiate speech recognition on the ASR resource. The returned event contains only the highest-probablility result. That is, it contains at most one TokenSequence.

Parameters:

rtcs - a RTC[] containing RTCs to be in effect during this call.

optargs - a Dictionary containing optional arguments.

Returns:

an Async_ASREvent

See Also:

ASREvent

async_getResults

public Async_ASREvent async_getResults()

Non-blocking version of getResults().

Retrieve intermediate recognition results and do not reset the recognizer. This method is valid whenever partial results are ready. The recognizer can be in either of state Recognizing or ResultsReady.

Returns:

an async_ASREvent

async_getFinalResults

public Async_ASREvent async_getFinalResults()

Non-blocking version of getFinalResults().

Retrieve recognition results and reset the recognizer.

Pre-conditions

Recognizer must be in the ResultsAvailable state.

Post-conditions

Recognizer is in the Idle state.

This is roughly equivalent to getResults() followed by triggerRTC(ASR.rtca_Idle).

Returns:

an async_ASREvent

async_startASR

public Async_ASREvent async_startASR()

Non-blocking version of startASR().

Starts a recognizer that is in a paused state. The Paused states are v_RecognitionPaused and v_TrainingPaused; the Recognizer moves to the states v_Recognizing and v_Training, respectively.

Returns:

an async_ASREvent

async_stopASR

public Async_ASREvent async_stopASR()

Non-blocking version of stopASR().

Stops the Recognizer when it is in the "Recognizing" or "Training" states. The recognizer transitions to the next state as if though they had completed execution. For example, the ASR resource would move from v_Recognizing to v_ResultsAvailable.

Returns:

an async_ASREvent

async_idleASR

public Async_ASREvent async_idleASR()

Non-blocking version of idleASR().

Forces a Recognizer into the Idle state.
Is this a transaction? or a void return?

The function is valid at any time, and is commonly used to move a Recognizer from the v_ResultsAvailable state into the v_Idle state without retrieving results from the Recognizer. Note that on entry to the Idle state, any recognition results or uncommitted training data is lost.

This function is also available as ASR.rtca_idle.

Returns:

an async_ASREvent

async_updateParameters

public Async_ASREvent async_updateParameters()

Non-blocking verions of updateParameters().

Set resource parameters according to p_UpdateParametersList.

This function (also available as ASR.rtca_updateParameters) is useful for barge-in scenarios, where the timeout values change after the prompt has completed playing.

If p_UpdateParametersList is not set or empty, then nothing is done and this method returns normally.

Returns:

an async_ASREvent

async_getRuleExpansion

public Async_ASREvent async_getRuleExpansion(java.lang.String grammarContext,
                                             java.lang.String ruleName)

Non-blocking version of getRuleExpansion(). Retrieve the expansion of a rule from a Grammar Context.

For a Grammar Context loaded on a resource, this method retrieves the current expansion of the rule RuleName in the Grammar Context GrammarContextName. The rule expansion is returned as part of the completion event for this function and is available using ASREvent.getRuleExpansion().

Parameters:

grammarContext - the name of a loaded grammar Context.

ruleName - a String that names the rule to be expanded.

Returns:

an async_ASREvent

async_setRuleExpansion

public Async_ASREvent async_setRuleExpansion(java.lang.String grammarContext,
                                             java.lang.String ruleName,
                                             java.lang.String ruleExpansion)

Non-blocking version of setRuleExpansion(). Set the expansion of a rule in a Grammar Context.

For a loaded Grammar Context, this function sets the rule expansion of the rule ruleName to the rule expansion given in the ruleExpansion argument. The syntax of RuleExpansion is defined by the JSGF grammar specification language.

Parameters:

grammarContext - a loaded Context.

ruleName - a String that names the rule being defined.

ruleExpansion - a String containing the rule expansion.

Returns:

an async_ASREvent

async_wordCommit

public Async_ASREvent async_wordCommit(java.lang.String wordContext,
                                       java.lang.String wordTemp,
                                       java.lang.String wordString)

Commits a Word, as trained, into a Context. Invoked when sufficient information has been collected to indicate that the Context may be permanently modified based on the updated training information.

The argument tempWord identifies the Word to be committed. When an utterance corresponding to that Word is detected, the recognizer will return wordString as the result. wordString is not the return value of the function -- wordString is the value the Recognizer will return as an answer in the Token field in the result object. wordString is permanent -- once set, the association between the Word and wordString cannot be changed. wordString is not necessarily an exact transcription of the utterance; in most cases, an arbitrary String is used.

For example, in a scenario where arbitrary voice labels are associated with a telephone number, the actual transcription is unknown. wordString can be an arbitrary index, and that index can used by the application to find the correct telephone number.

If this function is used to commit additional training to an already-existing Word, then wordTemp should be the permanent name for the Word; in that case, the value of wordString is ignored.

Parameters:

wordContext - the Context to which this word is committed.

wordTemp - a String that identifes the word to commit.

wordString - the permanent String to identify this word.

Returns:

an async_ASREvent

async_wordCreate

public Async_ASREvent async_wordCreate(java.lang.String wordContext,
                                       java.lang.String wordTemp)

Create a new Word within a loaded Context. The Word is accessed by using wordTemp, a temporary identifier. This method can only be used with Recognizers that support Context modification. Creating a Word adds it to the Context's p_WordList parameter.

Parameters:

wordContext - the Context in which Word is created.

wordTemp - a String containing the temporary name of the word.

Returns:

an async_ASREvent

async_wordDeleteLastUtterance

public Async_ASREvent async_wordDeleteLastUtterance(java.lang.String wordContext,
                                                    java.lang.String wordTemp)

Prevent the previous utterance from contributing to training. The most recent utterance associated with train() is not used as the training of a Word.

This method must be issued before any new training is made or before the training is committed to the Context. That is, this method must be issued before any other train(), and commit() method; either of those methods makes the utterance part of the permanent training of the Word.

Parameters:

wordContext - the Context in which the work is being trained.

wordTemp - the String that identifies the word being trained.

Returns:

an async_ASREvent

async_wordDeleteTraining

public Async_ASREvent async_wordDeleteTraining(java.lang.String wordContext,
                                               java.lang.String wordString)

Delete all training associated with a Word in the specified Context.

If the Word has been committed, then wordString must be the permanent name of the Word. If the Word has not been committed, then wordString must be the temporary name.

Parameters:

wordContext - the Context from which the training is deleted.

wordString - the String that idenifies word to be deleted.

Returns:

an async_ASREvent

async_wordDestroy

public Async_ASREvent async_wordDestroy(java.lang.String wordContext,
                                        java.lang.String wordString)

Remove a word from a loaded Context. This ASR Resource must support Context modification. Destroying a word will remove it from the Context's p_WordList parameter.

If the Word has been committed, then wordString must be the permanent name of the Word. If the Word has not been committed, then wordString must be the temporary name.

Parameters:

wordContext - the Context from which the Word is removed.

wordString - the String that identifies the word.

Returns:

an async_ASREvent

async_wordTrain

public Async_ASREvent async_wordTrain(java.lang.String wordContext,
                                      java.lang.String wordString)

Train a Word in a Context. The Recognizer collects audio information (or other information; p_TrainingType), and associates this information with the Word.

The Word might be one that has been trained before, or one that has just been created. If the Word has been committed, then wordString must be the permanent name of the Word. If the Word has not been committed, then wordString must be the temporary name.

Not all Recognizers can add additional training to a Word that has already been committed to a Context. The attribute a_TrainingModifiable may be queried to determine the Recognizer's abilities:
v_NotModifiable means that training cannot be modified.
v_Retrain means that retraining the Word is possible, but only by performing a asrTrain.deleteTraining() and retraining the Word entirely.
v_AddTraining means that additional training may be added to a Word by using the asrTrain.train() command.

Some Recognizers may perform training automatically, issuing prompts and collecting utterances until a sufficient number of good utterances have been collected. Such Recognizers, which have the attribute a_AutomaticTraining set to true, will run in automatic mode when the parameter p_AutomaticTraining is set to true. When training is over, they will issue a single completion event. The parameter p_NumberRepetitions, available in some Recognizers, may be set to dictate how many training utterances the Recognizer should use in AutomaticTraining mode.

Recognizers have different requirements for the minimum number of utterances necessary to provide training for a new Word; if the application is collecting utterances, the application will need to provide at least that many utterances to the Recognizer. The range of the p_NumberRepetitions parameter may be queried to determine this number, which is indicated by the minimum number of repetitions. The Recognizer may also have an upper limit on the number of utterances it can use for training; the p_NumberRepetitions parameter may also be queried to determine this number, which is the maximum number of repetitions.

Different types of training may be available on Recognizers; the a_TrainingType attribute indicates which types are available. The parameter p_TrainingType is used to set the type when more than one type is supported: p_TrainingType takes on the values v_Speech, v_Text, and v_Phonetic to describe the training input. Recognizers that accept training of type v_Phonetic use IPA as their text input for training. If p_TrainingType is set to v_Text or v_Phonetic, the dictionary entry p_TrainingInfo must also be present. This array of String will contain either the text or phonetic representation of the training material, as appropriate.

Parameters:

wordContext - the Context in which the word is trained.

wordString - a String that identifies the word to be trained.

Returns:

an async_ASREvent

async_contextCopy

public Async_ASREvent async_contextCopy(java.lang.String contextResource,
                                        java.lang.String containerContext,
                                        Symbol direction)

Copy a Context from a Resource to a Container, or from a Container to a Resource. This method can either store a loaded Context into a Container or load a context into the Resource.

The method contextCreate must be used to create the Context on the resource before using this method. If not, should we auto-define that Context? or should we define the Exception that is thrown?

The direction Symbol specifies whether the copy is from a resource to a container (v_FromResource) or from a container to a resource (v_ToResource).

To copy a Context from a Container to the Resource for the purpose of training, then the symbol v_ToResourceTraining should be used.

When copying a Context to the Resource, the argument resourceContext assigns a name to the Context. This name is used to identify the Context as loaded in the Resource. It does not need to be the same name used to identify the Context in a Container.

This is a non-destructive copy; the source copy of the Context is unaffected. If a Context of the same name already exists at the destination, it will be overwritten and lost. If the destination is a container, a new Context Object will be created to accommodate the Context if necessary. If the destination is an ASR Resource, and the Resource currently has a Context, and the Resource does not support multiple Contexts or the Resource has no room for this Context the copy will fail. In such cases the application must take corrective action, e.g., free up room on the ASR Resource by performing a asrContext.remove().

A Context copied into the Resource is inactive, it joins the set of inactive contexts.

Parameters:

contextResource - a Context within the ASR Resource.

containerContext - a String containing the name of the container context.

direction - a Symbol indicating the direction and type of copy. Must be one of ASRConstants.v_ToResource, ASRConstants.v_FromResource, or ASRConstants.v_ToResourceTraining.

Returns:

an async_ASREvent

async_contextCreate

public Async_ASREvent async_contextCreate(java.lang.String resourceContext,
                                          Symbol trainingType,
                                          java.util.Dictionary contextParams)

Creates a new context on the ASR Resource. A new context is created on the ASR Resource and is associated with the name of the supplied Context. The Context object should be used for all further operations on that context.

The ASR Resource implementation must support Context modification.

The trainingType argment indicates the type of input used to perform training. The possible values are: v_Speech, v_Phonetic, v_Text

Any context parameter -- including those that are normally read-only and cannot be written by the application - may be set during the time of creation by sending the appropriate Dictionary entry in contextParms.

Parameters:

resourceContext - a Context to be created in the Resource.

trainingType - a Symbol that identifies the type of input to be used for training this Context.

contextParams - a Dictionary containing the context parameters.

Returns:

an async_ASREvent

async_contextGetParameters

public Async_ASREvent async_contextGetParameters(java.lang.String resourceContext,
                                                 Symbol[] keys)

Retrieve context parameter values for a Context loaded in this resource.

If a key refers to a Parameter that is not present, or the Context has no meaning associated with a particular Symbol, or that parameter cannot be returned, then the key is ignored, no error is generated, and that key does not appear returned Dictionary.

If there is not ASR Resource configured in this MediaService, or if the ASR Resource cannot return parameters for the given Context, or if the Context is not loaded in the ASR Resource, then null is returned.

Parameters:

resourceContext - the Context from which parameters are retrieved

keys - an array of Symbols identifying the requested parameters.

Returns:

an async_ASREvent

async_contextRemove

public Async_ASREvent async_contextRemove(java.lang.String resourceContext)

Remove an existing Context from an ASR Resource. The Context which is removed is lost.

To preserve a Context, copy it to a Container using the contextCopy() method.

Parameters:

resourceContext - the Context to be removed.

Returns:

an async_ASREvent

async_contextSetParameters

public Async_ASREvent async_contextSetParameters(java.lang.String resourceContext,
                                                 java.util.Dictionary contextParams)

This function sets the parameters associated with a particular Context that is loaded on a Resource.

Parameters:

resourceContext - the Context on which parameters are to be set.

contextParams - a Dictionary of parameters to set.

Returns:

an async_ASREvent