Modules | Files | Inheritance Tree | Inheritance Graph | Name Index
module GNOME::Speech
interface Central
Files: GNOME_Speech.idl
GNOME-Speech-Central-inheritance GNOME-Speech-SpeechObject.html Bonobo-Unknown.html

The Central class is the initial access point to all speech input and output capabilities. Central provides the ability to locate, select and create speech recognizers and speech synthesizers

Creating a Recognizer or Synthesizer

The createRecognizer and createSynthesizer methods are used to create speech engines. Both methods accept a single parameter that defines the required properties for the engine to be created. The parameter is an EngineModeDesc and may be one of the sub-classes: RecognizerModeDesc or SynthesizerModeDesc.

A mode descriptor defines a set of required properties for an engine. For example, a SynthesizerModeDesc can describe a Synthesizer for Swiss German that has a male voice. Similarly, a RecognizerModeDesc can describe a Recognizer that supports dictation for Japanese.

An application is responsible for determining its own functional requirements for speech input/output and providing an appropriate mode descriptor. There are three cases for mode descriptors:

  1. null.
  2. Created by the application.
  3. Obtained from the availableRecognizers or availableSynthesizers methods of Central.

The mode descriptor is passed to the createRecognizer or createSynthesizer methods of Central to create a Recognizer or Synthesizer. The created engine matches all the engine properties in the mode descriptor passed to the create method. If no suitable speech engine is available, the create methods return null.

The create engine methods operate differently for the three cases. That is, engine selection depends upon the type of the mode descriptor:

  1. null mode descriptor: the Central class selects a suitable engine for the default locale.
  2. Application-created mode descriptor: the Central class attempts to locate an engine with all application-specified properties.
  3. Mode descriptor from availableRecognizers or availableSynthesizers: descriptors returned by these two methods identify a specific engine with a specific operating mode. Central creates an instance of that engine. (Note: these mode descriptors are distinguished because they implement the EngineCreate interface.)

Engine Selection Procedure: Cases 1 & 2

For cases 1 and 2 there is a defined procedure for selecting an engine to be created. (For case 3, the application can apply it's own selection procedure).

Locale is treated specially in the selection to ensure that language is always considered when selecting an engine. If a locale is not provided, the default locale is used.

The selection procedure is:

  1. If the locale is undefined add the language of the default locale to the required properties.
  2. If a Recognizer or Synthesizer has been created already and it has the required properties, return a reference to it. (The last created engine is checked).
  3. Obtain a list of all recognizer or synthesizer modes that match the required properties.
  4. Amongst the matching engines, give preference to:
    • A running engine (EngineModeDesc.getRunning is true),
    • An engine that matches the default locale's country.

When more than one engine is a legal match in the final step, the engines are ordered as returned by the availableRecognizers or availableSynthesizers method.

Security

A number of methods throughout the API throw SecurityException. Individual implementations of Recognizer and Synthesizer may throw SecurityException on additional methods as required to protect a client from malicious applications.

Engine Registration

The Central class locates, selects and creates speech engines from amongst a list of registered engines. Thus, for an engine to be used by GNOME applications, the engine must register itself with Central.

There are two registration mechanisms:

  1. add an EngineCentral class to a speech properties file.
  2. temporarily register an engine by calling the registerEngineCentral method.

The speech properties files provide persistent registration of speech engines. When Central is first called, it looks for properties in two files:

~/.gconf/desktop/gnome/speech/%gconf.xml
.../etc/gconf/gconf.xml.defaults/schemas/desktop/gnome/speech/%gconf.xml

Engines identified in either properties file are made available through the methods of Central.

Central looks for the "SupportedRecognizers" gconf resource, which is a comma separated list of the Recognizers that are supported.

When it is first called, the Central class will attempt to create an instance of each EngineCentral object and will ensure that it implements the EngineCentral interface.

Note to engine providers: Central calls each EngineCentral for each call to availableRecognizers or availableSynthesizers and sometimes createRecognizer and createSynthesizer. The results are not stored. The EngineCentral.createEngineList method should be reasonably efficient.


Operations Summary:
 EngineListavailableRecognizers(in EngineModeDesc require) raises
 EngineListavailableSynthesizers(in EngineModeDesc require) raises
Recognition::RecognizercreateRecognizer(in EngineModeDesc require) raises
Synthesis::SynthesizercreateSynthesizer(in EngineModeDesc require) raises
 voidregisterEngineCentral(in string className) raises

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

Operation Details:
 EngineList availableRecognizers(in EngineModeDesc require) raises (SecurityException)

List EngineModeDesc objects for available recognition engine modes that match the required properties. If the require parameter is null, then all known recognizers are listed.

Returns a zero-length list if no engines are available or if no engines have the required properties. (The method never returns null).

The order of the EngineModeDesc objects in the list is partially defined. For each registered engine (technically, each registered EngineCentral object) the order of the descriptors is preserved. Thus, each installed speech engine should order its descriptor objects with the most useful modes first, for example, a mode that is already loaded and running on a desktop.

Parameters:
require - an EngineModeDesc or RecognizerModeDesc defining the required features of the mode descriptors in the returned list.
Return:
list of mode descriptors with the required properties.


 EngineList availableSynthesizers(in EngineModeDesc require) raises (SecurityException)

List EngineModeDesc objects for available synthesis engine modes that match the required properties. If the require parameter is null, then all available known synthesizers are listed.

Returns an empty list (rather than null) if no engines are available or if no engines have the required properties.

The order of the EngineModeDesc objects in the list is partially defined. For each speech installation (technically, each registered EngineCentral object) the order of the descriptors is preserved. Thus, each installed speech engine should order its descriptor objects with the most useful modes first, for example, a mode that is already loaded and running on a desktop.

Parameters:
require - an EngineModeDesc or SynthesizerModeDesc defining the required features of the mode descriptors in the returned list.
Return:
list of mode descriptors with the required properties.


Recognition::Recognizer createRecognizer(in EngineModeDesc require) raises (IllegalArgumentException, EngineException, SecurityException)

Create a Recognizer with specified required properties. If there is no Recognizer with the required properties the method returns null.

The required properties defined in the input parameter may be provided as either an EngineModeDesc object or a RecognizerModeDesc object. The input parameter may also be null, in which case an engine is selected that supports the language of the default locale.

A non-null mode descriptor may be either application-created or a mode descriptor returned by the availableRecognizers method.

The mechanisms for creating a Recognizer are described above in detail.

Parameters:
require - required engine properties or null for default engine selection.
Return:
a recognizer matching the required properties or null if none is available
See Also:
availableRecognizers
::GNOME::Speech:Recognition::RecognizerModeDesc


Synthesis::Synthesizer createSynthesizer(in EngineModeDesc require) raises (IllegalArgumentException, EngineException)

Create a Synthesizer with specified required properties. If there is no Synthesizer with the required properties the method returns null.

The required properties defined in the input parameter may be provided as either an EngineModeDesc object or a SynthesizerModeDesc object. The input parameter may also be null, in which case an engine is selected that supports the language of the default locale.

A non-null mode descriptor may be either application-created or a mode descriptor returned by the availableSynthesizers method.

The mechanisms for creating a Synthesizer are described above in detail.

Parameters:
require - required engine properties or null for default engine selection.
Return:
a Synthesizer matching the required properties or null if none is available.
See Also:
availableSynthesizers
::GNOME::Speech::Synthesis::SynthesizerModeDesc


 void registerEngineCentral(in string className) raises (EngineException)

Register a speech engine with the Central class for use by the current application. This call adds the specified class name to the list of EngineCentral objects. The registered engine is not stored persistently in the properties files. If className is already registered, the call has no effect.

The class identified by className must have an empty constructor.

Parameters:
className - name of a class that implements the EngineCentral interface and provides access to an engine implementation.