Overview | Package | Class | Tree | Index | Help | |||
PREV CLASS | NEXT CLASS | FRAMES | NO FRAMES | ||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Synthesizer
interface provides primary access to speech
synthesis capabilities. The Synthesizer
interface extends
the Engine
interface. Thus, any Synthesizer
implements basic speech engine capabilities plus the specialized capabilities
required for speech synthesis.
The primary functions provided by the Synthesizer
interface
are the ability to speak text, speak Java Speech Markup Language text,
and control an output queue of objects to be spoken.
Creating a Synthesizer
Typically, a Synthesizer is created by a call to the
Central.createSynthesizer
method.
The procedures for locating, selecting, creating and
initializing a Synthesizer
are described in the documentation for
Central
class.
Synthesis Package: Inherited and Extended Capabilities
A synthesis
package inherits many of its important capabilities from
the Engine
interface and its related support classes and interfaces.
The synthesis
package adds specialized functionality for
performing speech synthesis.
Central.availableSynthesizers
method and EngineModeDesc
.
EngineModeDesc
as
SynthesizerModeDesc
.
allocate
and
deallocate
methods from the
Engine
interface.
pause
and
resume
methods from the
Engine
interface.
getEngineState
,
waitEngineState
and
testEngineState
methods from the
Engine
interface.
DEALLOCATED
,
ALLOCATED
,
ALLOCATING_RESOURCES
,
DEALLOCATING_RESOURCES
,
PAUSED
and
RESUMED
states from the
Engine
interface.
QUEUE_EMPTY
and
QUEUE_NOT_EMPTY
sub-states to the
ALLOCATED
state.
Engine.getAudioManager
and AudioManager
.
addEngineListener
and
removeEngineListener
methods and uses the
EngineListener
interface.
Extends EngineListener
interface
to SynthesizerListener
.
speak(Speakable, Listener)
,
speak(URL, Listener)
,
speak(String, Listener)
and
speakPlainText(String)
methods to place text on the output queue of the synthesizer.
phoneme(String)
method that converts text to phonemes.
enumerateQueue
,
cancel()
,
cancel(Object)
and
cancelAll
methods
for management of output queue.
Speaking Text
The basic function of a Synthesizer
is to speak text provided to
it by an application. This text can be plain Unicode text in a String
or can be marked up using the
Java Speech Markup Language (JSML).
Plain text is spoken using the speakPlainText
method.
JSML text is spoken using one of the three speak
methods. The
speak
methods obtain the JSML text for a Speakable
object, from a URL
, or from a String
.
[Note: JSML text provided programmatically (by a Speakable
object
or a String
) does not require the full XML header. JSML
text obtained from a URL requires the full XML header.]
A synthesizer is mono-lingual (it speaks a single language) so the text
should contain only the single language of the synthesizer.
An application requiring output of more than one language needs to
create multiple Synthesizer
object through Central
.
The language of the Synthesizer
should be selected at
the time at which it is created. The language for a created
Synthesizer
can be checked through the Locale
of its EngineModeDesc
(see getEngineModeDesc
).
Each object provided to a synthesizer is spoken independently.
Sentences, phrases and other structures should not span multiple
call to the speak
methods.
Synthesizer State System
Synthesizer
extends the state system of the generic
Engine
interface. It inherits the four basic
allocation states, plus the PAUSED
and RESUMED
states.
Synthesizer
adds a pair of sub-states to the
ALLOCATED
state to represent the state of the
speech output queue (queuing is described in more detail below).
For an ALLOCATED
Synthesizer
, the
speech output queue is either empty or not empty: represented
by the states QUEUE_EMPTY
and QUEUE_NOT_EMPTY
.
The queue status is independent of the pause/resume status.
Pausing or resuming a synthesizer does not effect the queue.
Adding or removing objects from the queue does not effect the
pause/resume status. The only form of interaction between
these state systems is that the Synthesizer
only
speaks in the RESUMED
state, and therefore,
a transition from QUEUE_NOT_EMPTY
to QUEUE_EMPTY
because of completion of speaking an object is only possible
in the RESUMED
state. (A transition from
QUEUE_NOT_EMPTY
to QUEUE_EMPTY
is
possible in the PAUSED
state only through a call
to one of the cancel
methods.)
Speech Output Queue
A synthesizer implements a queue of items provided to it
through the speak
and speakPlainText
methods.
The queue is "first-in, first-out (FIFO)" -- the objects are
spoken in exactly he order in which they are received.
The object at the top of the queue is the object that is
currently being spoken or about to be spoken.
The QUEUE_EMPTY
and QUEUE_NOT_EMPTY
states
of a Synthesizer
indicate the current state of
of the speech output queue. The state handling methods
inherited from the Engine
interface
(getEngineState
, waitEngineState
and
testEngineState
) can be used to test the queue state.
The items on the queue can be checked with the enumerateQueue
method which returns a snapshot of the queue.
The cancel
methods allows an application to (a) stop
the output of item currently at the top of the speaking queue,
(b) remove an arbitrary item from the queue, or (c) remove
all items from the output queue.
Applications requiring more complex queuing mechanisms (e.g. a prioritized queue) can implement their own queuing objects that control the synthesizer.
Pause and Resume
The pause and resume methods (inherited from the javax.speech.Engine
interface) have behavior like a "tape player". Pause stops audio output
as soon as possible. Resume restarts audio output from the point of the pause.
Pause and resume may occur within words, phrases or unnatural points
in the speech output.
Pause and resume do not affect the speech output queue.
In addition to the ENGINE_PAUSED
and ENGINE_RESUMED
events issued to the EngineListener
(or SynthesizerListener
),
SPEAKABLE_PAUSED
and SPEAKABLE_RESUMED
events are
issued to appropriate SpeakableListeners
for the Speakable
object at the top of the speaking queue. (The SpeakableEvent
is first issued to any SpeakableListener
provided with the
speak
method, then to each SpeakableListener
attached to the Synthesizer
. Finally, the EngineEvent
is issued to each SynthesizerListener
and EngineListener
attached to the Synthesizer
.)
Applications can determine the approximate point at which a pause occurs by
monitoring the WORD_STARTED
events.
Field Summary | |
static long | QUEUE_EMPTY
Bit of state that is set when the speech output queue of a Synthesizer is empty.
|
static long | QUEUE_NOT_EMPTY
Bit of state that is set when the speech output queue of a Synthesizer is not empty.
|
Method Summary | |
void | addSpeakableListener(SpeakableListener listener)
Request notifications of all SpeakableEvents for
all speech output objects for this Synthesizer .
|
void | cancelAll()
Cancel all objects in the synthesizer speech output queue and stop speaking the current top-of-queue object. |
void | cancel()
Cancel output of the current object at the top of the output queue. |
void | cancel(Object source)
Remove a specified item from the speech output queue. |
Enumeration | enumerateQueue()
Return an Enumeration containing a snapshot of
all the objects currently on the speech output queue. |
SynthesizerProperties | getSynthesizerProperties()
Return the SynthesizerProperties object (a JavaBean).
|
String | phoneme(String text)
Returns the phoneme string for a text string. |
void | removeSpeakableListener(SpeakableListener listener)
Remove a SpeakableListener from this Synthesizer .
|
void | speakPlainText(String text,
SpeakableListener listener)
Speak a plain text string. |
void | speak(Speakable JSMLtext,
SpeakableListener listener)
Speak an object that implements the Speakable interface
and provides text marked with the
Java Speech Markup Language.
|
void | speak(URL JSMLurl,
SpeakableListener listener)
Speak text from a URL formatted with the Java Speech Markup Language. |
void | speak(String JSMLText,
SpeakableListener listener)
Speak a string containing text formatted with the Java Speech Markup Language. |
Field Detail |
public static final long QUEUE_EMPTY
Synthesizer
is empty.
The QUEUE_EMPTY
state is a sub-state
of the ALLOCATED
state. An allocated
Synthesizer
is always in either the
QUEUE_NOT_EMPTY
or QUEUE_EMPTY
state.
A Synthesizer
is always allocated in the
QUEUE_EMPTY
state. The Synthesizer
transitions from the QUEUE_EMPTY
state
to the QUEUE_NOT_EMPTY
state when a
call to one of the speak
methods places
an object on the speech output queue. A QUEUE_UPDATED
event is issued to indicate this change in state.
A Synthesizer
returns from the
QUEUE_NOT_EMPTY
state to the QUEUE_EMPTY
state once the queue is emptied because of completion
of speaking all objects or because of a cancel
.
The queue status can be tested with the waitQueueEmpty
,
getEngineState
and testEngineState
methods.
To block a thread until the queue is empty:
Synthesizer synth = ...; synth.waitEngineState(QUEUE_EMPTY);
public static final long QUEUE_NOT_EMPTY
Synthesizer
is not empty.
The QUEUE_NOT_EMPTY
state is a sub-state
of the ALLOCATED
state. An allocated
Synthesizer
is always in either the
QUEUE_NOT_EMPTY
or QUEUE_EMPTY
state.
A Synthesizer
enters the QUEUE_NOT_EMPTY
from the QUEUE_EMPTY
state when one of the
speak
methods is called to place an object
on the speech output queue. A QUEUE_UPDATED
event is issued to mark this change in state.
A Synthesizer
returns from the
QUEUE_NOT_EMPTY
state to the QUEUE_EMPTY
state once the queue is emptied because of completion
of speaking all objects or because of a cancel
.
Method Detail |
public void speak(Speakable JSMLtext, SpeakableListener listener) throws JSMLException, EngineStateError
Speakable
interface
and provides text marked with the
Java Speech Markup Language.
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 getJSMLText
method. It then checks the
syntax of the JSML markup and throws a JSMLException
if any problems are found. If the JSML 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
, waitEngineState
and
enumerateQueue
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.
JSMLText
- object implementing the Speakable interface that provides
Java Speech Markup Language text to be spoken
listener
- receives notification of events as synthesis output proceedsJSMLtext
DEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic void speak(URL JSMLurl, SpeakableListener listener) throws JSMLException, MalformedURLException, IOException, EngineStateError
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 URL
.
Because of the need to check JSML 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 the JSML text provided
in the URL. The header is optional on programmatically generated
JSML (ie. with the speak(String, Listener)
and
speak(Speakable, Listener)
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.
JSMLurl
- URL containing Java Speech Markup Language text to be spoken
JSMLException
- if any syntax errors are encountered in JSMLtext
listener
- receives notification of events as synthesis output proceedsDEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic void speak(String JSMLText, SpeakableListener listener) throws JSMLException, EngineStateError
JSMLException
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.
JSMLText
- String contains Java Speech Markup Language text to be spoken
listener
- receives notification of events as synthesis output proceeds
JSMLException
- if any syntax errors are encountered in JSMLtext
DEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic void speakPlainText(String text, SpeakableListener listener) throws EngineStateError
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 the String
object.
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.
JSMLText
- String contains plaing text to be spoken
listener
- receives notification of events as synthesis output proceedsDEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic String phoneme(String text) throws EngineStateError
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.
text
- plain text to be converted to phonemesnull
DEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic Enumeration enumerateQueue() throws EngineStateError
Enumeration
containing a snapshot of
all the objects currently on the speech output queue. The
first item is the top of the queue. An empty queue returns a
null object.
If the return value is non-null then each object it contains
is guaranteed to be a SynthesizerQueueItem
object
representing the source object (Speakable
object,
URL
, or a String
) and the JSML or
plain text obtained from that object.
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 or applet. For security reasons, it is not possible to inspect items placed by other applications.
The items on the speech queue cannot be modified by changing the object returned from this method.
The enumerateQueue
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.
Enumeration
of the speech output queue or nullDEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic void cancel() throws EngineStateError
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.
DEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic void cancel(Object source) throws IllegalArgumentException, EngineStateError
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.
source
- object to be removed from the speech output queueDEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic void cancelAll() throws EngineStateError
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.
DEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic SynthesizerProperties getSynthesizerProperties()
SynthesizerProperties
object (a JavaBean).
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 enginepublic void addSpeakableListener(SpeakableListener listener)
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
indivudal 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.
listener
- the listener that will receive SpeakableEvents
public void removeSpeakableListener(SpeakableListener listener)
SpeakableListener
from this Synthesizer
.
A SpeakableListener
can be attached or removed in any
Engine
state.
Overview | Package | Class | Tree | Index | Help | |||
PREV CLASS | NEXT CLASS | FRAMES | NO FRAMES | ||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
JavaTM Speech API
Copyright 1997-1998 Sun Microsystems, Inc. All rights reserved
Send comments to javaspeech-comments@sun.com