javax.speech.synthesis
Class SpeakableEvent

Object
  SpeechEvent
      SpeakableEvent

public class SpeakableEvent
extends SpeechEvent

Event issued during processing of an item on the Synthesizer output queue.

SpeakableEvents are issued to SpeakableListeners. The speak and speakMarkup methods of a Synthesizer may include a SpeakableListener to monitor progress of the requested item on the Synthesizer output queue. SpeakableListener objects attached to a Synthesizer with the addSpeakableListener method receive every SpeakableEvent for every item on the Synthesizer output queue. SpeakableListeners attached to an individual item on the Synthesizer output queue are notified before SpeakableListeners attached to the Synthesizer.

The source for a SpeakableEvent is the object from the Synthesizer request: a Speakable object, a String, or an AudioSegment.

The normal sequence of events during output of the top item of the Synthesizer output queue is:

• TOP_OF_QUEUE
• SPEAKABLE_STARTED
• Any number of ELEMENT_REACHED, VOICE_CHANGED, PROSODY_UPDATED, MARKER_REACHED, WORD_STARTED, PHONEME_STARTED, or SPEAKABLE_FAILED events
• SPEAKABLE_ENDED

A SPEAKABLE_PAUSED may occur any time after the TOP_OF_QUEUE but before the SPEAKABLE_ENDED event. A SPEAKABLE_PAUSED event can only be followed by a SPEAKABLE_RESUMED or SPEAKABLE_CANCELLED event.

A SPEAKABLE_CANCELLED event can occur at any time before a SPEAKABLE_ENDED event (including before a TOP_OF_QUEUE event). No other events for an item can follow the SPEAKABLE_CANCELLED event since that item is removed from the Synthesizer output queue.

A SPEAKABLE_CANCELLED event can be issued for items that are not at the top of the Synthesizer output queue. The other events are only issued for the top-of-queue item.

See Also:

Speakable, SpeakableListener, Synthesizer, addSpeakableListener, removeSpeakableListener, speak(AudioSegment, SpeakableListener), speak(Speakable, SpeakableListener), speak(String, SpeakableListener), speakMarkup(String, SpeakableListener)

Field Summary

static int	DEFAULT_MASK The default mask for events in this class.
static int	ELEMENT_CLOSE Type of ELEMENT_REACHED event.
static int	ELEMENT_OPEN Type of ELEMENT_REACHED event.
static int	ELEMENT_REACHED Event issued when audio output for an element of markup text begins or ends.
static int	MARKER_REACHED Event issued when audio output reaches a marker contained in markup text.
static int	PHONEME_STARTED Event issued when audio output starts for a phoneme from an item on the Synthesizer output queue.
static int	PROSODY_CONTOUR Type of PROSODY_UPDATED event issued when a prosody value for contour changes.
static int	PROSODY_PITCH Type of PROSODY_UPDATED event issued when a prosody value for pitch changes.
static int	PROSODY_PITCH_RANGE Type of PROSODY_UPDATED event issued when a prosody value for pitch range changes.
static int	PROSODY_RATE Type of PROSODY_UPDATED event issued when a prosody value for rate changes.
static int	PROSODY_UPDATED Event issued when a prosody value changes due to markup text.
static int	PROSODY_VOLUME Type of PROSODY_UPDATED event issued when a prosody value for volume changes.
static int	SPEAKABLE_CANCELLED Event issued when an item on the Synthesizer output queue is cancelled and removed from the queue.
static int	SPEAKABLE_ENDED Event issued with the completion of audio output of an object on the Synthesizer output queue as the object is removed from the queue.
static int	SPEAKABLE_FAILED Event issued when an error occurs during processing of an item on the Synthesizer output queue.
static int	SPEAKABLE_FAILURE_RECOVERABLE Type of SPEAKABLE_FAILED event issued for recoverable errors.
static int	SPEAKABLE_FAILURE_UNRECOVERABLE Type of SPEAKABLE_FAILED event issued for unrecoverable errors.
static int	SPEAKABLE_PAUSED Event issued when audio output of the top item of the Synthesizer output queue is PAUSED.
static int	SPEAKABLE_RESUMED Event issued when audio output of the top item of the Synthesizer output queue is RESUMED after being PAUSED.
static int	SPEAKABLE_STARTED Event issued at the start of audio output of an item on the Synthesizer output queue.
static int	TOP_OF_QUEUE Event issued when an item on the Synthesizer output queue reaches the top of the queue.
static int	UNKNOWN_AUDIO_POSITION Value returned when the getAudioPosition method is not supported.
static int	UNKNOWN_INDEX Value returned when a method that returns an index is not supported.
static int	UNKNOWN_TYPE Value returned when a method that returns a type is not supported.
static int	UNKNOWN_VALUE Value returned when a method that returns a value is not supported.
static int	VOICE_CHANGED Event issued when audio output begins for a Voice change specified in markup text.
static int	WORD_STARTED Event issued when audio output starts for a word from an item on the Synthesizer output queue.

Fields inherited from class SpeechEvent

DISABLE_ALL, ENABLE_ALL

Constructor Summary

SpeakableEvent(Object source, int id, int requestId)
Constructs a SpeakableEvent denoting a status change.

SpeakableEvent(Object source, int id, int requestId, int type, SpeakableException speakableException)
Constructs a SPEAKABLE_FAILED SpeakableEvent.

SpeakableEvent(Object source, int id, int requestId, String textInfo, int audioPosition)
Constructs a MARKER_REACHED SpeakableEvent.

SpeakableEvent(Object source, int id, int requestId, String textInfo, int textBegin, int textEnd)
Constructs a WORD_STARTED SpeakableEvent.

SpeakableEvent(Object source, int id, int requestId, String textInfo, int type, int requested, int realized)
Constructs a PROSODY_UPDATED SpeakableEvent.

SpeakableEvent(Object source, int id, int requestId, String textInfo, int type, String[] attributes)
Constructs an ELEMENT_REACHED SpeakableEvent.

SpeakableEvent(Object source, int id, int requestId, String textInfo, PhoneInfo[] phones, int index)
Constructs a PHONEME_STARTED SpeakableEvent.

SpeakableEvent(Object source, int id, int requestId, String textInfo, Voice oldVoice, Voice newVoice)
Constructs a VOICE_CHANGED SpeakableEvent.

Method Summary

String[]	getAttributes() Gets any attributes associated with an ELEMENT_REACHED event.
int	getAudioPosition() Gets the position in milliseconds where a MARKER_REACHED event occurs in the rendered output stream.
int	getIndex() Gets the index of the phone associated with a PHONEME_STARTED event.
Voice	getNewVoice() Gets the new Voice associated with a VOICE_CHANGED event.
Voice	getOldVoice() Gets the old Voice associated with a VOICE_CHANGED event.
PhoneInfo[]	getPhones() Returns an array of phone information associated with a PHONEME_STARTED event.
int	getRealizedValue() Gets the prosody value realized by markup text with a PROSODY_UPDATED event.
int	getRequestedValue() Gets the prosody value requested by markup text with a PROSODY_UPDATED event.
int	getRequestId() Gets the request identifier associated with this SpeakableEvent.
SpeakableException	getSpeakableException() Gets the SpeakableException associated with a SPEAKABLE_FAILED event.
int	getTextBegin() Gets the index of the first character of the word in the synthesis markup text for a WORD_STARTED event.
int	getTextEnd() Gets the index of the last character of the word in the synthesis markup text for a WORD_STARTED event.
String	getTextInfo() Gets text information associated with this SpeakableEvent.
int	getType() Gets the type of this SpeakableEvent event.
String	paramString() Returns a parameter String that contains the event identifier in text form.
String	toString() Returns a printable String.

Methods inherited from class SpeechEvent

getId, getSource

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

TOP_OF_QUEUE

public static final int TOP_OF_QUEUE

Event issued when an item on the Synthesizer output queue reaches the top of the queue. If the Synthesizer is not PAUSED, the TOP_OF_QUEUE event will be followed immediately by the SPEAKABLE_STARTED event. If the Synthesizer is PAUSED, the SPEAKABLE_STARTED event will be delayed until the Synthesizer is RESUMED.

A QUEUE_UPDATED is also issued when the Synthesizer output queue changes (e.g. a new item at the top of the queue). The SpeakableEvent is issued prior to the SynthesizerEvent.

This event is not enabled by default. It may be enabled with setSpeakableMask.

See Also:

SPEAKABLE_STARTED, SynthesizerEvent.QUEUE_UPDATED, Engine.PAUSED, Engine.RESUMED, SpeakableEvent(Object, int, int), DEFAULT_MASK, setSpeakableMask, Constant Field Values

SPEAKABLE_STARTED

public static final int SPEAKABLE_STARTED

Event issued at the start of audio output of an item on the Synthesizer output queue. This event immediately follows the TOP_OF_QUEUE unless the Synthesizer is PAUSED when the item is promoted to the top of the queue.

See Also:

TOP_OF_QUEUE, Engine.PAUSED, SpeakableEvent(Object, int, int), DEFAULT_MASK, Constant Field Values

SPEAKABLE_ENDED

public static final int SPEAKABLE_ENDED

Event issued with the completion of audio output of an object on the Synthesizer output queue as the object is removed from the queue.

A QUEUE_UPDATED or QUEUE_EMPTIED event is also issued when the Synthesizer output queue changes because the output of the top item of the queue is completed. The SpeakableEvent is issued prior to the SynthesizerEvent.

See Also:

SynthesizerEvent.QUEUE_UPDATED, SynthesizerEvent.QUEUE_EMPTIED, SpeakableEvent(Object, int, int), DEFAULT_MASK, Constant Field Values

SPEAKABLE_PAUSED

public static final int SPEAKABLE_PAUSED

Event issued when audio output of the top item of the Synthesizer output queue is PAUSED.

The SPEAKABLE_PAUSED event is issued prior to the ENGINE_PAUSED event that is issued to the SynthesizerListener.

See Also:

SynthesizerListener, Engine.PAUSED, EngineEvent.ENGINE_PAUSED, SpeakableEvent(Object, int, int), DEFAULT_MASK, Constant Field Values

SPEAKABLE_RESUMED

public static final int SPEAKABLE_RESUMED

Event issued when audio output of the top item of the Synthesizer output queue is RESUMED after being PAUSED.

The SPEAKABLE_RESUMED event is issued prior to the ENGINE_RESUMED event that is issued to the SynthesizerListener.

See Also:

SynthesizerListener, Engine.RESUMED, Engine.PAUSED, EngineEvent.ENGINE_RESUMED, SpeakableEvent(Object, int, int), DEFAULT_MASK, Constant Field Values

SPEAKABLE_CANCELLED

public static final int SPEAKABLE_CANCELLED

Event issued when an item on the Synthesizer output queue is cancelled and removed from the queue. A Synthesizer output queue item may be cancelled at any time following a call to speak or speakMarkup. An item can be cancelled even if it is not at the top of the queue (other SpeakableEvents are issued only to the top-of-queue item). Once cancelled, the SpeakableListener for the cancelled item receives no further SpeakableEvents for that item.

This event may be caused by one of the cancel methods of Synthesizer. It may also be caused by focus changes due to Synthesizer priority or interruptibility.

The SPEAKABLE_CANCELLED event is issued prior to the QUEUE_UPDATED or QUEUE_EMPTIED SynthesizerEvents.

See Also:

SpeakableListener, cancel, speak, speakMarkup, setPriority, setInterruptibility, SynthesizerEvent.QUEUE_UPDATED, SynthesizerEvent.QUEUE_EMPTIED, SpeakableEvent(Object, int, int), DEFAULT_MASK, Constant Field Values

WORD_STARTED

public static final int WORD_STARTED

Event issued when audio output starts for a word from an item on the Synthesizer output queue.

The following methods provide additional information:

• getTextInfo the next word to be spoken
• getTextBegin character index of the word start within the speakable text
• getTextEnd character index of the word end within the speakable text

The text of the next word to be spoken may differ from the text defined by getTextBegin and getTextEnd in the original speakable text being spoken.

In speak("$101"), for example, the first WORD_STARTED event getTextInfo might return "one" (for "one hundred one dollars") and getTextBegin and getTextEnd might return 0 and 4, respectively, to define the segment of the speakable text ("$101"). The three subsequent WORD_STARTED events for "hundred", "one" and "dollars" would also return the same start and end indices. Note that the words spoken may vary by Synthesizer (e.g., "one hundred and one dollars").

This event is not enabled by default. It may be enabled with setSpeakableMask.

See Also:

getTextInfo, getTextBegin, getTextEnd, SpeakableEvent(Object, int, int, String, int, int), DEFAULT_MASK, setSpeakableMask, Constant Field Values

PHONEME_STARTED

public static final int PHONEME_STARTED

Event issued when audio output starts for a phoneme from an item on the Synthesizer output queue.

The following methods provide additional information:

• getTextInfo returns the text of the word being spoken
• getPhones returns an array of phones corresponding to the current text
• getIndex returns the index of the next phone within the phone array

Durations may have a value of UNKNOWN_DURATION if not supported. When supported, the timing supplied by the durations may not be exact.

PHONEME_STARTED events follow the associated WORD_STARTED event.

This event may not be delivered by all Synthesizers.

This event is not enabled by default. It may be enabled with setSpeakableMask.

See Also:

getTextInfo, getPhones, getIndex, UNKNOWN_DURATION, WORD_STARTED, SpeakableEvent(Object, int, int, String, PhoneInfo[], int), DEFAULT_MASK, setSpeakableMask, Constant Field Values

MARKER_REACHED

public static final int MARKER_REACHED

Event issued when audio output reaches a marker contained in markup text. This event is issued when a requested change results in an actual change.

The following methods provide additional information:

• getTextInfo returns the value of the name attribute in the mark element.
• getAudioPosition() returns the position of the mark in the output stream.

The following example shows how to include the mark element in markup text:

 <speak xml:lang='en-US' version='1.0'>
   Go from <mark name='HERE'/> here, to <mark name='THERE'/> there!
 </speak>
 

For this example, a MARKER_REACHED SpeakableEvent with the marker value "HERE" will be sent to attached SpeakableListeners as the word "here" is about to be played on the output device and similarly for the marker value "THERE" as "there" is about to be played.

See Also:

getTextInfo, getAudioPosition, SpeakableListener, SpeakableEvent(Object, int, int, String, int), DEFAULT_MASK, Constant Field Values

VOICE_CHANGED

public static final int VOICE_CHANGED

Event issued when audio output begins for a Voice change specified in markup text.

The following methods provide additional information:

• getTextInfo returns the element name that caused the Voice change
• getOldVoice returns the Voice before the change
• getNewVoice returns the Voice after the change

See Also:

getTextInfo(), getOldVoice(), getNewVoice(), SpeakableEvent(Object, int, int, String, Voice, Voice), DEFAULT_MASK, Constant Field Values

SPEAKABLE_FAILED

public static final int SPEAKABLE_FAILED

Event issued when an error occurs during processing of an item on the Synthesizer output queue.

The following methods provide additional information:

• getType returns the type of error:

  SPEAKABLE_FAILURE_RECOVERABLE, SPEAKABLE_FAILURE_UNRECOVERABLE,

• getSpeakableException returns more detail about the error

If for some reason the Synthesizer cannot continue due to a serious internal error that prevents normal behavior, an ENGINE_ERROR event is issued.

See Also:

getType, getSpeakableException, SpeakableEvent(Object,int,int,int,SpeakableException), DEFAULT_MASK, EngineEvent.ENGINE_ERROR, Constant Field Values

PROSODY_UPDATED

public static final int PROSODY_UPDATED

Event issued when a prosody value changes due to markup text. This event is issued when a requested change results in an actual change.

The following methods provide additional information:

• getTextInfo returns the element name that caused the change
• getType returns the type of prosody change requested:

  PROSODY_RATE - percentage multiplier of the default rate (e.g., 50 represents the multiplier 0.5 and 150 represents the multiplier 1.5)

  PROSODY_PITCH - measured in Hertz

  PROSODY_VOLUME - integer values between MIN_VOLUME and MAX_VOLUME

  PROSODY_PITCH_RANGE - measured in Hertz

  PROSODY_CONTOUR - individual contour values measured in Hertz

• getRequestedValue returns the prosody value requested by the markup
• getRealizedValue returns the realized prosody value for the request

This event is not enabled by default. It may be enabled with setSpeakableMask.

See Also:

getTextInfo, getType, getRequestedValue, getRealizedValue, SpeakableEvent(Object, int, int, String, int, int, int), SynthesizerProperties.MIN_VOLUME, SynthesizerProperties.MAX_VOLUME, DEFAULT_MASK, setSpeakableMask, Constant Field Values

ELEMENT_REACHED

public static final int ELEMENT_REACHED

Event issued when audio output for an element of markup text begins or ends.

The following methods provide additional information:

• getTextInfo returns the element name
• getType returns the type of element reached:

  ELEMENT_OPEN or ELEMENT_CLOSE

• getAttributes returns an array of any attribute/value pairs for this element

For example, if the markup element text is

 <prosody rate='-10%' volume='loud'>really</prosody>
 

then for the type ELEMENT_OPEN, getTextInfo and getAttributes will return values corresponding to

 String text = "prosody";
 String[] attributes = {"rate='-10%'", "volume='loud'"};
 

Because different synthesizers will render markup text differently, this event helps an application align SpeakableEvents with the corresponding markup text.

This event can also be used to align other multimedia queues (e.g., font and color changes) with the rendered audio.

This event is not enabled by default. It may be enabled with setSpeakableMask.

See Also:

getTextInfo, getType, getAttributes, SpeakableEvent(Object, int, int, String, int, String[]), DEFAULT_MASK, setSpeakableMask, Constant Field Values

ELEMENT_OPEN

public static final int ELEMENT_OPEN

Type of ELEMENT_REACHED event. The output for the element is beginning.

See Also:

ELEMENT_REACHED, Constant Field Values

ELEMENT_CLOSE

public static final int ELEMENT_CLOSE

Type of ELEMENT_REACHED event. The output for the element has completed.

See Also:

ELEMENT_REACHED, Constant Field Values

SPEAKABLE_FAILURE_RECOVERABLE

public static final int SPEAKABLE_FAILURE_RECOVERABLE

Type of SPEAKABLE_FAILED event issued for recoverable errors. In this case, the Synthesizer believes that it can render the requested item.

For example, a Synthesizer may choose not to report unsupported characters for a language. In this case, it can map the characters to expected ones and continue.

getSpeakableException may provide more detailed information.

See Also:

SPEAKABLE_FAILED, getSpeakableException, Constant Field Values

SPEAKABLE_FAILURE_UNRECOVERABLE

public static final int SPEAKABLE_FAILURE_UNRECOVERABLE

Type of SPEAKABLE_FAILED event issued for unrecoverable errors. In this case, the Synthesizer can NOT render the requested item. The Synthesizer will behave as if cancel had been invoked and processing will continue with the next item. This results in a SPEAKABLE_CANCELLED event.

Note that markup that is not well formed results in this error. This ensures consistent rendering across platforms.

A Synthesizer that encounters a token that it cannot support generates this error type.

getSpeakableException may provide more detailed information.

See Also:

SPEAKABLE_FAILED, SPEAKABLE_CANCELLED, cancel, getSpeakableException, cancel, Constant Field Values

PROSODY_RATE

public static final int PROSODY_RATE

Type of PROSODY_UPDATED event issued when a prosody value for rate changes.

See Also:

PROSODY_UPDATED, Constant Field Values

PROSODY_PITCH

public static final int PROSODY_PITCH

Type of PROSODY_UPDATED event issued when a prosody value for pitch changes. This applies to baseline pitch changes.

See Also:

PROSODY_UPDATED, Constant Field Values

PROSODY_VOLUME

public static final int PROSODY_VOLUME

Type of PROSODY_UPDATED event issued when a prosody value for volume changes.

See Also:

PROSODY_UPDATED, Constant Field Values

PROSODY_PITCH_RANGE

public static final int PROSODY_PITCH_RANGE

Type of PROSODY_UPDATED event issued when a prosody value for pitch range changes.

See Also:

PROSODY_UPDATED, Constant Field Values

PROSODY_CONTOUR

public static final int PROSODY_CONTOUR

Type of PROSODY_UPDATED event issued when a prosody value for contour changes.

One event of this type is issued for each requested contour change in the set of targets. The requested and realized pitch values are reported. The time positions are not reported.

The events of this type are reported in relative order, but may occur at times other than the requested time positions.

See Also:

PROSODY_UPDATED, Constant Field Values

DEFAULT_MASK

public static final int DEFAULT_MASK

The default mask for events in this class.

The mask is set with setSpeakableMask. The following events are delivered by default: MARKER_REACHED, SPEAKABLE_FAILED, SPEAKABLE_CANCELLED, SPEAKABLE_STARTED, SPEAKABLE_ENDED, SPEAKABLE_PAUSED, SPEAKABLE_RESUMED, and VOICE_CHANGED.

Other events may be enabled with setSpeakableMask if desired.

See Also:

MARKER_REACHED, SPEAKABLE_FAILED, SPEAKABLE_CANCELLED, SPEAKABLE_STARTED, SPEAKABLE_ENDED, SPEAKABLE_PAUSED, SPEAKABLE_RESUMED, VOICE_CHANGED, ELEMENT_REACHED, PROSODY_UPDATED, WORD_STARTED, PHONEME_STARTED, TOP_OF_QUEUE, setSpeakableMask, Constant Field Values

UNKNOWN_AUDIO_POSITION

public static final int UNKNOWN_AUDIO_POSITION

Value returned when the getAudioPosition method is not supported.

See Also:

getAudioPosition, Constant Field Values

UNKNOWN_INDEX

public static final int UNKNOWN_INDEX

Value returned when a method that returns an index is not supported.

See Also:

getIndex, getTextBegin, getTextEnd, Constant Field Values

UNKNOWN_TYPE

public static final int UNKNOWN_TYPE

Value returned when a method that returns a type is not supported.

See Also:

getType, Constant Field Values

UNKNOWN_VALUE

public static final int UNKNOWN_VALUE

Value returned when a method that returns a value is not supported.

See Also:

getRequestedValue, getRealizedValue, Constant Field Values

Constructor Detail

SpeakableEvent

public SpeakableEvent(Object source,
                      int id,
                      int requestId)
               throws IllegalArgumentException

Constructs a SpeakableEvent denoting a status change.

This constructor applies to the TOP_OF_QUEUE, SPEAKABLE_STARTED, SPEAKABLE_ENDED, SPEAKABLE_PAUSED, SPEAKABLE_RESUMED, and SPEAKABLE_CANCELLED event identifiers.

Parameters:

source - the object added to the Synthesizer output queue

id - the event identifier

requestId - a valid Synthesizer request identifier

Throws:

IllegalArgumentException - if called with an inappropriate event identifier

See Also:

TOP_OF_QUEUE, SPEAKABLE_STARTED, SPEAKABLE_ENDED, SPEAKABLE_PAUSED, SPEAKABLE_RESUMED, SPEAKABLE_CANCELLED, getSource, getId, getRequestId

SpeakableEvent

public SpeakableEvent(Object source,
                      int id,
                      int requestId,
                      String textInfo,
                      int type,
                      String[] attributes)
               throws IllegalArgumentException

Constructs an ELEMENT_REACHED SpeakableEvent. The documentation for ELEMENT_REACHED includes a list of valid types.

Parameters:

source - the object from which the markup text was obtained

id - the event identifier

requestId - a valid Synthesizer request identifier

textInfo - a non-null element name

type - the type of element reached

attributes - a non-null array of any attribute/value pairs for this element

Throws:

IllegalArgumentException - if called with an inappropriate event identifier or an invalid parameter value

See Also:

ELEMENT_REACHED, getSource, getId, getRequestId, getTextInfo, getType, getAttributes

SpeakableEvent

public SpeakableEvent(Object source,
                      int id,
                      int requestId,
                      String textInfo,
                      int audioPosition)
               throws IllegalArgumentException

Constructs a MARKER_REACHED SpeakableEvent.

Parameters:

source - the object from which the markup text was obtained

id - the event identifier

requestId - a valid Synthesizer request identifier

textInfo - non-null value of the name attribute for the mark element

audioPosition - a valid position in milliseconds where this mark occurs in the rendered output stream

Throws:

IllegalArgumentException - if called with an inappropriate event identifier or an invalid parameter value

See Also:

MARKER_REACHED, getSource, getId, getRequestId, getTextInfo, getAudioPosition

SpeakableEvent

public SpeakableEvent(Object source,
                      int id,
                      int requestId,
                      String textInfo,
                      int type,
                      int requested,
                      int realized)
               throws IllegalArgumentException

Constructs a PROSODY_UPDATED SpeakableEvent. This can be used to track markup-related prosody value changes.

Changes can occur both when entering and leaving a markup element. If needed, use the ELEMENT_CLOSE and ELEMENT_OPEN types of the ELEMENT_REACHED event to distinguish these conditions.

The documentation for PROSODY_UPDATED includes a list of valid types.

Parameters:

source - the object from which the markup text was obtained

id - the event identifier

requestId - a valid Synthesizer request identifier

textInfo - non-null element name that caused this event

type - the type of prosody change requested

requested - the prosody value requested by the markup

realized - the realized prosody value for the request

Throws:

IllegalArgumentException - if called with an inappropriate event identifier or an invalid parameter value

See Also:

PROSODY_UPDATED, getSource, getId, getRequestId, getTextInfo, getType, getRequestedValue, getRealizedValue, ELEMENT_REACHED, ELEMENT_OPEN, ELEMENT_CLOSE

SpeakableEvent

public SpeakableEvent(Object source,
                      int id,
                      int requestId,
                      String textInfo,
                      int textBegin,
                      int textEnd)
               throws IllegalArgumentException

Constructs a WORD_STARTED SpeakableEvent. The parameter textEnd must be greater than textBegin.

Parameters:

source - the object from which the speakable text was obtained

id - the event identifier

requestId - a valid Synthesizer request identifier

textInfo - non-null next word to be spoken

textBegin - non-negative character index of the word start within the speakable text

textEnd - non-negative character index of the word end within the speakable text

Throws:

IllegalArgumentException - if called with an inappropriate event identifier or an invalid parameter value

See Also:

WORD_STARTED, getSource, getId, getRequestId, getTextInfo, getTextBegin, getTextEnd

SpeakableEvent

public SpeakableEvent(Object source,
                      int id,
                      int requestId,
                      String textInfo,
                      PhoneInfo[] phones,
                      int index)
               throws IllegalArgumentException

Constructs a PHONEME_STARTED SpeakableEvent.

Information associated with the phonemes can help animate corresponding speaking images.

Parameters:

source - the object from which the speakable text was obtained

id - the event identifier

requestId - a valid Synthesizer request identifier

textInfo - non-null text of the word being spoken

phones - a non-empty array of phones corresponding to the current text

index - valid index of the next phone within the phone array

Throws:

IllegalArgumentException - if called with an inappropriate event identifier or an invalid parameter value

See Also:

PHONEME_STARTED, getSource, getId, getRequestId, getTextInfo, getPhones, getIndex

SpeakableEvent

public SpeakableEvent(Object source,
                      int id,
                      int requestId,
                      String textInfo,
                      Voice oldVoice,
                      Voice newVoice)
               throws IllegalArgumentException

Constructs a VOICE_CHANGED SpeakableEvent. This can be used to track markup-related Voice changes.

Changes can occur both when entering and leaving a markup element. If needed, use the ELEMENT_CLOSE and ELEMENT_OPEN types of the ELEMENT_REACHED event to distinguish these conditions.

Parameters:

source - the object from which the markup text was obtained

id - the event identifier

requestId - a valid Synthesizer request identifier

textInfo - non-null element name that caused this event

oldVoice - non-null Voice before the change

newVoice - non-null Voice after the change

Throws:

IllegalArgumentException - if called with an inappropriate event identifier or an invalid parameter value

See Also:

VOICE_CHANGED, getSource, getId, getRequestId, getTextInfo, getOldVoice, getNewVoice, Voice, ELEMENT_REACHED, ELEMENT_OPEN, ELEMENT_CLOSE

SpeakableEvent

public SpeakableEvent(Object source,
                      int id,
                      int requestId,
                      int type,
                      SpeakableException speakableException)
               throws IllegalArgumentException

Constructs a SPEAKABLE_FAILED SpeakableEvent.

The documentation for SPEAKABLE_FAILED includes a list of valid types.

Parameters:

source - the object added to the Synthesizer output queue

id - the event identifier

requestId - a valid Synthesizer request identifier

type - the markup failure

speakableException - a non-null SpeakableException describing the failure

Throws:

IllegalArgumentException - if called with an inappropriate event identifier or an invalid parameter value

See Also:

SPEAKABLE_FAILED, getSource, getId, getRequestId, getTextInfo, getType, getSpeakableException

Method Detail

getType

public int getType()

Gets the type of this SpeakableEvent event. The ELEMENT_REACHED, SPEAKABLE_FAILED, and PROSODY_UPDATED events include a type. See each of these events for details.

For all other events, this method returns UNKNOWN_TYPE.

Returns:

the type of the SpeakableEvent

See Also:

ELEMENT_REACHED, SPEAKABLE_FAILED, PROSODY_UPDATED, UNKNOWN_TYPE

getAttributes

public String[] getAttributes()

Gets any attributes associated with an ELEMENT_REACHED event. If the element contains no attributes, a zero-length array is returned.

The documentation for ELEMENT_REACHED provides an example.

For all other events, a zero-length array is returned.

Returns:

an array of attribute/value pairs

See Also:

ELEMENT_REACHED

getIndex

public int getIndex()

Gets the index of the phone associated with a PHONEME_STARTED event. The getPhones method returns the array of phones corresponding to the text.

This method returns UNKNOWN_INDEX for all other events.

Returns:

the index of the current phone within the phoneme context

See Also:

PHONEME_STARTED, getPhones, UNKNOWN_INDEX

getPhones

public PhoneInfo[] getPhones()

Returns an array of phone information associated with a PHONEME_STARTED event. The array represents a set of phones corresponding to the text. Each PhoneInfo instance includes the base phoneme along with anticipated duration.

If the event contains no phone information, a zero-length array is returned.

Returns:

set of phones corresponding to the current text

See Also:

getIndex, PHONEME_STARTED

getTextInfo

public String getTextInfo()

Gets text information associated with this SpeakableEvent. This method applies to the ELEMENT_REACHED, MARKER_REACHED, PHONEME_STARTED, PROSODY_UPDATED, VOICE_CHANGED, and WORD_STARTED event identifiers. The documentation for each event contains more detail about the text returned in each case.

For all other events, this method returns null.

Returns:

the text associated with this event

See Also:

ELEMENT_REACHED, MARKER_REACHED, PHONEME_STARTED, PROSODY_UPDATED, VOICE_CHANGED, WORD_STARTED

getRequestId

public int getRequestId()

Gets the request identifier associated with this SpeakableEvent.

Each SpeakableEvent is the result of a speak or speakMarkup request. These requests return a unique request identifier that is associated with any corresponding SpeakableEvent.

Returns:

the request identifier associated with this event

See Also:

Synthesizer.speak(AudioSegment, SpeakableListener), Synthesizer.speak(Speakable, SpeakableListener), Synthesizer.speak(String, SpeakableListener), Synthesizer.speakMarkup(String, SpeakableListener)

getSpeakableException

public SpeakableException getSpeakableException()

Gets the SpeakableException associated with a SPEAKABLE_FAILED event. The SpeakableException documentation contains more detail about the types of problems possible.

For all other events, this method returns null.

Returns:

the SpeakableException associated with this event

See Also:

SPEAKABLE_FAILED

getNewVoice

public Voice getNewVoice()

Gets the new Voice associated with a VOICE_CHANGED event.

For all other events, this method returns null.

Returns:

the voice after a VOICE_CHANGED event

See Also:

VOICE_CHANGED

getOldVoice

public Voice getOldVoice()

Gets the old Voice associated with a VOICE_CHANGED event.

For all other events, this method returns null.

Returns:

the voice before a VOICE_CHANGED event

See Also:

VOICE_CHANGED

getAudioPosition

public int getAudioPosition()

Gets the position in milliseconds where a MARKER_REACHED event occurs in the rendered output stream.

This value is relative to the beginning of the output stream and is not related to CPU time. If this mark occurs at sample n in a stream with a sample_rate measured in samples per second, then

 position = (n / sample_rate) * 1000
 

Valid values are 0 and above. If the value is not known or does not apply to an event identifier, a value of UNKNOWN_AUDIO_POSITION is returned.

Returns:

the position in milliseconds where this mark occurs in the rendered output stream

See Also:

MARKER_REACHED, UNKNOWN_AUDIO_POSITION

getRequestedValue

public int getRequestedValue()

Gets the prosody value requested by markup text with a PROSODY_UPDATED event.

The return value depends on the type of the PROSODY_UPDATED event.

This method returns UNKNOWN_VALUE for all other events.

Returns:

the requested prosody value

See Also:

PROSODY_UPDATED, UNKNOWN_VALUE, getRealizedValue

getRealizedValue

public int getRealizedValue()

Gets the prosody value realized by markup text with a PROSODY_UPDATED event.

The return value depends on the type of the PROSODY_UPDATED event.

This method returns UNKNOWN_VALUE for all other events.

Returns:

the realized prosody value

See Also:

PROSODY_UPDATED, UNKNOWN_VALUE, getRequestedValue

getTextEnd

public int getTextEnd()

Gets the index of the last character of the word in the synthesis markup text for a WORD_STARTED event.

For all other events, this method returns UNKNOWN_INDEX.

Returns:

index of the last character of the word in the synthesis markup text

See Also:

WORD_STARTED, getTextBegin, UNKNOWN_INDEX

getTextBegin

public int getTextBegin()

Gets the index of the first character of the word in the synthesis markup text for a WORD_STARTED event.

For all other events, this method returns UNKNOWN_INDEX.

Returns:

index of the first character of the word in the synthesis markup text

See Also:

WORD_STARTED, getTextEnd, UNKNOWN_INDEX

paramString

public String paramString()

Returns a parameter String that contains the event identifier in text form.

The method toString may provide more detail. This method is useful for event-logging and for debugging.

Specified by:

paramString in class SpeechEvent

Returns:

a String that contains the event identifier in text form.

See Also:

toString

toString

public String toString()

Returns a printable String. Useful for event-logging and debugging.

The method paramString also provides printable information.

Specified by:

toString in class SpeechEvent

Returns:

A printable string.

See Also:

paramString