The Engine
interface is the parent interface for all speech
engines including Recognizer
and Synthesizer
.
A speech engine is a generic entity that either processes speech input
or produces speech output. Engines - recognizers and synthesizers - derive
the following functionality from the Engine
interface:
allocate
and deallocate
methods.
pause
and resume
methods.
AudioManager
and VocabManager
.
EngineProperties
.
EngineModeDesc
.
EngineListener
objects.
Engines are located, selected and created through methods of the
Central
class.
Engine State System: Allocation
Each type of speech engine has a well-defined set of states of operation,
and well-defined behavior for moving between states. These states are
defined by constants of the Engine
, Recognizer
and Synthesizer
interfaces.
The Engine
interface defines three methods for viewing and
monitoring states: getEngineState
, waitEngineState
and testEngineState
. An EngineEvent
is issued
to EngineListeners
each time an Engine
changes
state.
The basic states of any speech engine (Recognizer
or
Synthesizer
) are DEALLOCATED
,
ALLOCATED
, ALLOCATING_RESOURCES
and
DEALLOCATING_RESOURCES
. An engine in the ALLOCATED
state has acquired all the resources it requires to perform its core
functions.
Engines are created in the DEALLOCATED
state and a call to
allocate
is required to prepare them for usage. The
ALLOCATING_RESOURCES
state is an intermediate state between
DEALLOCATED
and ALLOCATED
which an engine
occupies during the resource allocation process (which may be a very short
period or takes 10s of seconds).
Once an application finishes using a speech engine it should always
explicitly free system resources by calling the deallocate
method. This call transitions the engine to the DEALLOCATED
state via some period in the DEALLOCATING_RESOURCES
state.
The methods of Engine
, Recognizer
and
Synthesizer
perform differently according to the engine's
allocation state. Many methods cannot be performed when an engine is in
either the DEALLOCATED
or DEALLOCATING_RESOURCES
state. Many methods block (wait) for an engine in the
ALLOCATING_RESOURCES
state until the engine reaches
the ALLOCATED
state. This blocking/exception behavior is
defined separately for each method of Engine
,
Synthesizer
and Recognizer
.
Engine State System: Sub-states of ALLOCATED
The ALLOCATED
states has sub-states.
(The DEALLOCATED
, ALLOCATING_RESOURCES
and
DEALLOCATING_RESOURCES
states do not have any sub-states.)
ALLOCATED
engine (Recognizer
or
Synthesizer
) is either PAUSED
or
RESUMED
. These state indicates whether audio
input/output is stopped or running.
ALLOCATED
Synthesizer
has additional
sub-states for QUEUE_EMPTY
and
QUEUE_NOT_EMPTY
that indicate the status of its speech
output queue. These two states are independent of the
PAUSED
and RESUMED
states.
ALLOCATED
Recognizer
has additional
sub-states for LISTENING
, PROCESSING
and
SUSPENDED
that indicate the status of the recognition
process. These three states are independent of the PAUSED
and RESUMED
states (with the exception of minor
interactions documented with Recognizer
).
ALLOCATED
Recognizer
also has additional
sub-states for FOCUS_ON
and FOCUS_OFF
.
Focus determines when most of an application's grammars are active
or deactive for recognition. The focus states are independent of the
PAUSED
and RESUMED
states and of the
LISTENING
/ PROCESSING
/
SUSPENDED
states. (Limited exceptions are discussed in
the documentation for Recognizer
).
The pause
and resume
methods are used to
transition an engine between the PAUSED
and
RESUMED
states. The PAUSED
and
RESUMED
states are shared by all applications that use
the underlying engine. For instance, pausing a recognizer pauses all
applications that use that engine.
The states and sub-states defined above put constraints upon the state of an engine. The following are examples of illegal states:
Engine
states:
Engine.DEALLOCATED | Engine.RESUMED
Engine.ALLOCATED | Engine.DEALLOCATED
Synthesizer
states:
Engine.DEALLOCATED | Engine.QUEUE_NOT_EMPTY
Engine.QUEUE_EMPTY | Engine.QUEUE_NOT_EMPTY
Recognizer
states:
Engine.DEALLOCATED | Engine.PROCESSING
Engine.PROCESSING | Engine.SUSPENDED
Calls to the testEngineState
and waitEngineState
methods with illegal state values cause an exception to be raised.
Central
Synthesizer
Recognizer
Consts Summary: | |
long long | DEALLOCATED = 1 |
long long | ALLOCATING_RESOURCES = 2 |
long long | ALLOCATED = 4 |
long long | DEALLOCATING_RESOURCES = 8 |
long long | PAUSED = 256 |
long long | RESUMED = 512 |
Operations Summary: | |
void | addEngineListener(in EngineListener listener) |
void | removeEngineListener(in EngineListener listener) |
void | allocate() raises |
void | deallocate() raises |
AudioManager | getAudioManager() |
EngineModeDesc | getEngineModeDesc() raises |
EngineProperties | getEngineProperties() |
long long | getEngineState() |
VocabManager | getVocabManager() raises |
void | pause() raises |
void | resume() raises |
boolean | testEngineState(in long long state) raises |
void | waitEngineState(in long long state) raises |
Operations Inherited from Bonobo::Unknown | |
ref, unref, queryInterface |
Const Details: |
Bit of state that is set when an Engine
is in the
deallocated state. A deallocated engine does not have the
resources necessary for it to carry out its basic functions.
In the DEALLOCATED
state, many of the methods of
an Engine
throw an exception when called. The
DEALLOCATED
state has no sub-states.
An Engine
is always created in the
DEALLOCATED
state. A DEALLOCATED
can
transition to the ALLOCATED
state via the
ALLOCATING_RESOURCES
state following a call to the
allocate
method. An Engine
returns to
the DEALLOCATED
state via the
DEALLOCATING_RESOURCES
state with a call to the
deallocate
method.
allocate
deallocate
getEngineState
waitEngineState
Bit of state that is set when an Engine
is being
allocated - the transition state between DEALLOCATED
to ALLOCATED
following a call to the
allocate
method. The ALLOCATING_RESOURCES
state has no sub-states. In the ALLOCATING_RESOURCES
state, many of the methods of Engine
,
Recognizer
, and Synthesizer
will block
until the Engine
reaches the ALLOCATED
state and the action can be performed.
getEngineState
waitEngineState
Bit of state that is set when an #Engine is in the allocated state.
An engine in the ALLOCATED
state has acquired the
resources required for it to carry out its core functions.
The ALLOCATED
states has sub-states for
RESUMED
and PAUSED
.
Both Synthesizer
and Recognizer
define
additional sub-states of ALLOCATED
.
An Engine
is always created in the
DEALLOCATED
state. It reaches the
ALLOCATED
state via the
ALLOCATING_RESOURCES
state with a call to the
allocate
method.
Synthesizer
Recognizer
getEngineState
waitEngineState
Bit of state that is set when an Engine
is being
deallocated - the transition state between ALLOCATED
to DEALLOCATED
. The DEALLOCATING_RESOURCES
state has no sub-states. In the DEALLOCATING_RESOURCES
state, most methods of Engine
, Recognizer
and Synthesizer
throw an exception.
getEngineState
waitEngineState
Bit of state that is set when an Engine
is is in the
ALLOCATED
state and is PAUSED
. In the
PAUSED
state, audio input or output stopped.
An ALLOCATED
engine is always in either in the
PAUSED
or RESUMED
. The PAUSED
and RESUMED
states are sub-states of the
ALLOCATED
state.
RESUMED
ALLOCATED
getEngineState
waitEngineState
Bit of state that is set when an Engine
is is in the
ALLOCATED
state and is RESUMED
. In the
RESUMED
state, audio input or output active.
An ALLOCATED
engine is always in either in the
PAUSED
or RESUMED
. The PAUSED
and RESUMED
states are sub-states of the
ALLOCATED
state.
RESUMED
ALLOCATED
getEngineState
waitEngineState
Operation Details: |
Request notifications of events of related to the
Engine
. An application can attach multiple listeners
to an Engine
. A single listener can be attached to
multiple engines.
The EngineListener
is extended for both recognition
and synthesis. Typically, a RecognizerListener
is
attached to a Recognizer
and a
SynthesizerListener
is attached to a
Synthesizer
.
An EngineListener
can be attached or removed in any
state of an Engine
.
EngineEvents
. Recognizer
RecognizerListener
Synthesizer
SynthesizerListener
Remove a listener from this Engine
. An
EngineListener
can be attached or removed in any
state of an Engine
.
Allocate the resources required for the Engine
and
put it into the ALLOCATED
state. When this method
returns successfully the ALLOCATED
bit of engine
state is set, and the testEngineState(Engine.ALLOCATED)
method returns true. During the processing of the method, the
Engine
is temporarily in the
ALLOCATING_RESOURCES
state.
When the Engine
reaches the ALLOCATED
state other engine states are determined:
PAUSED
or RESUMED
: the pause
state depends upon the existing state of the engine. In a
multi-app environment, the pause/resume state of the
engine is shared by all apps.
Recognizer
always starts in the
LISTENING
state when newly allocated but may
transition immediately to another state.
Recognizer
may be allocated in either the
HAS_FOCUS
state or LOST_FOCUS
state depending upon the activity of other applications.
Synthesizer
always starts in the
QUEUE_EMPTY
state when newly allocated.
While this method is being processed events are issued to any
EngineListeners
attached to the Engine
to indicate state changes. First, as the Engine
changes from the DEALLOCATED
to the
ALLOCATING_RESOURCES
state, an
ENGINE_ALLOCATING_RESOURCES
event is issued. As the
allocation process completes, the engine moves from the
ALLOCATING_RESOURCES
state to the
ALLOCATED
state and an ENGINE_ALLOCATED
event is issued.
The allocate
method should be called for an
Engine
in the DEALLOCATED
state. The
method has no effect for an Engine
is either the
ALLOCATING_RESOURCES
or ALLOCATED
states.
The method throws an exception in the
DEALLOCATING_RESOURCES
state.
If any problems are encountered during the allocation process
so that the engine cannot be allocated, the engine returns
to the DEALLOCATED
state (with an
ENGINE_DEALLOCATED
event), and an
EngineException
is thrown.
Allocating the resources for an engine may be fast (less than
a second) or slow (several 10s of seconds) depending upon a range
of factors. Since the allocate
method does not
return until allocation is completed applications may want to
perform allocation in a background thread and proceed with other
activities.
getEngineState
deallocate
ALLOCATED
EngineEvent#ENGINE_ALLOCATED
Free the resources of the engine that were acquired during
allocation and during operation and return the engine
to the DEALLOCATED
. When this method returns
the DEALLOCATED
bit of engine state is set so the
testEngineState(Engine.DEALLOCATED) method returns
true. During the processing of the method, the
Engine
is temporarily in the
DEALLOCATING_RESOURCES
state.
A deallocated engine can be re-started with a subsequent
call to allocate
.
Engines need to clean up current activities before being
deallocated. A Synthesizer
must be in the
QUEUE_EMPTY
state before being deallocated. If the
queue is not empty, any objects on the speech output queue must
be cancelled with appropriate events issued. A
Recognizer
cannot be in the PROCESSING
state when being deallocated. If necessary, there must be a
forceFinalize
of any unfinalized result.
While this method is being processed events are issued to any
EngineListeners
attached to the Engine
to indicate state changes. First, as the Engine
changes from the ALLOCATED
to the
DEALLOCATING_RESOURCES
state, an
ENGINE_DEALLOCATING_RESOURCES
event is issued. As
the deallocation process completes, the engine moves from the
DEALLOCATING_RESOURCES
state to the
DEALLOCATED
state and an
ENGINE_DEALLOCATED
event is issued.
The deallocate
method should only be called for
an Engine
in the ALLOCATED
state.
The method has no effect for an Engine
is either
the DEALLOCATING_RESOURCES
or DEALLOCATED
states. The method throws an exception in the
ALLOCATING_RESOURCES
state.
Deallocating resources for an engine is not always immediate. Since the deallocate method does not return until complete, applications may want to perform deallocation in a separate thread.
allocate
EngineEvent#ENGINE_DEALLOCATED
Synthesizer#QUEUE_EMPTY
Return an object which provides management of the audio input or
output for the Engine
.
The AudioManager
is available in any state of an
Engine
.
AudioManager
for the engine.
Return a mode descriptor that defines the operating properties
of the engine. For a Recognizer
the return value is a
RecognizerModeDesc
. For a Synthesizer
the return value is a SynthesizerModeDesc
.
The EngineModeDesc
is available in any state of an
Engine
.
EngineModeDesc
for the engine.
Return the EngineProperties
object.
A Recognizer
returns a
RecognizerProperties
object. The
Recognizer
interface also defines a
getRecognizerProperties
method that returns the same
object as getEngineProperties
, but without requiring
a cast to be useful.
A Synthesizer
returns a
SynthesizerProperties
object. The
Synthesizer
interface also defines a
getSynthesizerProperties
method that returns the
same object as getEngineProperties
, but without
requiring a cast to be useful.
The EngineProperties
are available in any state of
an Engine
. However, changes only take effect once
an engine reaches the ALLOCATED
state.
EngineProperties
object for this engine.Recognizer#getRecognizerProperties
RecognizerProperties
Synthesizer#getSynthesizerProperties
SynthesizerProperties
Returns an OR'ed set of flags indicating the current state of an
Engine
. The format of the returned state value is
described above.
An EngineEvent
is issued each time the
Engine
changes state.
The getEngineState
method can be called successfully
in any Engine
state.
Engine
.getEngineState
waitEngineState
EngineEvent#getNewEngineState
EngineEvent#getOldEngineState
Return an object which provides management of the vocabulary for
the Engine
. See the VocabManager
documentation for a description of vocabularies and their use
with speech engines. Returns null if the Engine
does
not provide vocabulary management capabilities.
The VocabManager
is available for engines in the
ALLOCATED
state. The call blocks for engines in the
ALLOCATING_RESOURCES
. An error is thrown for engines
in the DEALLOCATED
or
DEALLOCATING_RESOURCES
states.
VocabManager
for the engine or null if it does not have a VocabManager
. Word
Pause the audio stream for the engine and put the
Engine
into the PAUSED
state. Pausing
an engine pauses the underlying engine for all applications that
are connected to that engine. Engines are typically paused and
resumed by request from a user.
Applications may pause an engine indefinitely. When an engine
moves from the RESUMED
state to the PAUSED
state, an ENGINE_PAUSED
event is issued to each
EngineListener
attached to the Engine
.
The PAUSED
bit of the engine state is set to true
when paused, and can be tested by the getEngineState
method and other engine state methods.
The PAUSED
state is a sub-state of the
ALLOCATED
state. An ALLOCATED
Engine
is always in either the PAUSED
or the RESUMED
state.
It is not an exception to pause an Engine
that is
already paused.
The pause
method operates as defined for engines
in the ALLOCATED
state. When pause is called for
an engine in the ALLOCATING_RESOURCES
state, the
method blocks (waits) until the ALLOCATED
state
is reached and then operates normally. An error is thrown when
pause is called for an engine is either the
DEALLOCATED
is DEALLOCATING_RESOURCES
states.
The pause
method does not always return immediately.
Some applications need to execute pause in a separate
thread.
Pausing a Synthesizer
The pause/resume mechanism for a synthesizer is analogous to pause/resume on a tape player or CD player. The audio output stream is paused. The speaking queue is left intact and a subsequent resume continues output from the point at which the pause took effect.
Pausing a Recognizer
Pause and resume for a recognizer are analogous to turning a microphone off and on. Pausing stops the input audio input stream as close as possible to the time of the call to pause. The incoming audio between the pause and the resume calls is ignored.
Anything a user says while the recognizer is paused will not be heard by the recognizer. Pausing a recognizer during the middle of user speech forces the recognizer to finalize or reject processing of that incoming speech - a recognition result cannot cross a pause/resume boundary.
Most recognizers have some amount of internal audio buffering. This means that some recognizer processing may continue after the pause. For example, results can be created and finalized.
Note: recognizers add a special suspend
method that
allows applications to temporarily stop the recognizer to modify
grammars and grammar activation. Unlike a paused recognizer,
a suspended recognizer buffers incoming audio input to be
processed once it returns to a listening state, so no audio is lost.
resume
getEngineState
EngineEvent#ENGINE_PAUSED
Recognizer#suspend
Put the Engine
in the RESUMED
state to
resume audio streaming to or from a paused engine. Resuming an
engine resuming the underlying engine for all applications that
are connected to that engine. Engines are typically paused and
resumed by request from a user.
The specific pause/resume behavior of recognizers and synthesizers
is defined in the documentation for the pause
method.
When an engine moves from the PAUSED
state to the
RESUMED
state, an ENGINE_RESUMED
event
is issued to each EngineListener
attached to the
Engine
. The RESUMED
bit of the engine
state is set to true when resumed, and can be tested by the
getEngineState method and other engine state methods.
The RESUMED
state is a sub-state of the
ALLOCATED
state. An ALLOCATED
Engine
is always in either the PAUSED
or the RESUMED
state.
It is not an exception to resume a engine
that is
already in the RESUMED
state. An exception may be
thrown if the audio resource required by the engine (audio input
or output) is not available.
The resume
method operates as defined for engines in
the ALLOCATED
state. When resume is called for an
engine in the ALLOCATING_RESOURCES
state, the method
blocks (waits) until the ALLOCATED
state is reached
and then operates normally. An error is thrown when resume is
called for an engine is either the DEALLOCATED
is
DEALLOCATING_RESOURCES
states.
The resume
method does not always return immediately.
Some applications need to execute resume in a separate thread.
pause
getEngineState
EngineEvent#ENGINE_RESUMED
Returns true if the current engine state matches the specified
state. The format of the state
value is
described above.
The test performed is not an exact match to the current state.
Only the specified states are tested. For example the following
returns true only if the Synthesizer
queue is empty,
irrespective of the pause/resume and allocation states.
if (synth.testEngineState(Synthesizer.QUEUE_EMPTY)) ...
The testEngineState
method is equivalent to:
if ((engine.getEngineState() & state) == state)
The testEngineState
method can be called successfully
in any Engine
state.
Blocks the calling thread until the Engine
is in a
specified state. The format of the state value is
described above.
All state bits specified in the state parameter must be set in
order for the method to return, as defined for the
testEngineState
method. If the state parameter
defines an unreachable state (e.g. PAUSED | RESUMED
)
an exception is thrown.
The waitEngineState
method can be called successfully
in any Engine
state.
Engine
. testEngineState
getEngineState