com.sun.speech.freetts
Class Voice

java.lang.Object
  com.sun.speech.freetts.Voice

All Implemented Interfaces:

Dumpable, UtteranceProcessor

Direct Known Subclasses:

CMUVoice

public abstract class Voice

extends java.lang.Object

implements UtteranceProcessor, Dumpable

Performs text-to-speech using a series of UtteranceProcessors. It is the main conduit to the FreeTTS speech synthesizer. It can perform TTS on ASCII text, a JSML document, an InputStream, or a FreeTTSSpeakable, by invoking the method speak.

Before a Voice can perform TTS, it must have a Lexicon, from which it gets the vocabulary, and an AudioPlayer, to which it sends the synthesized output.

Example (using the CMUDiphoneVoice, CMULexicon and JavaClipAudioPlayer):

 Voice voice = new CMUDiphoneVoice();

 // sets the Lexicon
 voice.setLexicon(new CMULexicon());

 // sets the AudioPlayer
 voice.setAudioPlayer(new JavaClipAudioPlayer());

 // loads the Voice
 voice.allocate();

 // start talking
 voice.speak("I can talk forever without getting tired!");
 

A user can override the AudioPlayer to use by defining the "com.sun.speech.freetts.voice.defaultAudioPlayer" system property. The value of this property must be the name of a class that implements the AudioPlayer interface, and which also has a no-arg constructor.

See Also:

VoiceManager, VoiceDirectory

Field Summary

static java.lang.String	DATABASE_NAME Constant that describes the name of the unit database used by this voice.
static java.lang.String	DEFAULT_AUDIO_PLAYER Feature name for the default AudioPlayer class to use.
static java.lang.String	DEFAULT_AUDIO_PLAYER_DEFAULT The default class to use for the DEFAULT_AUDIO_PLAYER.
static java.lang.String	FEATURE_JOIN_TYPE Feature name for the join type string.
static java.lang.String	FEATURE_SILENCE Feature name for the silence phone string.
static java.lang.String	PROP_PREFIX Prefix for System property names.

Constructor Summary

Voice()
Creates a new Voice.

Voice(java.lang.String name, Gender gender, Age age, java.lang.String description, java.util.Locale locale, java.lang.String domain, java.lang.String organization)
Creates a new Voice like above, except that it also stores the properties of the voice.

Method Summary

void	addFeatureProcessor(java.lang.String name, FeatureProcessor fp) Adds a language/voice specific Feature Processor to the set of FeatureProcessors supported by this voice.
void	allocate() Allocate this Voice.
static OutputQueue	createOutputThread() Creates an output thread that will asynchronously output utterances that are generated by this voice (and other voices).
void	deallocate() Shuts down the voice processing.
void	dump(java.io.PrintWriter output, int pad, java.lang.String title) Dumps the voice in textual form.
void	dumpProcessors(java.io.PrintWriter output, int pad, java.lang.String title) Dumps the voice processors.
void	endBatch() Ends a batch of utterances.
void	error(java.lang.String message) Sends the given error message to stderr and also throws an error exception.
Age	getAge() Get the age of this voice.
protected abstract UtteranceProcessor	getAudioOutput() Returns the AudioOutput processor to be used by this voice.
AudioPlayer	getAudioPlayer() Gets the audio player associated with this voice.
AudioPlayer	getDefaultAudioPlayer() Gets the default audio player for this voice.
java.lang.String	getDescription() Get the description of this voice.
java.lang.String	getDomain() Get the domain of this voice.
float	getDurationStretch() Gets the duration Stretch
FeatureProcessor	getFeatureProcessor(java.lang.String name) Returns a language/voice specific Feature Processor.
FeatureSet	getFeatures() Returns the feature set associated with this voice.
Gender	getGender() Get the gender of this voice.
Lexicon	getLexicon() Gets the lexicon for this voice.
java.util.Locale	getLocale() Get the locale of this voice.
java.lang.String	getName() Get the name of this voice.
java.lang.String	getOrganization() Gets the organization which created this voice.
OutputQueue	getOutputQueue() Returns the output queue associated with this voice.
java.lang.String	getPhoneFeature(java.lang.String phone, java.lang.String featureName) Given a phoneme and a feature name, returns the feature.
float	getPitch() Retreives the baseline pitch.
float	getPitchRange() Gets the pitch range.
float	getPitchShift() Gets the pitch shift.
float	getRate() Gets the rate of speech.
protected java.net.URL	getResource(java.lang.String resource) Get a resource for this voice.
java.lang.String	getRunTitle() Gets the title for this run.
java.lang.String	getStyle() Gets the voice style.
abstract Tokenizer	getTokenizer() Returns the tokenizer associated with this voice.
java.util.List	getUtteranceProcessors() Return the list of UtteranceProcessor instances.
float	getVolume() Gets the volume.
java.lang.String	getWaveDumpFile() Gets the dumpfile for this voice.
boolean	isDetailedMetrics() Gets the state of the detailedMetrics mode.
boolean	isDumpRelations() Gets the state of the dumpRelations mode.
boolean	isDumpUtterance() Gets the state of the dumpUtterance mode.
boolean	isLoaded() Returns true if this voice is loaded.
boolean	isMetrics() Gets the state of the metrics mode.
boolean	isVerbose() Gets the state of the verbose mode.
void	load() Deprecated. As of FreeTTS 1.2, replaced by allocate().
protected abstract void	loader() Loads voice specific data.
void	log(java.lang.String message) Prints the given message to System.out if "verbose" operation is enabled.
protected java.lang.StringBuffer	processNode(org.w3c.dom.Node n, java.lang.StringBuffer buf) Adds text for just this node and returns any text that might be needed to undo the effects of this node after it is processed.
void	processUtterance(Utterance u) Processes the given Utterance by passing it to each UtteranceProcessor managed by this Voice.
protected void	setAge(Age age) Set the age of this voice.
void	setAudioPlayer(AudioPlayer player) Sets the audio player associated with this voice.
protected void	setDescription(java.lang.String description) Set the description of this voice.
void	setDetailedMetrics(boolean detailedMetrics) Sets the state of the detailedMetrics mode.
protected void	setDomain(java.lang.String domain) Set the domain of this voice.
void	setDumpRelations(boolean dumpRelations) Sets the state of the dumpRelations mode.
void	setDumpUtterance(boolean dumpUtterance) Sets the state of the dumpUtterance mode.
void	setDurationStretch(float stretch) Sets the duration stretch
protected void	setGender(Gender gender) Set the gender of this voice.
void	setLexicon(Lexicon lexicon) Sets the lexicon to be used by this voice.
protected void	setLoaded(boolean loaded) Sets the loaded state
protected void	setLocale(java.util.Locale locale) Set the locale of this voice.
void	setMetrics(boolean metrics) Sets the metrics mode.
protected void	setName(java.lang.String name) Set the name of this voice.
protected void	setOrganization(java.lang.String organization) Sets the organization which created this voice.
void	setOutputQueue(OutputQueue queue) Sets the output queue for this voice.
void	setPitch(float hertz) Sets the baseline pitch.
void	setPitchRange(float range) Sets the pitch range.
void	setPitchShift(float shift) Sets the pitch shift
void	setRate(float wpm) Sets the rate of speech.
void	setRunTitle(java.lang.String runTitle) Sets the title for this run.
void	setStyle(java.lang.String style) Sets the voice style.
void	setVerbose(boolean verbose) Sets the verbose mode.
void	setVolume(float vol) Sets the volume.
void	setWaveDumpFile(java.lang.String waveDumpFile) Sets the dumpfile for this voice.
boolean	speak(org.w3c.dom.Document doc) Speaks the given document.
boolean	speak(FreeTTSSpeakable speakable) Speak the given queue item.
boolean	speak(java.io.InputStream inputStream) Speaks the input stream.
boolean	speak(java.lang.String text) Speaks the given text.
void	startBatch() Starts a batch of utterances.
java.lang.String	toString() Returns the name of this Voice.
void	warn(java.lang.String message) Sends the given warning message to stderr.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DATABASE_NAME

public static final java.lang.String DATABASE_NAME

Constant that describes the name of the unit database used by this voice.

See Also:

Constant Field Values

PROP_PREFIX

public static final java.lang.String PROP_PREFIX

Prefix for System property names.

See Also:

Constant Field Values

FEATURE_SILENCE

public static final java.lang.String FEATURE_SILENCE

Feature name for the silence phone string.

See Also:

Constant Field Values

FEATURE_JOIN_TYPE

public static final java.lang.String FEATURE_JOIN_TYPE

Feature name for the join type string.

See Also:

Constant Field Values

DEFAULT_AUDIO_PLAYER

public static final java.lang.String DEFAULT_AUDIO_PLAYER

Feature name for the default AudioPlayer class to use.

See Also:

Constant Field Values

DEFAULT_AUDIO_PLAYER_DEFAULT

public static final java.lang.String DEFAULT_AUDIO_PLAYER_DEFAULT

The default class to use for the DEFAULT_AUDIO_PLAYER.

See Also:

Constant Field Values

Constructor Detail

Voice

public Voice()

Creates a new Voice. Utterances are sent to an output queue to be rendered as audio. Utterances are placed on the queue by an output thread. This queue is usually created via a call to 'createOutputThread,' which creates a thread that waits on the queue and sends the output to the audio player associated with this voice. If the queue is null, the output is rendered in the calling thread.

See Also:

createOutputThread()

Voice

public Voice(java.lang.String name,
             Gender gender,
             Age age,
             java.lang.String description,
             java.util.Locale locale,
             java.lang.String domain,
             java.lang.String organization)

Creates a new Voice like above, except that it also stores the properties of the voice.

Parameters:

name - the name of the voice

gender - the gender of the voice

age - the age of the voice

description - a human-readable string providing a description that can be displayed for the users.

locale - the locale of the voice

domain - the domain of this voice. For example,

organization - the organization which created the voice "general", "time", or "weather".

See Also:

Voice()

Method Detail

speak

public boolean speak(java.lang.String text)

Speaks the given text.

Parameters:

text - the text to speak

Returns:

true if the given text is spoken properly; otherwise false

speak

public boolean speak(org.w3c.dom.Document doc)

Speaks the given document.

Parameters:

doc - the JSML document to speak

Returns:

true if the given document is spoken properly; otherwise false

speak

public boolean speak(java.io.InputStream inputStream)

Speaks the input stream.

Parameters:

inputStream - the inputStream to speak

Returns:

true if the given input stream is spoken properly; otherwise false

speak

public boolean speak(FreeTTSSpeakable speakable)

Speak the given queue item. This is a synchronous method that does not return until the speakable is completely spoken or has been cancelled.

Parameters:

speakable - the item to speak

Returns:

true if the utterance was spoken properly, false otherwise

load

public void load()

Deprecated. As of FreeTTS 1.2, replaced by allocate().

allocate

public void allocate()

Allocate this Voice. It loads the lexicon and the audio output handler, and creates an audio output thread by invoking createOutputThread(), if one is not already created. It then calls the loader() method to load Voice-specific data, which include utterance processors.

isLoaded

public boolean isLoaded()

Returns true if this voice is loaded.

Returns:

true if the voice is loaded; otherwise false

setLoaded

protected void setLoaded(boolean loaded)

Sets the loaded state

Parameters:

loaded - the new loaded state otherwise false

processUtterance

public void processUtterance(Utterance u)
                      throws ProcessException

Processes the given Utterance by passing it to each UtteranceProcessor managed by this Voice. The UtteranceProcessors are called in the order they were added to the Voice.

Specified by:

processUtterance in interface UtteranceProcessor

Parameters:

u - the Utterance to process

Throws:

ProcessException - if an exception occurred while performing operations on the Utterance

createOutputThread

public static OutputQueue createOutputThread()

Creates an output thread that will asynchronously output utterances that are generated by this voice (and other voices).

Returns:

the queue where utterances should be placed.

getTokenizer

public abstract Tokenizer getTokenizer()

Returns the tokenizer associated with this voice.

Returns:

the tokenizer

getUtteranceProcessors

public java.util.List getUtteranceProcessors()

Return the list of UtteranceProcessor instances. Applications should use this to obtain and modify the contents of the UtteranceProcessor list.

Returns:

a List containing UtteranceProcessor instances

getFeatures

public FeatureSet getFeatures()

Returns the feature set associated with this voice.

Returns:

the feature set.

startBatch

public void startBatch()

Starts a batch of utterances. Utterances are sometimes batched in groups for timing purposes.

See Also:

endBatch()

endBatch

public void endBatch()

Ends a batch of utterances.

See Also:

startBatch()

setOutputQueue

public void setOutputQueue(OutputQueue queue)

Sets the output queue for this voice. If no output queue is set for the voice when the voice is loaded, a queue and thread will be created when the voice is loaded. If the outputQueue is set by an external entity by calling setOutputQueue, the caller is responsible for shutting down the output thread. That is, if you call 'setOutputQueue' then you are responsible for shutting down the output thread on your own. This is necessary since the output queue may be shared by a number of voices.

Utterances are placed on the queue to be output by an output thread. This queue is usually created via a call to 'createOutputThread' which creates a thread that waits on the queue and sends the output to the audio player associated with this voice. If the queue is null, the output is rendered in the calling thread.

Parameters:

queue - the output queue

getOutputQueue

public OutputQueue getOutputQueue()

Returns the output queue associated with this voice.

Returns:

the output queue associated with this voice

loader

protected abstract void loader()
                        throws java.io.IOException

Loads voice specific data. Subclasses of voice should implement this to perform class specific loading.

Throws:

java.io.IOException

processNode

protected java.lang.StringBuffer processNode(org.w3c.dom.Node n,
                                             java.lang.StringBuffer buf)

Adds text for just this node and returns any text that might be needed to undo the effects of this node after it is processed.

Parameters:

n - the node to traverse in depth-first order

buf - the buffer to append text to

Returns:

a String containing text to undo the effects of the node

dump

public void dump(java.io.PrintWriter output,
                 int pad,
                 java.lang.String title)

Dumps the voice in textual form.

Specified by:

dump in interface Dumpable

Parameters:

output - where to send the formatted output

pad - the initial padding

title - the title to print when dumping out

dumpProcessors

public void dumpProcessors(java.io.PrintWriter output,
                           int pad,
                           java.lang.String title)

Dumps the voice processors.

Parameters:

output - where to send the formatted output

pad - the initial padding

title - the title to print when dumping out

getFeatureProcessor

public FeatureProcessor getFeatureProcessor(java.lang.String name)

Returns a language/voice specific Feature Processor.

Parameters:

name - the name of the processor

Returns:

the processor associated with the name or null if none could be found

addFeatureProcessor

public void addFeatureProcessor(java.lang.String name,
                                FeatureProcessor fp)

Adds a language/voice specific Feature Processor to the set of FeatureProcessors supported by this voice.

Parameters:

name - the name of the processor

fp - the processor

log

public void log(java.lang.String message)

Prints the given message to System.out if "verbose" operation is enabled.

See Also:

setVerbose(boolean), isVerbose()

warn

public void warn(java.lang.String message)

Sends the given warning message to stderr.

error

public void error(java.lang.String message)

Sends the given error message to stderr and also throws an error exception.

isVerbose

public boolean isVerbose()

Gets the state of the verbose mode.

Returns:

true if verbose mode is on

setVerbose

public void setVerbose(boolean verbose)

Sets the verbose mode.

Parameters:

verbose - true if verbose mode should be on

isMetrics

public boolean isMetrics()

Gets the state of the metrics mode.

Returns:

true if metrics mode is on

setMetrics

public void setMetrics(boolean metrics)

Sets the metrics mode.

Parameters:

metrics - true if metrics mode should be on

isDetailedMetrics

public boolean isDetailedMetrics()

Gets the state of the detailedMetrics mode.

Returns:

true if detailedMetrics mode is on

setDetailedMetrics

public void setDetailedMetrics(boolean detailedMetrics)

Sets the state of the detailedMetrics mode.

Parameters:

detailedMetrics - true if detailedMetrics mode should be on

isDumpUtterance

public boolean isDumpUtterance()

Gets the state of the dumpUtterance mode.

Returns:

true if dumpUtterance mode is on

setDumpUtterance

public void setDumpUtterance(boolean dumpUtterance)

Sets the state of the dumpUtterance mode.

Parameters:

dumpUtterance - true if dumpUtterance mode should be on

isDumpRelations

public boolean isDumpRelations()

Gets the state of the dumpRelations mode.

Returns:

true if dumpRelations mode is on

setDumpRelations

public void setDumpRelations(boolean dumpRelations)

Sets the state of the dumpRelations mode.

Parameters:

dumpRelations - true if dumpRelations mode should be on

setRunTitle

public void setRunTitle(java.lang.String runTitle)

Sets the title for this run.

Parameters:

runTitle - the title for the run

getRunTitle

public java.lang.String getRunTitle()

Gets the title for this run.

Returns:

the title for the run

getPhoneFeature

public java.lang.String getPhoneFeature(java.lang.String phone,
                                        java.lang.String featureName)

Given a phoneme and a feature name, returns the feature.

Parameters:

phone - the phoneme of interest

featureName - the name of the feature of interest

Returns:

the feature with the given name

deallocate

public void deallocate()

Shuts down the voice processing.

setPitch

public void setPitch(float hertz)

Sets the baseline pitch.

Parameters:

hertz - the baseline pitch in hertz

getPitch

public float getPitch()

Retreives the baseline pitch.

Returns:

the baseline pitch in hertz

setPitchRange

public void setPitchRange(float range)

Sets the pitch range.

Parameters:

range - the range in hertz

getPitchRange

public float getPitchRange()

Gets the pitch range.

Returns:

the range in hertz

setPitchShift

public void setPitchShift(float shift)

Sets the pitch shift

Parameters:

shift - the pitch shift (1.0 is no shift)

getPitchShift

public float getPitchShift()

Gets the pitch shift.

Returns:

the pitch shift

setDurationStretch

public void setDurationStretch(float stretch)

Sets the duration stretch

Parameters:

stretch - the duration stretch (1.0 is no stretch)

getDurationStretch

public float getDurationStretch()

Gets the duration Stretch

Returns:

the duration stretch

setRate

public void setRate(float wpm)

Sets the rate of speech.

Parameters:

wpm - words per minute

getRate

public float getRate()

Gets the rate of speech.

Returns:

words per minute

setVolume

public void setVolume(float vol)

Sets the volume.

Parameters:

vol - the volume (0 to 1.0)

getVolume

public float getVolume()

Gets the volume.

Returns:

the volume (0 to 1.0)

getLexicon

public Lexicon getLexicon()

Gets the lexicon for this voice.

Returns:

the lexicon (or null if there is no lexicon)

setLexicon

public void setLexicon(Lexicon lexicon)

Sets the lexicon to be used by this voice.

Parameters:

lexicon - the lexicon to use

setWaveDumpFile

public void setWaveDumpFile(java.lang.String waveDumpFile)

Sets the dumpfile for this voice.

Parameters:

waveDumpFile - the dumpfile

getWaveDumpFile

public java.lang.String getWaveDumpFile()

Gets the dumpfile for this voice.

Returns:

the dumpfile

setAudioPlayer

public void setAudioPlayer(AudioPlayer player)

Sets the audio player associated with this voice. The caller is responsible for closing this player.

Parameters:

player - the audio player

getDefaultAudioPlayer

public AudioPlayer getDefaultAudioPlayer()
                                  throws java.lang.InstantiationException

Gets the default audio player for this voice. The return value will be non-null only if the DEFAULT_AUDIO_PLAYER system property has been set to the name of an AudioPlayer class, and that class is able to be instantiated via a no arg constructor. getAudioPlayer will automatically set the audio player for this voice to the default audio player if the audio player has not yet been set.

Returns:

the default AudioPlayer

Throws:

java.lang.InstantiationException

See Also:

DEFAULT_AUDIO_PLAYER, getAudioPlayer()

getAudioPlayer

public AudioPlayer getAudioPlayer()

Gets the audio player associated with this voice. If the audio player has not yet been set, the value will default to the return value of getDefaultAudioPlayer.

Returns:

the audio player

See Also:

getDefaultAudioPlayer()

getResource

protected java.net.URL getResource(java.lang.String resource)

Get a resource for this voice. By default, the voice is searched for in the package to which the voice class belongs. Subclasses are free to override this behaviour.

setName

protected void setName(java.lang.String name)

Set the name of this voice. [[[TODO: any standard format to the name?]]]

Parameters:

name - the name to assign this voice

getName

public java.lang.String getName()

Get the name of this voice.

Returns:

the name

toString

public java.lang.String toString()

Returns the name of this Voice.

Returns:

the name of this Voice

setGender

protected void setGender(Gender gender)

Set the gender of this voice.

Parameters:

gender - the gender to assign

getGender

public Gender getGender()

Get the gender of this voice.

Returns:

the gender of this voice

setAge

protected void setAge(Age age)

Set the age of this voice.

Parameters:

age - the age to assign

getAge

public Age getAge()

Get the age of this voice.

Returns:

the age of this voice

setDescription

protected void setDescription(java.lang.String description)

Set the description of this voice.

Parameters:

description - the human readable description to assign

getDescription

public java.lang.String getDescription()

Get the description of this voice.

Returns:

the human readable description of this voice

setLocale

protected void setLocale(java.util.Locale locale)

Set the locale of this voice.

Parameters:

locale - the locale of this voice.

getLocale

public java.util.Locale getLocale()

Get the locale of this voice.

Returns:

the locale of this voice.

setDomain

protected void setDomain(java.lang.String domain)

Set the domain of this voice.

Parameters:

domain - the domain of this voice. For example, "general", "time", or "weather".

getDomain

public java.lang.String getDomain()

Get the domain of this voice.

Returns:

the domain of this voice. For example, "general", "time", or "weather".

setStyle

public void setStyle(java.lang.String style)

Sets the voice style. This parameter is designed for human interpretation. Values might include "business", "casual", "robotic", "breathy"

Parameters:

style - the stile of this voice.

getStyle

public java.lang.String getStyle()

Gets the voice style. This parameter is designed for human interpretation. Values might include "business", "casual", "robotic", "breathy".

setOrganization

protected void setOrganization(java.lang.String organization)

Sets the organization which created this voice. For example "cmu", "sun", ...

Parameters:

organization - the name of the organization

getOrganization

public java.lang.String getOrganization()

Gets the organization which created this voice. For example "cmu", "sun", ...

Returns:

the name of the organization

getAudioOutput

protected abstract UtteranceProcessor getAudioOutput()
                                              throws java.io.IOException

Returns the AudioOutput processor to be used by this voice. Derived voices typically override this to customize behaviors.

Returns:

the audio output processor

Throws:

java.io.IOException - if an IO error occurs while getting processor