Modules | Files | Inheritance Tree | Inheritance Graph | Name Index
module GNOME::Speech::Synthesis
interface Synthesizer
Files: GNOME_Speech.idl
GNOME-Speech-Synthesis-Synthesizer-inheritance GNOME-Speech-Engine.html GNOME-Speech-SpeechObject.html Bonobo-Unknown.html
Operations Summary:
 voidaddSpeakableListener(in SpeakableListener listener)
 voidremoveSpeakableListener(in SpeakableListener listener)
 longgetNumberOfQueueItems() raises
SynthesizerQueueItemgetQueueItem(in long n) raises
 voidcancel() raises
 voidcancelItem(in SpeechObject source) raises
 voidcancelAll() raises
SynthesizerPropertiesgetSynthesizerProperties()
 stringphoneme(in string text) raises
 booleanisMarkupTypeSupported(in MarkupType type)
 voidspeakMarkupText(in string markupText, in SpeakableListener listener) raises
 voidspeakTextFromURL(in SpeechURL markupURL, in SpeakableListener listener) raises
 voidspeakSpeakable(in Speakable markupText, in SpeakableListener listener) raises
 voidspeakPlainText(in string plainText, in SpeakableListener listener) 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 addSpeakableListener(in SpeakableListener listener)

Request notifications of all SpeakableEvents for all speech output objects for this Synthesizer. An application can attach multiple SpeakableListeners to a Synthesizer. A single listener can be attached to multiple synthesizers.

When an event effects more than one item in the speech output queue (e.g. cancelAll), the SpeakableEvents are issued in the order of the items in the queue starting with the top of the queue.

A SpeakableListener can also provided for an individual speech output item by providing it as a parameter to one of the speak or speakPlainText methods.

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

Parameters:
listener - the listener that will receive SpeakableEvents.
See Also:
removeSpeakableListener


 void removeSpeakableListener(in SpeakableListener listener)

Remove a SpeakableListener from this Synthesizer.

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

Parameters:
listener - the listener to remove.
See Also:
addSpeakableListener


 long getNumberOfQueueItems() raises (EngineStateError)

Return the number of items currently on the speech output queue.

The getNumberOfQueueItems method works in the ALLOCATED state. The call blocks if the Synthesizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown for synthesizers in the DEALLOCATED or DEALLOCATING_RESOURCES states.

Return:
the number of items currently on the speech output queue.
See Also:
getQueueItem
SynthesizerQueueItem
SynthesizerEvent#QUEUE_UPDATED
SynthesizerEvent#QUEUE_EMPTIED
Engine#addEngineListener


SynthesizerQueueItem getQueueItem(in long n) raises (EngineStateError)

Return the n'th item currently on the speech output queue.

A QUEUE_UPDATED event is issued to each SynthesizerListener whenever the speech output queue changes. A QUEUE_EMPTIED event is issued whenever the queue the emptied.

This method returns only the items on the speech queue placed there by the current application. For security reasons, it is not possible to inspect items placed by other applications.

The getQueueItem method works in the ALLOCATED state. The call blocks if the Synthesizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown for synthesizers in the DEALLOCATED or DEALLOCATING_RESOURCES states.

Parameters:
n - index of the item on the speech queue to be returned.
Return:
the n'th item currently on the speech output queue.
See Also:
SynthesizerQueueItem
SynthesizerEvent#QUEUE_UPDATED
SynthesizerEvent#QUEUE_EMPTIED
Engine#addEngineListener


 void cancel() raises (EngineStateError)

Cancel output of the current object at the top of the output queue. A SPEAKABLE_CANCELLED event is issued to appropriate SpeakableListeners.

If there is another object in the speaking queue, it is moved to top of queue and receives the TOP_OF_QUEUE event. If the Synthesizer is not paused, speech output continues with that object. To prevent speech output continuing with the next object in the queue, call pause before calling cancel.

A SynthesizerEvent is issued to indicate QUEUE_UPDATED (if objects remain on the queue) or QUEUE_EMPTIED (if the cancel leaves the queue empty).

It is not an exception to call cancel if the speech output queue is empty.

The cancel methods work in the ALLOCATED state. The calls blocks if the Synthesizer in the ALLOCATING_RESOURCES state and complete when the engine reaches the ALLOCATED state. An error is thrown for synthesizers in the DEALLOCATED or DEALLOCATING_RESOURCES states.

See Also:
cancelItem
cancelAll
SynthesizerEvent#QUEUE_UPDATED
SynthesizerEvent#QUEUE_EMPTIED
SpeakableEvent#TOP_OF_QUEUE
SpeakableEvent#SPEAKABLE_CANCELLED


 void cancelItem(in SpeechObject source) raises (IllegalArgumentException, EngineStateError)

Remove a specified item from the speech output queue. The source object must be one of the items passed to a speak method. A SPEAKABLE_CANCELLED event is issued to appropriate SpeakableListeners.

If the source object is the top item in the queue, the behavior is the same as the cancel method.

If the source object is not at the top of the queue, it is removed from the queue without affecting the current top-of-queue speech output. A QUEUE_UPDATED is then issued to SynthesizerListeners.

If the source object appears multiple times in the queue, only the first instance is cancelled.

Warning: cancelling an object just after the synthesizer has completed speaking it and has removed the object from the queue will cause an exception. In this instance, the exception can be ignored.

The cancel methods work in the ALLOCATED state. The calls blocks if the Synthesizer in the ALLOCATING_RESOURCES state and complete when the engine reaches the ALLOCATED state. An error is thrown for synthesizers in the DEALLOCATED or DEALLOCATING_RESOURCES states.

Parameters:
source - object to be removed from the speech output queue.
See Also:
cancel
cancelAll
SynthesizerEvent#QUEUE_UPDATED
SynthesizerEvent#QUEUE_EMPTIED
SpeakableEvent#SPEAKABLE_CANCELLED


 void cancelAll() raises (EngineStateError)

Cancel all objects in the synthesizer speech output queue and stop speaking the current top-of-queue object.

The SpeakableListeners of each cancelled item on the queue receive a SPEAKABLE_CANCELLED event. A QUEUE_EMPTIED event is issued to attached SynthesizerListeners.

A cancelAll is implictly performed before a Synthesizer is deallocated.

The cancel methods work in the ALLOCATED state. The calls blocks if the Synthesizer in the ALLOCATING_RESOURCES state and complete when the engine reaches the ALLOCATED state. An error is thrown for synthesizers in the DEALLOCATED or DEALLOCATING_RESOURCES states.

See Also:
cancel
cancelItem
SynthesizerEvent#QUEUE_EMPTIED
SpeakableEvent#SPEAKABLE_CANCELLED


SynthesizerProperties getSynthesizerProperties()

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

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

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


 string phoneme(in string text) raises (EngineStateError)

Returns the phoneme string for a text string. The return string uses the International Phonetic Alphabet subset of UTF8. The input string is expected to be simple text (for example, a word or phrase in English). The text is not expected to contain punctuation or markup.

If the Synthesizer does not support text-to-phoneme conversion or cannot process the input text it will return null.

If the text has multiple pronunciations, there is no way to indicate which pronunciation is preferred.

The phoneme method operate as defined only when a Synthesizer is in the ALLOCATED state. The call blocks if the Synthesizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown for synthesizers in the DEALLOCATED or DEALLOCATING_RESOURCES states.

Parameters:
text - plain text to be converted to phonemes.
Return:
phonemic representation of text or null.


 boolean isMarkupTypeSupported(in MarkupType type)

Return an indication of whether this markup type is supported.

Parameters:
markupType - the markup type being checked.
Return:
an indication of whether this Synthesizer supports this markup type.
See Also:
MARKUP_JSML
MARKUP_SSML


 void speakMarkupText(in string markupText, in SpeakableListener listener) raises (MarkupException, EngineStateError)

Speak a string containing markup formatted text. The marked up text is checked for formatting errors and a MarkupException is thrown if any are found. If legal, the text is placed at the end of the speaking queue and will be spoken once it reaches the top of the queue and the synthesizer is in the RESUMED state. In all other respects is it identical to the speak method that accepts a Speakable object.

The source of a SpeakableEvent issued to the SpeakableListener is the string.

The speak methods operate as defined only when a Synthesizer is in the ALLOCATED state. The call blocks if the Synthesizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown for synthesizers in the DEALLOCATED or DEALLOCATING_RESOURCES states.

Parameters:
markupText - string contains marked up text to be spoken.
listener - receives notification of events as synthesis output proceeds.
See Also:
speakSpeakable
speakTextFromURL
speakPlainText


 void speakTextFromURL(in SpeechURL markupURL, in SpeakableListener listener) raises (MarkupException, IOException, MalformedURLException, EngineStateError)

Speak marked up text from a URL. The text is obtained from the URL, checked for legal markup formatting, and placed at the end of the speaking queue. It is spoken once it reaches the top of the queue and the synthesizer is in the RESUMED state. In other respects is it identical to the speak method that accepts a Speakable object.

The source of a SpeakableEvent issued to the SpeakableListener is the SpeechURL.

Because of the need to check markup syntax, this speak method returns only once the complete URL is loaded, or until a syntax error is detected in the URL stream. Network delays will cause the method to return slowly.

Note: the full XML header is required in JSML formatted text provided in the URL. The header is optional on programmatically generated JSML (ie. with the speakMarkupText and speakSpeakable) methods.

The speak methods operate as defined only when a Synthesizer is in the ALLOCATED state. The call blocks if the Synthesizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown for synthesizers in the DEALLOCATED or DEALLOCATING_RESOURCES states.

Parameters:
markupURL - URL containing marked up text to be spoken.
listener - receives notification of events as synthesis output proceeds.
See Also:
speakSpeakable
speakMarkupText
speakPlainText
SpeakableEvent
addSpeakableListener


 void speakSpeakable(in Speakable markupText, in SpeakableListener listener) raises (MarkupException, EngineStateError)

Speak an object that implements the Speakable interface and provides marked up text. The Speakable object is added to the end of the speaking queue and will be spoken once it reaches the top of the queue and the synthesizer is in the RESUMED state.

The synthesizer first requests the text of the Speakable by calling its getMarkupText method. It then checks the syntax of the markup and throws a MarkupException if any problems are found. If the marked up text is legal, the text is placed on the speech output queue.

When the speech output queue is updated, a QUEUE_UPDATE event is issued to SynthesizerListeners.

Events associated with the Speakable object are issued to the SpeakableListener object. The listener may be null. A listener attached with this method cannot be removed with a subsequent remove call. The source for the SpeakableEvents is the JSMLtext object.

SpeakableEvents can also be received by attaching a SpeakableListener to the Synthesizer with the addSpeakableListener method. A SpeakableListener attached to the Synthesizer receives all SpeakableEvents for all speech output items of the synthesizer (rather than for a single Speakable).

The speak call is asynchronous: it returns once the text for the Speakable has been obtained, checked for syntax, and placed on the synthesizer's speech output queue. An application needing to know when the Speakable has been spoken should wait for the SPEAKABLE_ENDED event to be issued to the SpeakableListener object. The getEngineState and waitEngineState methods can be used to determine the speech output queue status.

An object placed on the speech output queue can be removed with one of the cancel methods.

The speak methods operate as defined only when a Synthesizer is in the ALLOCATED state. The call blocks if the Synthesizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown for synthesizers in the DEALLOCATED or DEALLOCATING_RESOURCES states.

Parameters:
markupText - object implementing the Speakable interface that provides marked up text to be spoken.
listener - receives notification of events as synthesis output proceeds.
See Also:
speakMarkupText
speakTextFromURL
speakPlainText
SpeakableEvent
addSpeakableListener


 void speakPlainText(in string plainText, in SpeakableListener listener) raises (EngineStateError)

Speak a plain text string. The text is not interpreted as containing a markup language so markup elements are ignored. The text is placed at the end of the speaking queue and will be spoken once it reaches the top of the queue and the synthesizer is in the RESUMED state. In other respects it is similar to the speak method that accepts a Speakable object.

The source of a SpeakableEvent issued to the SpeakableListener is a string.

The speak methods operate as defined only when a Synthesizer is in the ALLOCATED state. The call blocks if the Synthesizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown for synthesizers in the DEALLOCATED or DEALLOCATING_RESOURCES states.

Parameters:
plainText - string containing plain text to be spoken
listener - receives notification of events as synthesis output proceeds.
See Also:
speakSpeakable
speakTextFromURL
speakMarkupText