Modules | Files | Inheritance Tree | Inheritance Graph | Name Index
module GNOME::Speech
interface Engine
Files: GNOME_Speech.idl
GNOME-Speech-Engine-inheritance GNOME-Speech-Synthesis-Synthesizer.html GNOME-Speech-Recognition-Recognizer.html GNOME-Speech-SpeechObject.html Bonobo-Unknown.html

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:

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.)

  • Any ALLOCATED engine (Recognizer or Synthesizer) is either PAUSED or RESUMED. These state indicates whether audio input/output is stopped or running.

  • An 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.

  • An 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).

  • An 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.

Engine State System: get/test/wait

The current state of an Engine is returned by the getEngineState method. The waitEngineState method blocks the calling thread until the Engine reaches a specified state. The testEngineState tests whether an Engine is in a specified state.

The state values can be bitwise OR'ed For example, for an allocated, resumed synthesizer with items in its speech output queue, the state is

Engine.ALLOCATED | Engine.RESUMED | Synthesizer.QUEUE_NOT_EMPTY

The states and sub-states defined above put constraints upon the state of an engine. The following are examples of illegal states:

Illegal Engine states: Engine.DEALLOCATED | Engine.RESUMED Engine.ALLOCATED | Engine.DEALLOCATED

Illegal Synthesizer states: Engine.DEALLOCATED | Engine.QUEUE_NOT_EMPTY Engine.QUEUE_EMPTY | Engine.QUEUE_NOT_EMPTY

Illegal 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.

See Also:
Central
Synthesizer
Recognizer


Consts Summary:
long longDEALLOCATED = 1
long longALLOCATING_RESOURCES = 2
long longALLOCATED = 4
long longDEALLOCATING_RESOURCES = 8
long longPAUSED = 256
long longRESUMED = 512

Operations Summary:
 voidaddEngineListener(in EngineListener listener)
 voidremoveEngineListener(in EngineListener listener)
 voidallocate() raises
 voiddeallocate() raises
 AudioManagergetAudioManager()
EngineModeDescgetEngineModeDesc() raises
EnginePropertiesgetEngineProperties()
 long longgetEngineState()
 VocabManagergetVocabManager() raises
 voidpause() raises
 voidresume() raises
 booleantestEngineState(in long long state) raises
 voidwaitEngineState(in long long state) raises

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

Const Details:
long long
DEALLOCATED = 1

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.

See Also:
allocate
deallocate
getEngineState
waitEngineState


long long ALLOCATING_RESOURCES = 2

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.

See Also:
getEngineState
waitEngineState


long long ALLOCATED = 4

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.

See Also:
Synthesizer
Recognizer
getEngineState
waitEngineState


long long DEALLOCATING_RESOURCES = 8

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.

See Also:
getEngineState
waitEngineState


long long PAUSED = 256

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.

See Also:
RESUMED
ALLOCATED
getEngineState
waitEngineState


long long RESUMED = 512

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.

See Also:
RESUMED
ALLOCATED
getEngineState
waitEngineState


Operation Details:
 void addEngineListener(in EngineListener listener)

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.

Parameters:
listener - the listener that will receive EngineEvents.
See Also:
Recognizer
RecognizerListener
Synthesizer
SynthesizerListener


 void removeEngineListener(in EngineListener listener)

Remove a listener from this Engine. An EngineListener can be attached or removed in any state of an Engine.

Parameters:
listener - the listener to be removed.


 void allocate() raises (EngineException, EngineStateError)

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.

  • A Recognizer always starts in the LISTENING state when newly allocated but may transition immediately to another state.

  • A Recognizer may be allocated in either the HAS_FOCUS state or LOST_FOCUS state depending upon the activity of other applications.

  • A 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.

See Also:
getEngineState
deallocate
ALLOCATED
EngineEvent#ENGINE_ALLOCATED


 void deallocate() raises (EngineException, EngineStateError)

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.

See Also:
allocate
EngineEvent#ENGINE_DEALLOCATED
Synthesizer#QUEUE_EMPTY


 AudioManager getAudioManager()

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.

Return:
the AudioManager for the engine.


EngineModeDesc getEngineModeDesc() raises (SecurityException)

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.

Return:
an EngineModeDesc for the engine.


EngineProperties getEngineProperties()

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.

Return:
the EngineProperties object for this engine.
See Also:
Recognizer#getRecognizerProperties
RecognizerProperties
Synthesizer#getSynthesizerProperties
SynthesizerProperties


 long long getEngineState()

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.

Return:
an OR'ed set of flags indicating the current state of an Engine.
See Also:
getEngineState
waitEngineState
EngineEvent#getNewEngineState
EngineEvent#getOldEngineState


 VocabManager getVocabManager() raises (EngineStateError)

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.

Return:
the VocabManager for the engine or null if it does not have a VocabManager.
See Also:
Word


 void pause() raises (EngineStateError)

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.

See Also:
resume
getEngineState
EngineEvent#ENGINE_PAUSED
Recognizer#suspend


 void resume() raises (AudioException, EngineStateError)

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.

See Also:
pause
getEngineState
EngineEvent#ENGINE_RESUMED


 boolean testEngineState(in long long state) raises (IllegalArgumentException)

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.

Parameters:
state - the engine state to test against.
Return:
a boolean indication of whether the current engine state matches the specified state.


 void waitEngineState(in long long state) raises (IllegalArgumentException, InterruptedException)

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.

Parameters:
state - the state required of the Engine.
See Also:
testEngineState
getEngineState