Modules | Files | Inheritance Tree | Inheritance Graph | Name Index
module GNOME::Speech::Recognition
interface Recognizer
Files: GNOME_Speech.idl
GNOME-Speech-Recognition-Recognizer-inheritance GNOME-Speech-Engine.html GNOME-Speech-SpeechObject.html Bonobo-Unknown.html
Operations Summary:
 voidaddResultListener(in ResultListener listener)
 voidremoveResultListener(in ResultListener listener)
 voidcommitChanges() raises
 voiddeleteRuleGrammar(in RuleGrammar grammar) raises
 voidforceFinalize(in boolean flush) raises
DictationGrammargetDictationGrammar(in string name) raises
RecognizerPropertiesgetRecognizerProperties()
RuleGrammargetRuleGrammar(in string name) raises
SpeakerManagergetSpeakerManager() raises
RuleGrammarArraylistRuleGrammars() raises
 booleanisGrammarTypeSupported(in GrammarType type)
RuleGrammarloadGrammarFromStream(in GrammarType type, in InputStream inputStream) raises
RuleGrammarloadGrammarFromURL(in GrammarType type, in GrammarURL urlContext, in string grammarName) raises
RuleGrammarloadGrammarFromURLWithImports(in GrammarType type, in GrammarURL urlContext, in string grammarName, in boolean loadImports, in boolean reloadGrammars, in GrammarArray loadedGrammars) raises
RuleGrammarnewRuleGrammar(in string name) raises
GrammarreadVendorGrammar(in InputStream input) raises
 voidwriteVendorGrammar(in OutputStream output, in Grammar grammar) raises
 ResultreadVendorResult(in InputStream input) raises
 voidwriteVendorResult(in OutputStream output, in Result result) raises
 voidreleaseFocus() raises
 voidrequestFocus() raises
 voidsuspend() raises

Consts Inherited from Engine
DEALLOCATED, ALLOCATING_RESOURCES, ALLOCATED, DEALLOCATING_RESOURCES, PAUSED, RESUMED

Operations Inherited from Engine
addEngineListener, removeEngineListener, allocate, deallocate, getAudioManager, getEngineModeDesc, getEngineProperties, getEngineState, getVocabManager, pause, resume, testEngineState, waitEngineState

Operations Inherited from Bonobo::Unknown
ref, unref, queryInterface

Operation Details:
 void addResultListener(in ResultListener listener)

Request notifications of all events for all Result produced by this Recognizer. An application can attach multiple ResultListeners to a Recognizer. A listener is removed with the removeResultListener method.

ResultListeners attached to a Recognizer are the only ResultListeners to receive the RESULT_CREATED event and all subsequent events.

ResultListener objects can also be attached to any Grammar or to any Result. A listener attached to the Grammar receives all events that match that Grammar following a GRAMMAR_FINALIZED event. A listener attached to a Result receives all events for that result from the time at which the listener is attached.

A ResultListener can be attached or removed in any Engine state.

Parameters:
listener - the listener to add.
See Also:
removeResultListener
Grammar#addResultListener
Result#addResultListener
ResultEvent#RESULT_CREATED
ResultEvent#GRAMMAR_FINALIZED


 void removeResultListener(in ResultListener listener)

A ResultListener can be attached or removed in any Engine state.

Parameters:
listener - the listener to remove.
See Also:
addResultListener
Result#removeResultListener
Grammar#removeResultListener


 void commitChanges() raises (GrammarException, EngineStateError)

Commit changes to all loaded grammars and all changes of grammar enabling since the last commitChanges. Because all changes are applied atomically (all at once) the application does not need to be concerned with intermediate states as it changes grammar definitions and enabling.

The commitChanges call first checks that all the loaded grammars are legal. If there are any problems with the current definition of any RuleGrammar an exception is thrown. Problems might include undefined rule name, illegal recursion and so on (see the Java Speech Grammar Format Specification and the GrammarSyntaxDetail class documentation for details).

The commitChanges call is asynchronous (the changes have not necessarily been committed when the call returns). When the changes have been committed, a CHANGES_COMMITTED event is issued to all RecognizerListeners and to the GrammarListeners of all changed Grammars.

Immediately following the CHANGES_COMMITTED event, a GRAMMAR_CHANGES_COMMITTED GrammarEvent is issued to the GrammarListeners of all changed grammars.

The roll of commitChanges in applying grammar changes is described * in the documentation for the Grammar interface. The effect of the commitChanges method upon Recognizer states is described above. The use of suspend with commitChanges and their use for processing asynchronous non-speech events are also described above.

It is not an error to commitChanges when no grammars have been changed. However, the Recognizer performs state transitions in the same way as when grammars are changed.

The commitChanges method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

See Also:
LISTENING
PROCESSING
SUSPENDED
suspend
RecognizerEvent#CHANGES_COMMITTED


 void deleteRuleGrammar(in RuleGrammar grammar) raises (IllegalArgumentException, EngineStateError)

Delete a RuleGrammar from the Recognizer. The grammar deletion only takes effect when all grammar changes are committed.

Recognizers may chose to ignore the deletion of built-in grammars.

The deleteRuleGrammar method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Parameters:
grammar - the rule grammar to delete.
See Also:
commitChanges
RecognizerEvent#CHANGES_COMMITTED


 void forceFinalize(in boolean flush) raises (EngineStateError)

If the Recognizer is in the PROCESSING state (producing a Result), force the Recognizer to immediately complete processing of that result by finalizing it. It is acceptable behavior for a Recognizer to automatically reject the current result.

The flush flag indicates whether the recognizer's internally buffered audio should be processed before forcing the finalize. Applications needing immediate cessation of recognition should request a flush. If the force finalize is a response to a user event (e.g. keyboard or mouse press) then the buffer is typically not flushed because incoming speech from a user could be lost.

The state behavior of the Recognizer is the same as if the Result had been finalized because of end-of-utterance. The Recognizer will transition to the SUSPENDED state.

The forceFinalize method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Parameters:
flush - whether the recognizer's internally buffered audio should be processed before forcing the finalize.


DictationGrammar getDictationGrammar(in string name) raises (EngineStateError)

Return the DictationGrammar for a Recognizer. Typically, the name parameter is null to get access to the default DictationGrammar for the Recognizer.

If the Recognizer does not support dictation, or if it does have a DictationGrammar with the specified name, then the method returns null.

An application can determine whether the Recognizer supports dictation by calling the isDictationGrammarSupported method of the RecognizerModeDesc.

Note: the @name parameter is provided for future extension of the API to allow more than one DictationGrammar to be defined.

The getDictationGrammar method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Parameters:
name - provided for future extension of the API to allow more than one DictationGrammar to be defined.
Return:
the DictationGrammar for a Recognizer.
See Also:
RecognizerModeDesc#isDictationGrammarSupported


RecognizerProperties getRecognizerProperties()

Return the RecognizerProperties object. The method returns exactly the same object as the getEngineProperties method in the Engine interface. However, with the getRecognizerProperties method, an application does not need to cast the return value.

The RecognizerProperties are available in any state of an Engine. However, changes only take effect once an engine reaches the ALLOCATED state.

Return:
the RecognizerProperties object for this engine.
See Also:
Engine#getEngineProperties


RuleGrammar getRuleGrammar(in string name) raises (EngineStateError)

Get the RuleGrammar with the specified name. Returns null if the grammar is not known to the Recognizer.

The getRuleGrammar method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Parameters:
name - the name of the grammar to be returned.
Return:
a RuleGrammar reference or null.


SpeakerManager getSpeakerManager() raises (SecurityException)

Return an object which provides management of the speakers of a Recognizer. Returns null if the Recognizer does not store speaker data - that is, if it is a speaker-independent recognizer in which all speakers are handled the same.

A getSpeakerManager returns successfully in any state of a Recognizer. The SpeakerManager methods that list speakers and set the current speaker operate in any Recognizer state but only take effect in the ALLOCATED state. This allows an application can set the initial speaker prior to allocating the engine. Other methods of the SpeakerManager only operate in the ALLOCATED state.

Return:
the SpeakerManager for this Recognizer.


RuleGrammarArray listRuleGrammars() raises (EngineStateError)

List the RuleGrammars known to the Recognizer. Returns null if there are no grammars.

The listRuleGrammars method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Return:
the RuleGrammars known to the Recognizer.


 boolean isGrammarTypeSupported(in GrammarType type)

Return an indication of whether this Recognizer supports this grammar type.

Parameters:
type - the type of the grammar being checked.
Return:
an indication of whether this Recognizer supports this grammar type.
See Also:
GRAMMAR_JSGF
GRAMMAR_SRGS


RuleGrammar loadGrammarFromStream(in GrammarType type, in InputStream inputStream) raises (GrammarException, IOException, EngineStateError)

Create a RuleGrammar for the grammar formatted text provided by the InputStream. If the grammar contained in the Reader already exists, it is over-written. The new grammar is used for recognition only after changes are committed.

The caller is responsible for determining the character encoding of the formatted document. The character encoding information contained in the grammar format header is ignored.

The loadGrammar methods operate as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Parameters:
type - the type of the grammar being loaded.
inputStream - the InputStream from which the grammar text is loaded.

Return:
a RuleGrammar from grammar formatted text provided by the InputStream.
See Also:
loadGrammarFromURL
loadGrammarFromURLWithImports


RuleGrammar loadGrammarFromURL(in GrammarType type, in GrammarURL urlContext, in string grammarName) raises (GrammarException, IOException, MalformedURLException, EngineStateError)

Load a RuleGrammar and its imported grammars from grammar formatted text from URLs or from system resources. The loaded grammars are used for recognition only after changes are committed.

The method returns a reference to the named RuleGrammar. The method never returns null since an exception is thrown if grammarName cannot be loaded successfully.

The method attempts to load all imports of grammarName, all imports of the imported grammars, and so on. This recursive load stops when grammars are reached that have already been loaded or when no more imports are found. The intent is to ensure that every grammar needed to use the named grammar is loaded.

For example, if we load grammar X, which imports grammar Y, which imports grammars A and B, then all four grammars are loaded. If any of the grammars are already loaded, then it and its imports are not reloaded.

Note that JSGF allows fully-qualified rulename references without a corresponding import statement. This method also attempts to load all grammars referenced by a fully-qualified rulename not already referenced and loaded by a corresponding import statement.

The advanced loadGrammarFromURLWithImports method provides more control of the loading process. This method is equivalent to:

loadGrammarFromURLWithImports(type, url, name, true, false, null);

(load imports, don't reload existing grammars, don't provide a list of loaded grammars.)

Locating Grammars

The context URL parameter is used as the first parameter of the GrammarURL constructor.

The grammarName is converted to a grammar filename. The conversion changes each each period character ('.') to a file separator ('/'). The ".gram" suffix is appended to identify the grammar file. The grammarName "com.sun.numbers" becomes the filename "com/sun/numbers.gram". This filename is used as the spec parameter in the URL constructor.

If the context is null, the grammars are searched for only as a system resource.

Reading Grammars

For each grammar it loads, the recognizer determines the file's character encoding by reading the JSGF header.

An exception is thrown if:

  1. any grammar format syntax problems are found,
  2. if a grammar found in a URL does not match the expected name, or
  3. if a grammar cannot be located as either a URL or system resource.

If an exception is thrown part way through loading a set of grammars the list of loaded grammars not explicitly available. The recognizer does not attempt to remove any partially loaded grammars.

The loadGrammar methods operate as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Parameters:
type - the type of the grammar being loaded.
urlContext - the URL context from which grammar locations are derived or null to load exclusively from system resources.
grammarName - the name of the grammar to be loaded.
Return:
a reference to @grammarName.
See Also:
loadGrammarFromStream
loadGrammarFromURLWithImports


RuleGrammar loadGrammarFromURLWithImports(in GrammarType type, in GrammarURL urlContext, in string grammarName, in boolean loadImports, in boolean reloadGrammars, in GrammarArray loadedGrammars) raises (GrammarException, IOException, MalformedURLException, EngineStateError)

Load a RuleGrammar in grammar formatted text from a URL or from system resources and optionally load its imports. This method provide an additional control over whether grammars are reloaded even if they have already been loaded, and allows caller to receive a list of all grammars loaded by the Recognizer. The loaded grammars are used for recognition only after changes are committed.

The three additional parameters of this method provide the following extensions over the loadGrammarFromURL method:

Parameters:
type - the type of the grammar being loaded.
urlContext - the URL context from which grammar locations are derived or null to load exclusively from system resources.
grammarName - the name of the grammar to be loaded.
loadImports - if true, grammars imported by grammarName are loaded plus their imports.
reloadGrammars - if true reload all grammars and imports, if false do not load grammars already loaded into the Recognizer.
loadedGrammars - if non-null a reference to each loaded RuleGrammar is appended as it is loaded.
Return:
a reference to @grammarName.
See Also:
loadGrammarFromStream
loadGrammarFromURL


RuleGrammar newRuleGrammar(in string name) raises (IllegalArgumentException, EngineStateError)

Create a new RuleGrammar for this recognizer with a specified grammar name. The new grammar is used for recognition only after changes are committed.

The newRuleGrammar method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Parameters:
name - name of the grammar to be created.
Return:
a new RuleGrammar for this recognizer with a specified grammar name.


Grammar readVendorGrammar(in InputStream input) raises (VendorDataException, IOException, EngineStateError)

Create a new grammar by reading in a grammar stored in a vendor-specific format. The data could have been stored using the writeVendorGrammar method. The documentation for the writeVendorGrammar method describes the use of vendor grammar formats.

If a grammar of the same name already exists, it is over-written.

The readVendorGrammar method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Parameters:
input - InputStream from which grammar is loaded
Return:
a reference to the loaded grammar.


 void writeVendorGrammar(in OutputStream output, in Grammar grammar) raises (IOException, EngineStateError)

Store a grammar in a vendor-specific format. The data can be reloaded at a future time by the readVendorGrammar method.

The output format will be specific to the type of recognizer that writes it. For example, data written by an Acme Command and Control Recognizer will be readable only by another Acme Command and Control Recognizer or by other recognizers that understand it's format. When portability is required, use the Java Speech Grammar Format.

Why is a Vendor grammar format useful? The recognizer can store information that makes reloading of the grammar faster than when JSGF is used. The recognizer may also store additional information (e.g. pronunciation, statistical and acoustic data) that improve recognition using this grammar.

The writeVendorGrammar method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Parameters:
output - the OutputStream where the grammar is written.
grammar - the Grammar to be written. Store a grammar in a vendor-specific format. The data can be


 Result readVendorResult(in InputStream input) raises (VendorDataException, IOException, EngineStateError)

Read a Result object from a stream in a vendor-specific format. The return value will include the best-guess tokens, and may include N-best results, audio data, timing data, training information and other data the is optionally provided with a finalized Result.

The call returns null upon failure. Because result objects are stored in a vendor-specific format they cannot normally be loaded by incompatible recognizers.

The readVendorResult method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Parameters:
input - the InputStream from which Result is loaded.
Return:
reference to the loaded result


 void writeVendorResult(in OutputStream output, in Result result) raises (IOException, ResultStateError, EngineStateError)

Store a finalized Result object in a vendor-specific format so that it can be re-loaded in a future session. All the current information associated with the result is stored. If the application will not need audio data or training information in a future session, they should release that information (through the FinalResult interface) before writing the result to reduce storage requirements.

The writeVendorGrammar method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Parameters:
output - the OutputStream where the result is written.
result - the Result to be written.


 void releaseFocus() raises (EngineStateError)

Release the speech focus from this Recognizer. A FOCUS_LOST event is issued to RecognizerListeners once the focus is released and the Recognizer state changes from FOCUS_OFF to FOCUS_ON.

Since one one application may have recognition focus at any time, applications should release focus whenever it is not required. Speech focus and other focus issues are discussed above in more detail.

It is not an error for an application to release focus for a Recognizer that does not have speech focus.

Focus is implicitly released when a Recognizer is deallocated.

The releaseFocus method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

See Also:
requestFocus
FOCUS_OFF
RecognizerEvent#FOCUS_LOST
Engine#getEngineState


 void requestFocus() raises (EngineStateError)

Request the speech focus for this Recognizer from the underlying speech recognition engine. When the focus is received, a FOCUS_GAINED event is issued to RecognizerListeners and the Recognizer changes state from FOCUS_ON to FOCUS_OFF.

Since one one application may have recognition focus at any time, applications should only request focus when confident that the user is speaking to that application. Speech focus and other focus issues are discussed above in more detail.

It is not an error for an application to request focus for a Recognizer that already has speech focus.

The requestFocus method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

See Also:
releaseFocus
FOCUS_ON
RecognizerEvent#FOCUS_GAINED
Engine#getEngineState


 void suspend() raises (EngineStateError)

Temporarily suspend recognition while the application updates grammars prior to a commitChanges call. The suspend call places the Recognizer in the SUSPENDED state. While in that state the incoming audio is buffered. The buffered audio is processed after the recognizer has committed grammar changes and returned to the LISTENING state.

The primary difference between the suspend and pause methods is that audio is buffered while a Recognizer is suspended whereas incoming audio is ignored while in the PAUSED state. Also, the SUSPENDED state should only be visited temporarily, whereas a Recognizer can be PAUSED indefinately.

The suspend method is asynchronous. When the call returns, the recognizer is not necessarily suspended. The getEngineState method, or the RECOGNIZER_SUSPENDED events can be used to determine when the recognizer is actually suspended.

The use of suspend with commitChanges for handling atomic grammar changes and for handling asynchronous events are described above.

Calls to suspend and commitChanges do not nest. A single call to commitChanges can release the Recognizer after multiple calls to suspend.

The suspend method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

See Also:
commitChanges
SUSPENDED
RecognizerEvent#RECOGNIZER_SUSPENDED