javax.speech.synthesis
Interface SynthesizerProperties

All Superinterfaces:

EngineProperties

public interface SynthesizerProperties
extends EngineProperties

Provides run-time control of the properties of a Synthesizer. The SynthesizerProperties object is obtained by calling the getSynthesizerProperties method.

SynthesizerProperties inherits the following behavior from the EngineProperties interface (see that interface for more detail):

• Each property has a get and set method (JavaBeans property method patterns).
• An Engine may ignore calls to change properties, for example by applying maximum and minimum settings.
• Calls to set methods may be asynchronous (they may return before the property change takes effect). The Engine will apply a change as soon as possible. An EnginePropertyEvent is issued when the change takes effect. For example, a change in the speaking rate might take place immediately, or at the end of the current word, sentence or paragraph.
• The get methods return the current setting - not a pending value.
• An EnginePropertyListener may be attached to receive EnginePropertyEvents.
• Where appropriate, property settings are persistent across sessions.

The primary properties of a Synthesizer are:

• Speaking voice,
• Baseline pitch,
• Pitch range,
• Speaking rate,
• Volume.

Setting these properties should be considered as a hint to the Synthesizer. A Synthesizer may choose to ignore out-of-range values. A Synthesizer may have some properties that are unchangeable (e.g. a single Voice Synthesizer). Reasonable values for baseline pitch, pitch range and speaking rate may vary between Synthesizers, between languages and or between Voices.

A change in Voice may lead to change in other properties. For example, female and young voices typically have higher pitches than male voices. When a change in Voice leads to changes in other properties, a separate EnginePropertyEvent is issued for each property changed.

Whenever possible, property changes should be persistent for a Voice. For instance, after changing from Voice A to Voice B and back, the previous property settings for Voice A should return.

Changes in pitch, speaking rate and so on in markup text provided to the Synthesizer do not affect the baseline values reflected in this interface. These changes may be tracked through SpeakableEvents.

Additional properties include

• Interruptibility level,
• Priority.

Setting these values helps determine the speaking order of items between Synthesizer instances. Priority may differ between trusted applications (such as those installed directly on the device) and untrusted applications (such as those downloaded from the Web).

See Also:

Synthesizer, getSynthesizerProperties, EngineProperties, addEnginePropertyListener, removeEnginePropertyListener, SpeakableEvent

Field Summary

static int	DEFAULT_RATE The natural speaking rate for a given Voice.
static int	DEFAULT_VOLUME The default volume level.
static int	FAST_RATE A fast speaking rate.
static int	MAX_VOLUME The maximum volume level.
static int	MEDIUM_RATE A medium speaking rate.
static int	MEDIUM_VOLUME A value representing medium volume level.
static int	MIN_VOLUME The minimum volume level.
static int	OBJECT_LEVEL The value for object-level interruptibility.
static int	QUEUE_LEVEL The value for queue-level interruptibility.
static int	SLOW_RATE A slow speaking rate.
static int	WORD_LEVEL The value for word-level interruptibility.
static int	X_FAST_RATE An extra fast speaking rate.
static int	X_SLOW_RATE An extra-slow speaking rate.

Fields inherited from interface EngineProperties

MAX_PRIORITY, MAX_UNTRUSTED_PRIORITY, MIN_PRIORITY, NORM_TRUSTED_PRIORITY, NORM_UNTRUSTED_PRIORITY

Method Summary

int	getInterruptibility() Gets the interruptibility property.
int	getPitch() Gets the pitch property.
int	getPitchRange() Gets the pitchRange property.
int	getPriority() Gets the priority property.
int	getSpeakingRate() Gets the speakingRate property.
Voice	getVoice() Gets the voice property.
int	getVolume() Gets the volume property.
void	setInterruptibility(int level) Sets the interruptibility property.
void	setPitch(int hertz) Set the pitch property.
void	setPitchRange(int hertz) Sets the pitchRange property.
void	setPriority(int priority) Sets the priority property.
void	setSpeakingRate(int rate) Sets the speakingRate property.
void	setVoice(Voice voice) Sets the voice property.
void	setVolume(int volume) Sets the volume property.

Methods inherited from interface EngineProperties

addEnginePropertyListener, getBase, removeEnginePropertyListener, reset, setBase

Field Detail

WORD_LEVEL

static final int WORD_LEVEL

The value for word-level interruptibility.

See Also:

setInterruptibility, Constant Field Values

OBJECT_LEVEL

static final int OBJECT_LEVEL

The value for object-level interruptibility.

See Also:

setInterruptibility, Constant Field Values

QUEUE_LEVEL

static final int QUEUE_LEVEL

The value for queue-level interruptibility.

See Also:

setInterruptibility, Constant Field Values

MIN_VOLUME

static final int MIN_VOLUME

The minimum volume level.

See Also:

setVolume, Constant Field Values

MEDIUM_VOLUME

static final int MEDIUM_VOLUME

A value representing medium volume level. This value is between MIN_VOLUME and MAX_VOLUME.

See Also:

MIN_VOLUME, MAX_VOLUME, setVolume, Constant Field Values

DEFAULT_VOLUME

static final int DEFAULT_VOLUME

The default volume level. For compatibility with SSML, this is set to MAX_VOLUME.

See Also:

MAX_VOLUME, setVolume, Constant Field Values

MAX_VOLUME

static final int MAX_VOLUME

The maximum volume level.

See Also:

setVolume, Constant Field Values

DEFAULT_RATE

static final int DEFAULT_RATE

The natural speaking rate for a given Voice.

See Also:

setSpeakingRate, Voice, Constant Field Values

X_SLOW_RATE

static final int X_SLOW_RATE

An extra-slow speaking rate.

See Also:

setSpeakingRate, Constant Field Values

SLOW_RATE

static final int SLOW_RATE

A slow speaking rate.

See Also:

setSpeakingRate, Constant Field Values

MEDIUM_RATE

static final int MEDIUM_RATE

A medium speaking rate.

See Also:

setSpeakingRate, Constant Field Values

FAST_RATE

static final int FAST_RATE

A fast speaking rate.

See Also:

setSpeakingRate, Constant Field Values

X_FAST_RATE

static final int X_FAST_RATE

An extra fast speaking rate.

See Also:

setSpeakingRate, Constant Field Values

Method Detail

getInterruptibility

int getInterruptibility()

Gets the interruptibility property.

Returns:

the interruptibility level for synthesis

See Also:

setInterruptibility

getPitch

int getPitch()

Gets the pitch property.

Returns:

the baseline pitch in Hertz for synthesis

See Also:

setPitch

getPitchRange

int getPitchRange()

Gets the pitchRange property.

Returns:

the pitch range in Hertz for synthesis

See Also:

setPitchRange

getPriority

int getPriority()

Gets the priority property.

Specified by:

getPriority in interface EngineProperties

Returns:

the priority for this Engine instance

See Also:

setPriority

getSpeakingRate

int getSpeakingRate()

Gets the speakingRate property.

The setSpeakingRate method describes more detail.

Returns:

the current target speaking rate

See Also:

setSpeakingRate

getVoice

Voice getVoice()

Gets the voice property. The Voice may be changed using setVoice.

Returns:

the current Voice for synthesis

See Also:

setVoice

getVolume

int getVolume()

Gets the volume property.

See setVolume for a full description of volume values.

Returns:

the current volume setting for synthesis

See Also:

setVolume

setInterruptibility

void setInterruptibility(int level)
                         throws IllegalArgumentException

Sets the interruptibility property.

The interruptibility level affects Synthesizer output queue behavior. Synthesizer instances of higher priority interrupt immediately. Synthesizer instances of the same or lower priority wait for the specified interruptibility level to complete. If a queue item is interrupted, then a SPEAKABLE_CANCELLED event is issued.

The possible values are WORD_LEVEL, OBJECT_LEVEL, and QUEUE_LEVEL. With WORD_LEVEL, the current word will complete. With OBJECT_LEVEL, the current queue item will complete. With QUEUE_LEVEL, the entire queue will be spoken.

The default interruptibility level depends on the system implementation. The level set may be less than the level requested depending on the implementation.

The system property values javax.speech.synthesizer.defaultTrustedInterruptibility and javax.speech.synthesizer.defaultUntrustedInterruptibility determine the defaults (normal default is OBJECT_LEVEL).

The system property value javax.speech.synthesizer.maximumUntrustedInterruptibility determines the default maximum interruptibility level for untrusted applications (normal default is QUEUE_LEVEL).

Making a Synthesizer more interruptible (e.g., WORD_LEVEL) may cause it to lose output focus if another Synthesizer instance is waiting to speak. For example, if this Synthesizer instance changes from QUEUE_LEVEL to WORD_LEVEL interruptibility and another Synthesizer instance of equal or higher priority is waiting to speak, then this Synthesizer becomes eligible for interruption at the end of the current word.

Changing the interruptibility may be asynchronous, so any focus change may not occur immediately.

The requested value may be rejected or limited.

Parameters:

level - the interruptibility level for synthesis

Throws:

IllegalArgumentException - if the property value is out of range

See Also:

WORD_LEVEL, OBJECT_LEVEL, QUEUE_LEVEL, getInterruptibility, setPriority, SPEAKABLE_CANCELLED, EngineManager, addEnginePropertyListener

setPitch

void setPitch(int hertz)
              throws IllegalArgumentException

Set the pitch property. This property applies to the baseline pitch. Different Voices have different natural sounding ranges of pitch. Typical male voices are between 80 and 180 Hertz. Pitch for female voices typically vary from 150 to 300 Hertz.

The requested value may be rejected or limited.

Parameters:

hertz - the pitch in Hertz

Throws:

IllegalArgumentException - if the parameter is not a positive integer

See Also:

getPitch, addEnginePropertyListener, Voice

setPitchRange

void setPitchRange(int hertz)
                   throws IllegalArgumentException

Sets the pitchRange property. Set the pitch range for the current synthesis Voice. A narrow pitch range provides monotonous output while a wider range provides a more lively voice. This setting is a hint to the Synthesizer. Synthesizers may choose to ignore unreasonable requests. Some Synthesizers may not support pitch variability.

The pitch range is typically between 20% and 80% of the baseline pitch.

The requested value may be rejected or limited.

Parameters:

hertz - the pitch range in Hertz

Throws:

IllegalArgumentException - if the parameter is a negative integer

See Also:

getPitchRange, addEnginePropertyListener, Voice

setSpeakingRate

void setSpeakingRate(int rate)
                     throws IllegalArgumentException

Sets the speakingRate property. This is the target speaking rate for the Synthesizer. It is either a percentage change relative to the DEFAULT_RATE or one of the rate constants X_SLOW_RATE, SLOW_RATE, MEDIUM_RATE, FAST_RATE, or X_FAST_RATE.

The DEFAULT_RATE speaking rate is the best natural speaking rate for a given Voice (some voices sound better at faster or slower speed than others). The rate parameter supports percentage changes relative to the DEFAULT_RATE. For example, a value of 100 represents 100% or no change and a value of 50 represents 50% or half the DEFAULT_RATE.

The constants X_SLOW_RATE, SLOW_RATE, MEDIUM_RATE, FAST_RATE, X_FAST_RATE allow for relative changes. They represent a sequence of monotonically non-decreasing speaking rates.

The speakingRate property affects the baseline speaking rate used in the speakMarkup method.

Note that the DEFAULT_RATE may vary by dialect and language for a given Voice. A reasonable DEFAULT_RATE for an English Voice may be 200 words per minute.

The requested value may be rejected or limited.

Parameters:

rate - a percentage speaking rate change or constant

Throws:

IllegalArgumentException - if the parameter is not a positive integer or one of the expected constant values

See Also:

DEFAULT_RATE, X_SLOW_RATE, SLOW_RATE, MEDIUM_RATE, FAST_RATE, X_FAST_RATE, getSpeakingRate, addEnginePropertyListener, Voice, speakMarkup

setVoice

void setVoice(Voice voice)
              throws IllegalArgumentException

Sets the voice property. This affects the current Voice of the Synthesizer. The getVoices method returns a list of available Voices for a Synthesizer. Any one of the Voices returned by that method can be passed to this method to set the current speaking Voice.

Alternatively, the voice parameter may be an application-created, partially specified Voice object. If there is no matching Voice, the Voice remains unchanged.

The following example sets a teen-aged, female Voice:

 Voice voice = new Voice(null, null,
                         GENDER_FEMALE, AGE_TEENAGER,
                         VARIANT_DONT_CARE);
 synthesizerProperties.setVoice(voice);
 

The requested value may be rejected or limited.

Parameters:

voice - a Voice to match in the current Synthesizer

Throws:

IllegalArgumentException - if the property value is out of range

See Also:

getVoice, addEnginePropertyListener, getVoices

setVolume

void setVolume(int volume)
               throws IllegalArgumentException

Sets the volume property. The volume is a value between MIN_VOLUME and MAX_VOLUME. A value of MIN_VOLUME indicates silence and MAX_VOLUME indicates maximum available volume.

The default is DEFAULT_VOLUME. Note that SSML prescribes MAX_VOLUME as the default. Applications may wish to begin with MEDIUM_VOLUME instead.

A Synthesizer may change a Voice's style with volume. For example, a quiet volume might produce whispered output and loud volume might produce shouting. Many synthesizers do not make this type of change.

The requested value may be rejected or limited.

Parameters:

volume - value between MAX_VOLUME and MIN_VOLUME

Throws:

IllegalArgumentException - if the property value is out of range

See Also:

getVolume, MIN_VOLUME, MEDIUM_VOLUME, MAX_VOLUME, DEFAULT_VOLUME, addEnginePropertyListener

setPriority

void setPriority(int priority)
                 throws IllegalArgumentException

Sets the priority property.

The priority values range between MIN_PRIORITY and MAX_PRIORITY. The priority used may be lower than the priority requested (rejected or limited). In this case, the return value will differ from the value requested.

Trusted applications may use the full range of priority values. Untrusted applications have a maximum of MAX_UNTRUSTED_PRIORITY, which is less than MAX_PRIORITY.

The default priority values for trusted and untrusted applications are NORM_TRUSTED_PRIORITY and NORM_UNTRUSTED_PRIORITY, respectively.

The priority property should be used with care to avoid starvation of other applications.

Changing the priority may be asynchronous, so any resulting focus change may not occur immediately.

The priority property may determine the order in which Engine instances interact. For example, focus gain and loss may be affected by priority.

Along with Synthesizer output queue interruptibility, the priority determines the order in which queue items are synthesized.

Changing the priority of a Synthesizer instance may cause it to gain or lose focus. For example, if the new priority value for this Synthesizer instance is higher than that of the speaking Synthesizer instance, then that Synthesizer will be interrupted and this one will speak instead. Conversely if the priority of a Synthesizer instance is lowered, another instance may interrupt it.

Specified by:

setPriority in interface EngineProperties

Parameters:

priority - the priority for this Engine

Throws:

IllegalArgumentException - if the property value is out of range

See Also:

getPriority, setInterruptibility, EngineManager, addEnginePropertyListener, EngineProperties.MIN_PRIORITY, EngineProperties.NORM_TRUSTED_PRIORITY, EngineProperties.NORM_UNTRUSTED_PRIORITY, EngineProperties.MAX_UNTRUSTED_PRIORITY, EngineProperties.MAX_PRIORITY