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: |
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.
removeResultListener
Grammar#addResultListener
Result#addResultListener
ResultEvent#RESULT_CREATED
ResultEvent#GRAMMAR_FINALIZED
A ResultListener
can be attached or removed in any
Engine
state.
addResultListener
Result#removeResultListener
Grammar#removeResultListener
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.
LISTENING
PROCESSING
SUSPENDED
suspend
RecognizerEvent#CHANGES_COMMITTED
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.
commitChanges
RecognizerEvent#CHANGES_COMMITTED
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.
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.
DictationGrammar
to be defined. DictationGrammar
for a Recognizer
.RecognizerModeDesc#isDictationGrammarSupported
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.
RecognizerProperties
object for this engine. Engine#getEngineProperties
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.
RuleGrammar
reference or null.
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.
SpeakerManager
for this Recognizer
.
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.
RuleGrammars
known to the Recognizer
.
Return an indication of whether this Recognizer
supports this grammar type.
Recognizer
supports this grammar type.GRAMMAR_JSGF
GRAMMAR_SRGS
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.
InputStream
from which the grammar text is loaded.
RuleGrammar
from grammar formatted text provided by the InputStream
.loadGrammarFromURL
loadGrammarFromURLWithImports
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:
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.
loadGrammarFromStream
loadGrammarFromURLWithImports
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:
loadImports
: if false, the method only loads
the RuleGrammar
specified by the name parameter.
If true, the method behaves like the
loadGrammarFromURL
method and recursively loads imported grammars.
reloadGrammars
: if true, the method always
loads a RuleGrammar
, even if it is already
loaded into the Recognizer
. The previous
version of the grammar is overwritten. If false, the
method behaves like the
loadGrammarFromURL
method and does not load grammars that are already loaded,
or their imports.
loadedGrammars
: if non-null, then as the
Recognizer
loads any grammar it appends a
reference to that RuleGrammar
to the vector.
grammarName
are loaded plus their imports.Recognizer
.RuleGrammar
is appended as it is loaded. loadGrammarFromStream
loadGrammarFromURL
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.
RuleGrammar
for this recognizer with a specified grammar name.
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.
InputStream
from which grammar is loaded 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.
OutputStream
where the grammar is written.Grammar
to be written. Store a grammar in a vendor-specific format. The data can be
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.
InputStream
from which Result
is loaded.
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.
OutputStream
where the result is written.Result
to be written.
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.
requestFocus
FOCUS_OFF
RecognizerEvent#FOCUS_LOST
Engine#getEngineState
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.
releaseFocus
FOCUS_ON
RecognizerEvent#FOCUS_GAINED
Engine#getEngineState
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.
commitChanges
SUSPENDED
RecognizerEvent#RECOGNIZER_SUSPENDED