Operations Summary: | |
void | addSpeakableListener(in SpeakableListener listener) |
void | removeSpeakableListener(in SpeakableListener listener) |
long | getNumberOfQueueItems() raises |
SynthesizerQueueItem | getQueueItem(in long n) raises |
void | cancel() raises |
void | cancelItem(in SpeechObject source) raises |
void | cancelAll() raises |
SynthesizerProperties | getSynthesizerProperties() |
string | phoneme(in string text) raises |
boolean | isMarkupTypeSupported(in MarkupType type) |
void | speakMarkupText(in string markupText, in SpeakableListener listener) raises |
void | speakTextFromURL(in SpeechURL markupURL, in SpeakableListener listener) raises |
void | speakSpeakable(in Speakable markupText, in SpeakableListener listener) raises |
void | speakPlainText(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: |
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.
SpeakableEvents
. removeSpeakableListener
Remove a SpeakableListener
from this
Synthesizer
.
A SpeakableListener
can be attached or removed in
any Engine
state.
addSpeakableListener
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.
getQueueItem
SynthesizerQueueItem
SynthesizerEvent#QUEUE_UPDATED
SynthesizerEvent#QUEUE_EMPTIED
Engine#addEngineListener
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.
SynthesizerQueueItem
SynthesizerEvent#QUEUE_UPDATED
SynthesizerEvent#QUEUE_EMPTIED
Engine#addEngineListener
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.
cancelItem
cancelAll
SynthesizerEvent#QUEUE_UPDATED
SynthesizerEvent#QUEUE_EMPTIED
SpeakableEvent#TOP_OF_QUEUE
SpeakableEvent#SPEAKABLE_CANCELLED
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.
cancel
cancelAll
SynthesizerEvent#QUEUE_UPDATED
SynthesizerEvent#QUEUE_EMPTIED
SpeakableEvent#SPEAKABLE_CANCELLED
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.
cancel
cancelItem
SynthesizerEvent#QUEUE_EMPTIED
SpeakableEvent#SPEAKABLE_CANCELLED
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.
SynthesizerProperties
object for this engine. Engine#getEngineProperties
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.
Return an indication of whether this markup type is supported.
Synthesizer
supports this markup type.MARKUP_JSML
MARKUP_SSML
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.
speakSpeakable
speakTextFromURL
speakPlainText
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.
speakSpeakable
speakMarkupText
speakPlainText
SpeakableEvent
addSpeakableListener
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.
speakMarkupText
speakTextFromURL
speakPlainText
SpeakableEvent
addSpeakableListener
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.
speakSpeakable
speakTextFromURL
speakMarkupText