javax.speech.synthesis
Interface Synthesizer

All Superinterfaces:

Engine

public interface Synthesizer
extends Engine

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 Synthesizer interface provides the ability to speak plain text, speak synthesis markup text, and control an output queue of objects to be spoken.

Creating a Synthesizer

A Synthesizer is created by a call to the createEngine method. A Synthesizer for the default Voice is created as follows:

 Synthesizer synth = (Synthesizer)
     EngineManager.createEngine(SynthesizerMode.DEFAULT);
 

The synthesis package overview contains a synthesis example . Detailed descriptions of the procedures for locating, selecting, creating and initializing a Synthesizer are provided in the documentation for the EngineManager.

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 or synthesis markup text using the Speech Synthesis Markup Language (SSML).

Plain text is spoken using one of the speak methods. Markup text is spoken using the speakMarkup method. The other speak methods obtain markup text from a Speakable object or from an AudioSegment (if needed and provided).

Each object provided to a Synthesizer is spoken independently. Sentences, phrases and other structures should not span multiple calls to the speak methods.

Text Normalization

Text presented to a Synthesizer may include punctuation, dates, times, numbers, money values, etc. The Synthesizer will do its best to convert the text to spoken form using a process known as "text normalization".

Lexical text normalization produces normal words from input tokens (e.g., the input "100" results in "one hundred"). Punctuation within text can change the way that it is rendered (e.g., a question mark at the end results in a rise in pitch for English).

The text normalization process can be complex and is language and platform dependent. Applications may use normal words and simple punctuation to avoid any misinterpretation.

Resolving References

Synthesis markup text may use standard URI conventions to refer to resources. Examples include references to audio and lexicon resources. The standard SSML conventions for resolving any relative references apply (see "Resolving Relative URIs"). If any further resolution is required, information from the following method is used:

• EngineProperties.getBase

A special "resource:" scheme may be used to force resolution with getResourceAsStream. This avoids unintended redirection of references that begin with "/" by EngineProperties.setBase. See that method for details.

Synthesizer Voices

A Synthesizer may be mono-lingual (it speaks a single language) in which case the text should contain only the single language of the Synthesizer. An application requiring output of more than one language with a mono-lingual Synthesizer may create multiple Synthesizer objects through the EngineManager. The language of the Synthesizer should be selected at the time at which it is created. The languages for a created Synthesizer can be checked through the Voices of its SynthesizerMode (see getEngineMode).

Synthesizer States

The Synthesizer interface adds a pair of substates to the ALLOCATED state to represent the state of the Synthesizer Output Queue. For an ALLOCATED Synthesizer, the output queue is either empty or not empty represented by the states QUEUE_EMPTY and QUEUE_NOT_EMPTY, respectively.

The queue status is independent of the PAUSED/RESUMED state. Calling pause or resume on a Synthesizer does not affect the queue. Adding or removing objects from the queue does not affect the PAUSED/RESUMED state. 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.

A Synthesizer starts in the RESUMED state.

See the Table of Diagrams for state transition diagrams.

Synthesizer Output Queue

A Synthesizer implements a queue of items provided to it through the speak and speakMarkup methods. The queue is "first-in, first-out" (FIFO) - the objects are spoken in exactly the order in which they are received.

When the queue is updated, a QUEUE_UPDATE event is issued to each attached SynthesizerListener. An object is be spoken once it reaches the top (or front) of the queue and the Synthesizer is in the RESUMED state.

Objects are added to the queue asynchronously. The SpeakableEvent class describes how to use SpeakableListeners to monitor the progress of objects on the queue. An application needing to know when the Speakable has been spoken should wait for the SPEAKABLE_ENDED or SPEAKABLE_CANCELLED events issued to a SpeakableListener.

The QUEUE_EMPTY and QUEUE_NOT_EMPTY states indicate the current state of the Synthesizer output queue. The state handling methods inherited from the Engine interface (getEngineState, waitEngineState and testEngineState) can be used to test the queue state.

The cancel methods allow an application to

• cancel() - stop the output of the item currently at the top of the queue,
• cancel(int) - remove an arbitrary item from the queue, or
• cancelAll() - remove all items from the queue.

Focus Policy

As synthesis requests are made, focus is implicitly requested. The timing of synthesis depends on the priority of this Synthesizer (see getPriority) and the interruptibility of other Synthesizers (see getInterruptibility). Focus is implicitly released in the QUEUE_EMPTY state or if another Synthesizer gains focus.

Once a Synthesizer gains focus, it is in the Engine.FOCUSED state. Once it loses focus, it is in the Engine.DEFOCUSED state. Entry to and exit from these states are indicated by the ENGINE_FOCUSED and ENGINE_DEFOCUSED events.

pause and resume

The pause and resume methods (inherited from the Engine interface) provide behavior similar to 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.

As mentioned, pause and resume do not affect the Synthesizer output queue.

In addition to the ENGINE_PAUSED and ENGINE_RESUMED events issued to the SynthesizerListener, SPEAKABLE_PAUSED and SPEAKABLE_RESUMED events are issued to appropriate SpeakableListeners for the Speakable object at the top of the Synthesizer output queue. The SpeakableEvent class describes how to attach SpeakableListeners and the order of events delivered.

Applications can determine the approximate point at which a pause takes affect by monitoring the WORD_STARTED events.

Conditions for Operation

Where noted, standard Conditions for Operation apply. This means that a method operates as defined only when the Engine is in the ALLOCATED state and not DEALLOCATING_RESOURCES. The call blocks if the Engine is in the ALLOCATING_RESOURCES state and completes when the Engine reaches the ALLOCATED state. Otherwise, an exception is thrown for an Engine in the DEALLOCATING_RESOURCES or DEALLOCATED states.

See Also:

EngineManager, Engine, SynthesizerEvent, SynthesizerListener, Speakable, SpeakableEvent, SpeakableListener, Voice

Field Summary

static long	QUEUE_EMPTY Bit of state that is set when the Synthesizer output queue is empty.
static long	QUEUE_NOT_EMPTY Bit of state that is set when the Synthesizer output queue is not empty.

Fields inherited from interface Engine

ALLOCATED, ALLOCATING_RESOURCES, ASYNCHRONOUS_MODE, DEALLOCATED, DEALLOCATING_RESOURCES, DEFOCUSED, ERROR_OCCURRED, FOCUSED, IMMEDIATE_MODE, PAUSED, RESUMED

Method Summary

void	addSpeakableListener(SpeakableListener listener) Request notifications of all SpeakableEvents for all items on the Synthesizer output queue.
void	addSynthesizerListener(SynthesizerListener listener) Request notifications of events related to general operation of this Synthesizer.
void	allocate() Allocates the resources required for this Engine and puts it into the ALLOCATED state.
void	allocate(int mode) Allocates the resources required for this Engine using the mode specified and puts it into the ALLOCATED state.
boolean	cancel() Cancels output of the current object at the top of the Synthesizer output queue.
boolean	cancel(int id) Removes the object specified by the id from the Synthesizer output queue.
boolean	cancelAll() Cancels all objects in the Synthesizer output queue and stops speaking the current top-of-queue object.
void	deallocate() Deallocates the resources acquired for this Engine and returns it to the DEALLOCATED state.
void	deallocate(int mode) Deallocates the resources acquired for this Engine using the mode specified and returns it to the DEALLOCATED state.
int	getSpeakableMask() Gets the mask to filter events for added SpeakableListeners.
SynthesizerProperties	getSynthesizerProperties() Returns the properties of this Synthesizer.
void	pause() Pauses the audio processing for this Engine and puts it into the PAUSED state.
void	removeSpeakableListener(SpeakableListener listener) Removes a SpeakableListener from this Synthesizer.
void	removeSynthesizerListener(SynthesizerListener listener) Removes a SynthesizerListener from this Synthesizer.
boolean	resume() Resumes audio processing for this Engine by entering the RESUMED state.
void	setSpeakableMask(int mask) Sets the mask to filter events for added SpeakableListeners.
int	speak(AudioSegment audio, SpeakableListener listener) Speaks an AudioSegment.
int	speak(Speakable speakable, SpeakableListener listener) Speaks an object that provides synthesis markup text through the Speakable interface.
int	speak(String text, SpeakableListener listener) Speaks a plain text String.
int	speakMarkup(String synthesisMarkup, SpeakableListener listener) Speaks a String containing text synthesis markup text.

Methods inherited from interface Engine

getAudioManager, getEngineMask, getEngineMode, getEngineState, getSpeechEventExecutor, getVocabularyManager, setEngineMask, setSpeechEventExecutor, testEngineState, waitEngineState, waitEngineState

Field Detail

QUEUE_EMPTY

static final long QUEUE_EMPTY

Bit of state that is set when the Synthesizer output queue is empty. The QUEUE_EMPTY state is a substate 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 or speakMarkup methods places an object on the Synthesizer output queue. A QUEUE_UPDATED event indicates this state change.

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. A QUEUE_EMPTIED event indicates this state change.

The queue status can be tested with the waitEngineState, getEngineState and testEngineState methods. Example:

 // Block a thread until the queue is empty
 Synthesizer synth = ...;
 synth.allocate();                          // allocate resources
 synth.speak("hello world", null);          // speak
 synth.waitEngineState(QUEUE_EMPTY);        // wait for finish
 

See Also:

speak, speakMarkup, QUEUE_NOT_EMPTY, Engine.ALLOCATED, getEngineState, waitEngineState, testEngineState, SynthesizerEvent.QUEUE_UPDATED, SynthesizerEvent.QUEUE_EMPTIED, Constant Field Values

QUEUE_NOT_EMPTY

static final long QUEUE_NOT_EMPTY

Bit of state that is set when the Synthesizer output queue is not empty. The QUEUE_NOT_EMPTY state is a substate 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 state from the QUEUE_EMPTY state when one of the speak or speakMarkup methods places an object on the Synthesizer output queue. A QUEUE_UPDATED event indicates this state change.

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. A QUEUE_EMPTIED event indicates this state change.

See Also:

QUEUE_EMPTY, Engine.ALLOCATED, getEngineState, waitEngineState, testEngineState, SynthesizerEvent.QUEUE_UPDATED, SynthesizerEvent.QUEUE_EMPTIED, Constant Field Values

Method Detail

addSpeakableListener

void addSpeakableListener(SpeakableListener listener)

Request notifications of all SpeakableEvents for all items on the Synthesizer output queue.

An application can attach multiple SpeakableListeners to a Synthesizer. A single SpeakableListener can be attached to multiple Synthesizers.

When an event affects more than one item in the Synthesizer 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 be provided for an individual Synthesizer output queue item by providing it as a parameter to one of the speak or speakMarkup methods.

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

SpeakableEvents may be filtered with setSpeakableMask.

Use addSynthesizerListener for notifications related to general operation of this Synthesizer.

Parameters:

listener - the SpeakableListener that will receive SpeakableEvents

See Also:

cancelAll, speak, speakMarkup, SpeakableEvent, SpeakableListener, removeSpeakableListener, setSpeakableMask, addSynthesizerListener

addSynthesizerListener

void addSynthesizerListener(SynthesizerListener listener)

Request notifications of events related to general operation of this Synthesizer. The SynthesizerEvent class provides details about these events.

An application can attach multiple SynthesizerListeners to this Synthesizer. A single SynthesizerListener can be attached to multiple Synthesizers.

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

SynthesizerEvents may be filtered with setEngineMask.

Use addSpeakableListener for notifications related to individual items on the Synthesizer output queue.

Parameters:

listener - the SynthesizerListener that will receive SynthesizerEvents

See Also:

SynthesizerEvent, SynthesizerListener, removeSynthesizerListener, setEngineMask, addSpeakableListener

cancel

boolean cancel()
               throws EngineStateException

Cancels output of the current object at the top of the Synthesizer output queue. This method returns false if the Synthesizer output queue is empty.

This method returns true if this call results in cancellation. In that case a SPEAKABLE_CANCELLED event is issued to appropriate SpeakableListeners. Also, SynthesizerListeners receive either a QUEUE_UPDATED or QUEUE_EMPTIED event.

If there is another object in the output 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.

This method operates as defined when the standard Conditions for Operation apply.

Returns:

true when this call results in cancellation of the requested object, and false otherwise

Throws:

EngineStateException - when not in the standard Conditions for Operation

See Also:

pause, PAUSED, SPEAKABLE_CANCELLED, TOP_OF_QUEUE, SpeakableListener, SynthesizerEvent.QUEUE_UPDATED, SynthesizerEvent.QUEUE_EMPTIED, SynthesizerListener

cancel

boolean cancel(int id)
               throws EngineStateException

Removes the object specified by the id from the Synthesizer output queue. The id must be a request ID returned from a speak or speakMarkup method.

This method returns true if this call results in cancellation. In that case a SPEAKABLE_CANCELLED event is issued to appropriate SpeakableListeners. Also, SynthesizerListeners receive either a QUEUE_UPDATED or QUEUE_EMPTIED event. This method returns false if the specified object has already been processed or cancelled.

If the requested object is the top item in the queue, the behavior is the same as the cancel() method. If the requested object is not at the top of the queue, it is removed from the queue without affecting output for the current top-of-queue object.

This method operates as defined when the standard Conditions for Operation apply.

Parameters:

id - id for object to be removed from the Synthesizer output queue

Returns:

true when this call results in cancellation of the requested object, and false otherwise

Throws:

EngineStateException - when not in the standard Conditions for Operation

See Also:

speak, speak, speak, speakMarkup, SynthesizerEvent.QUEUE_UPDATED, SynthesizerEvent.QUEUE_EMPTIED, SynthesizerListener

cancelAll

boolean cancelAll()
                  throws EngineStateException

Cancels all objects in the Synthesizer output queue and stops speaking the current top-of-queue object.

This method returns true if this call results in cancellation. In that case the SpeakableListeners of each cancelled item on the queue receive a SPEAKABLE_CANCELLED event. Also, SynthesizerListeners receive a QUEUE_EMPTIED event. This method returns false if all objects at the time of the call have already been processed or cancelled.

A call to deallocate(IMMEDIATE_MODE) performs an implicit cancelAll.

This method operates as defined when the standard Conditions for Operation apply.

Returns:

true when this call results in cancellation of at least one object, and false otherwise

Throws:

EngineStateException - when not in the standard Conditions for Operation

See Also:

cancel, cancel(int), deallocate, SynthesizerEvent.QUEUE_EMPTIED, SpeakableEvent.SPEAKABLE_CANCELLED, SynthesizerListener, SpeakableListener

getSynthesizerProperties

SynthesizerProperties getSynthesizerProperties()

Returns the properties of this Synthesizer.

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

Returns:

the SynthesizerProperties for this Synthesizer

See Also:

ALLOCATED

removeSpeakableListener

void removeSpeakableListener(SpeakableListener listener)

Removes a SpeakableListener from this Synthesizer.

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

Parameters:

listener - the SpeakableListener to remove

See Also:

addSpeakableListener

removeSynthesizerListener

void removeSynthesizerListener(SynthesizerListener listener)

Removes a SynthesizerListener from this Synthesizer. A SynthesizerListener can be removed in any Engine state.

Parameters:

listener - the SynthesizerListener to remove

See Also:

addSynthesizerListener

speak

int speak(AudioSegment audio,
          SpeakableListener listener)
          throws SpeakableException,
                 EngineStateException,
                 IllegalArgumentException

Speaks an AudioSegment. The AudioSegment is placed at the end of the Synthesizer output queue and will be spoken once it reaches the top of the queue and the Synthesizer is in the RESUMED state.

If the audio cannot be played, and getMarkupText returns non-null, the markup text will be used as if speakMarkup were called. Otherwise, a SPEAKABLE_FAILED event is issued. If markup text is available and formatting errors are found, a SpeakableException is thrown. Markup errors may also be encountered during synthesis in which case they are reported in a SPEAKABLE_FAILED event.

The following two audio formats are supported as a minimum:

• 16-bit, 8 KHz, PCM
• 8-bit, 8 KHz, CCITT A-law as exemplified by turca.wav

Support for 16-bit, 16 KHz, PCM audio is recommended.

The Synthesizer Output Queue section details item processing and associated SpeakableEvents. SPEAKABLE_FAILED events may occur during processing with additional SpeakableException information. The source of a SpeakableEvent issued to a SpeakableListener is the audio parameter.

This method operates as defined when the standard Conditions for Operation apply.

Parameters:

audio - an AudioSegment to be spoken

listener - receives notification of events as synthesis output proceeds

Returns:

a unique id for this request

Throws:

SpeakableException - if synthesis markup is available and any errors are encountered

EngineStateException - when not in the standard Conditions for Operation

IllegalArgumentException - if the Synthesizer cannot interpret the AudioSegment

See Also:

addSpeakableListener, SpeakableEvent, SpeakableEvent.SPEAKABLE_FAILED, speakMarkup

speak

int speak(Speakable speakable,
          SpeakableListener listener)
          throws SpeakableException,
                 EngineStateException

Speaks an object that provides synthesis markup text through the Speakable interface.

The Synthesizer first requests the markup text of the Speakable by calling its getMarkupText method. Once the markup text is obtained, this method behaves the same as the speakMarkup method. See that method for details.

The Synthesizer Output Queue section details item processing and associated SpeakableEvents. SPEAKABLE_FAILED events may occur during processing with additional SpeakableException information. The source of a SpeakableEvent issued to a SpeakableListener is the speakable parameter.

This method operates as defined when the standard Conditions for Operation apply.

Parameters:

speakable - implements the Speakable interface that provides synthesis markup text to be spoken

listener - receives notification of events as synthesis output proceeds

Returns:

a unique id for this request

Throws:

SpeakableException - if any errors are encountered in the synthesis markup

EngineStateException - when not in the standard Conditions for Operation

See Also:

getMarkupText, SpeakableEvent, SpeakableListener, SpeakableEvent.SPEAKABLE_FAILED, getSupportsMarkup

Required Features:

getSupportsLetterToSound when the vocabulary specified is not already present within the Synthesizer

speak

int speak(String text,
          SpeakableListener listener)
          throws EngineStateException

Speaks a plain text String. The text is placed on the Synthesizer output queue and will be spoken once it reaches the top of the queue and the Synthesizer is in the RESUMED state.

Text Normalization considerations apply to this method. In addition, this method does not expect markup - all input is subject to the Synthesizer's text normalization process.

To speak plain text from a URL, download the text and then use this method.

The Synthesizer Output Queue section details item processing and associated SpeakableEvents. SPEAKABLE_FAILED events may occur during processing with additional SpeakableException information. The source of a SpeakableEvent issued to a SpeakableListener is the text parameter.

This method operates as defined when the standard Conditions for Operation apply.

Parameters:

text - contains plain text to be spoken

listener - receives notification of events as synthesis output proceeds

Returns:

a unique id for this request

Throws:

EngineStateException - when not in the standard Conditions for Operation

See Also:

SpeakableEvent, SpeakableListener, SpeakableEvent.SPEAKABLE_FAILED, speakMarkup

Required Features:

getSupportsLetterToSound when the vocabulary specified is not already present within the Synthesizer

speakMarkup

int speakMarkup(String synthesisMarkup,
                SpeakableListener listener)
                throws SpeakableException,
                       EngineStateException

Speaks a String containing text synthesis markup text. The markup text must be well formed.

If no formatting errors are found, the text is placed at the end of the Synthesizer output queue and will be spoken once it reaches the top of the queue and the Synthesizer is in the RESUMED state.

If formatting errors are found, a SpeakableException is thrown. Markup errors may also be encountered during synthesis in which case they are reported in a SPEAKABLE_FAILED event.

The speakingRate property (see setSpeakingRate) affects the baseline speaking rate of synthesis markup. The rate at the time of this call is used, not the rate when rendered.

If the Synthesizer does not support markup (see getSupportsMarkup), then the markup is removed before rendering the associated text.

Text Normalization considerations apply to this method. Markup text is interpreted in conjunction with text normalization.

To speak markup from a URL, download the markup first and then use this method.

The following example includes emphasis and a change in rate:

 Synthesizer synth = ...
 synth.speakMarkup(
     "<speak xml:lang='en-US' version='1.0'>" +
         "I <emphasis>really</emphasis> like" + 
         "<prosody rate='slow'>speech</prosody>" +
     "</speak>",
     null);
 

The Synthesizer Output Queue section details item processing and associated SpeakableEvents. SPEAKABLE_FAILED events may occur during processing with additional SpeakableException information. The source of a SpeakableEvent issued to a SpeakableListener is the synthesisMarkup parameter.

This method operates as defined when the standard Conditions for Operation apply.

Parameters:

synthesisMarkup - contains synthesis markup text to speak

listener - receives notification of events as synthesis output proceeds

Returns:

a unique id for this request

Throws:

SpeakableException - if any errors are encountered in the synthesis markup

EngineStateException - when not in the standard Conditions for Operation

See Also:

speak(String,SpeakableListener), SpeakableEvent.SPEAKABLE_FAILED, addSpeakableListener, SpeakableEvent, getSupportsMarkup, setBase

Required Features:

getSupportsLetterToSound when the vocabulary specified is not already present within the Synthesizer

allocate

void allocate()
              throws AudioException,
                     EngineException,
                     EngineStateException,
                     SecurityException

Allocates the resources required for this Engine and puts 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.

While this method is being processed, events are issued to any EngineListeners attached to the Engine to indicate state changes (see setEngineMask for event filtering). 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 in 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 use allocate(int) with a flag for asynchronous operation

When the Engine reaches the ALLOCATED state, other Engine substates are determined according to the type of Engine. Each Engine subclass provides more detail.

Note that there are currently no required permissions defined in this API for this method.

Specified by:

allocate in interface Engine

Throws:

AudioException - if any audio request fails

EngineException - if an allocation error occurred or the Engine is not operational.

EngineStateException - if called for an Engine in the DEALLOCATING_RESOURCES state

SecurityException - if the application does not have permission for this Engine

See Also:

allocate(int), deallocate(), getEngineState, ALLOCATED, ALLOCATING_RESOURCES, DEALLOCATED, EngineEvent, ENGINE_ALLOCATED, ENGINE_DEALLOCATED, setEngineMask

Required permission:

none defined

allocate

void allocate(int mode)
              throws IllegalArgumentException,
                     AudioException,
                     EngineException,
                     EngineStateException,
                     SecurityException

Allocates the resources required for this Engine using the mode specified and puts it into the ALLOCATED state.

When the mode is ASYNCHRONOUS_MODE, this method asynchronously allocates an Engine. In this case, the Engine transitions to ALLOCATING_RESOURCES before this method returns.

When mode is 0, this method operates the same as allocate().

waitEngineState may be used to wait for the ALLOCATED state.

 Engine engine;

 engine = EngineManager.createEngine(RecognizerMode.DEFAULT);
 engine.allocate(Engine.ASYNCHRONOUS_MODE);
 // Do other stuff while allocation takes place
 ...
 // Now wait until allocation is complete
 engine.waitEngineState(Engine.ALLOCATED);
 

Note that there are currently no required permissions defined in this API for this method.

Specified by:

allocate in interface Engine

Parameters:

mode - flag indicating the operational mode

Throws:

IllegalArgumentException - if called with an unexpected mode value

AudioException - if any audio access fails

EngineException - if an allocation error occurred or the Engine is not operational.

EngineStateException - if called for an Engine in the DEALLOCATING_RESOURCES state

SecurityException - if the application does not have permission for this Engine

See Also:

ASYNCHRONOUS_MODE, allocate(), deallocate(), getEngineState, ALLOCATED, ALLOCATING_RESOURCES, DEALLOCATED, EngineEvent, ENGINE_ALLOCATED, ENGINE_DEALLOCATED, setEngineMask, waitEngineState

Required permission:

none defined

deallocate

void deallocate()
                throws AudioException,
                       EngineException,
                       EngineStateException

Deallocates the resources acquired for this Engine and returns it to the DEALLOCATED state. 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 restarted with a subsequent call to allocate.

Engines should normally clean up current activities before becoming DEALLOCATED. If needed, deallocate will wait for pending operations to complete appropriate for the type of Engine. The deallocate(int) method includes a flag to stop pending operations immediately.

Deallocating resources for an Engine is not always immediate. Use the deallocate(int) method with a flag for asynchronous operation. The documentation for the allocate(int) method shows an example of asynchronous operation

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 in either the DEALLOCATING_RESOURCES or DEALLOCATED states. The method throws an exception in the ALLOCATING_RESOURCES state.

Specified by:

deallocate in interface Engine

Throws:

AudioException - if any audio request fails

EngineException - if a deallocation error occurs

EngineStateException - if called for an Engine in the ALLOCATING_RESOURCES state

See Also:

deallocate(int), allocate(), allocate(int), ASYNCHRONOUS_MODE, IMMEDIATE_MODE, DEALLOCATED, DEALLOCATING_RESOURCES, EngineEvent, ENGINE_DEALLOCATING_RESOURCES, ENGINE_DEALLOCATED

deallocate

void deallocate(int mode)
                throws IllegalArgumentException,
                       AudioException,
                       EngineException,
                       EngineStateException

Deallocates the resources acquired for this Engine using the mode specified and returns it to the DEALLOCATED state.

When using ASYNCHRONOUS_MODE, this method asynchronously deallocates an Engine. In this case, the Engine transitions to DEALLOCATING_RESOURCES before this method returns.

When using IMMEDIATE_MODE, this method causes the Engine to stop pending operations immediately before beginning the deallocation process.

The mode values may be combined. Calling deallocate(ASYNCHRONOUS_MODE | IMMEDIATE_MODE) combines the behavior of both modes.

When mode is 0, this method operates the same as deallocate().

Specified by:

deallocate in interface Engine

Parameters:

mode - flag indicating the operational mode

Throws:

IllegalArgumentException - if called with an unexpected mode value

AudioException - if any audio request fails

EngineException - if a deallocation error occurs

EngineStateException - if called for an Engine in the ALLOCATING_RESOURCES state

See Also:

deallocate(), allocate(), ASYNCHRONOUS_MODE, IMMEDIATE_MODE, DEALLOCATED, DEALLOCATING_RESOURCES, EngineEvent, ENGINE_DEALLOCATING_RESOURCES, ENGINE_DEALLOCATED, waitEngineState

pause

void pause()
           throws EngineStateException

Pauses the audio processing for this Engine and puts it into the PAUSED state. Pausing an Engine pauses the Engine instance and does not affect other Engine instances in the current application or other applications, even though they may use the same underlying resources.

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 substate 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 does not always return immediately. Some applications may want to execute pause in a separate Thread.

Note that calls to pause and resume nest, so that there must be a resume for each pause in order for resume to operate as described.

This method operates as defined when the standard Conditions for Operation apply.

Operational detail depends on the particular Engine subinterface. For Engines that produce audio, pausing is analogous to pressing the "pause" button on a tape or CD player - audio output is paused and any unplayed audio is heard after resume. For Engines that consume audio, pausing is analogous to pressing a "mute" button on a microphone - by default, audio input is ignored and permanently lost. Audio processing does not begin again until after resume.

For a Synthesizer, the Synthesizer output queue is left intact and a subsequent resume continues output from the point at which the pause took effect.

Specified by:

pause in interface Engine

Throws:

EngineStateException - when not in the standard Conditions for Operation

See Also:

resume, getEngineState, EngineEvent.ENGINE_PAUSED

resume

boolean resume()
               throws EngineStateException

Resumes audio processing for this Engine by entering the RESUMED state. Resuming an Engine instance does not affect other Engine instances that share the same underlying resources.

The pause method describes how to pause an Engine.

Note that calls to pause and resume nest, so that there must be a resume for each pause in order for this method to operate as described.

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 when the Engine resumes, and can be tested by the getEngineState method and other Engine state methods.

The RESUMED state is a substate of the ALLOCATED state. An ALLOCATED Engine is always in either the PAUSED or the RESUMED state.

It is not an exception to resume an Engine that is already in the RESUMED state.

The resume method does not always return immediately. Some applications may want to execute resume in a separate Thread. The documentation for the Thread class shows examples of this.

This method operates as defined when the standard Conditions for Operation apply.

Specified by:

resume in interface Engine

Returns:

true if the Engine is in or is about to enter the RESUMED state; or false if it will remain PAUSED due to nested calls to pause.

Throws:

EngineStateException - when not in the standard Conditions for Operation

See Also:

pause, getEngineState, EngineEvent.ENGINE_RESUMED, Thread

setSpeakableMask

void setSpeakableMask(int mask)

Sets the mask to filter events for added SpeakableListeners.

It can improve efficiency to mask events that are not used. Events of interest can be seen by using the logical OR of the event constants defined in the SpeakableEvent class. SpeakableEvent.DEFAULT_MASK is the initial value.

The event mask can be set and retrieved in any Synthesizer state. This method affects filtering of all attached SpeakableListeners.

Parameters:

mask - the mask for SpeakableEvents

See Also:

SpeakableEvent, SpeakableEvent.DEFAULT_MASK, SpeakableListener, getSpeakableMask

getSpeakableMask

int getSpeakableMask()

Gets the mask to filter events for added SpeakableListeners.

See setSpeakableMask for details.

The event mask can be set and retrieved in any Synthesizer state.

Returns:

the current mask for SpeakableEvents

See Also:

SpeakableEvent, SpeakableListener, setSpeakableMask