Package 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 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

Fields
Modifier and Type
Field
Description
`static final String`
`DATABASE_NAME`
Constant that describes the name of the unit database used by this voice.
`static final String`
`DEFAULT_AUDIO_PLAYER`
Feature name for the default AudioPlayer class to use.
`static final String`
`DEFAULT_AUDIO_PLAYER_DEFAULT`
The default class to use for the DEFAULT_AUDIO_PLAYER.
`static final String`
`FEATURE_JOIN_TYPE`
Feature name for the join type string.
`static final String`
`FEATURE_SILENCE`
Feature name for the silence phone string.
`static final String`
`PROP_PREFIX`
Prefix for System property names.

## Constructor Summary

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

## Method Summary

Modifier and Type
Method
Description
`void`
`addFeatureProcessor(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(PrintWriter output, int pad, String title)`
Dumps the voice in textual form.
`void`
`dumpProcessors(PrintWriter output, int pad, String title)`
Dumps the voice processors.
`void`
`endBatch()`
Ends a batch of utterances.
`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.
`String`
`getDescription()`
Get the description of this voice.
`String`
`getDomain()`
Get the domain of this voice.
`float`
`getDurationStretch()`
Gets the duration Stretch
`FeatureProcessor`
`getFeatureProcessor(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.
`Locale`
`getLocale()`
Get the locale of this voice.
`String`
`getName()`
Get the name of this voice.
`String`
`getOrganization()`
Gets the organization which created this voice.
`OutputQueue`
`getOutputQueue()`
Returns the output queue associated with this voice.
`String`
`getPhoneFeature(String phone, 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 URL`
`getResource(String resource)`
Get a resource for this voice.
`String`
`getRunTitle()`
Gets the title for this run.
`String`
`getStyle()`
Gets the voice style.
`abstract Tokenizer`
`getTokenizer()`
Returns the tokenizer associated with this voice.
`List`
`getUtteranceProcessors()`
Return the list of UtteranceProcessor instances.
`float`
`getVolume()`
Gets the volume.
`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.
`void`
`load()`
Deprecated.
As of FreeTTS 1.2, replaced by `allocate()`.
`protected abstract void`
`loader()`
Loads voice specific data.
`protected StringBuffer`
`processNode(Node n, 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(String description)`
Set the description of this voice.
`void`
`setDetailedMetrics(boolean detailedMetrics)`
Sets the state of the detailedMetrics mode.
`protected void`
`setDomain(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(Locale locale)`
Set the locale of this voice.
`void`
`setMetrics(boolean metrics)`
Sets the metrics mode.
`protected void`
`setName(String name)`
Set the name of this voice.
`protected void`
`setOrganization(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(String runTitle)`
Sets the title for this run.
`void`
`setStyle(String style)`
Sets the voice style.
`void`
`setVolume(float vol)`
Sets the volume.
`void`
`setWaveDumpFile(String waveDumpFile)`
Sets the dumpfile for this voice.
`boolean`
`speak(FreeTTSSpeakable speakable)`
Speak the given queue item.
`boolean`
`speak(InputStream inputStream)`
Speaks the input stream.
`boolean`
`speak(String text)`
Speaks the given text.
`boolean`
`speak(Document doc)`
Speaks the given document.
`void`
`startBatch()`
Starts a batch of utterances.
`String`
`toString()`
Returns the name of this Voice.

### Methods inherited from class java.lang.Object

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

## Field Details

### DATABASE_NAME

public static final 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 String PROP_PREFIX
Prefix for System property names.

See Also:
  - Constant Field Values

### FEATURE_SILENCE

public static final String FEATURE_SILENCE
Feature name for the silence phone string.

See Also:
  - Constant Field Values

### FEATURE_JOIN_TYPE

public static final String FEATURE_JOIN_TYPE
Feature name for the join type string.

See Also:
  - Constant Field Values

### DEFAULT_AUDIO_PLAYER

public static final 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 String DEFAULT_AUDIO_PLAYER_DEFAULT
The default class to use for the DEFAULT_AUDIO_PLAYER.

See Also:
  - Constant Field Values

## Constructor Details

### 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(String name, Gender gender, Age age, String description, Locale locale, String domain, 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 Details

### speak

public boolean speak(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(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(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 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 IOException
Loads voice specific data. Subclasses of voice should implement this to perform class specific loading.

Throws:
  `IOException`

### processNode

protected StringBuffer processNode(Node n, 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(PrintWriter output, int pad, 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(PrintWriter output, int pad, 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(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(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

### 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(String runTitle)
Sets the title for this run.

Parameters:
  `runTitle` - the title for the run

### getRunTitle

public String getRunTitle()
Gets the title for this run.

Returns:
  the title for the run

### getPhoneFeature

public String getPhoneFeature(String phone, 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(String waveDumpFile)
Sets the dumpfile for this voice.

Parameters:
  `waveDumpFile` - the dumpfile

### getWaveDumpFile

public 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 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:
  `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 URL getResource(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(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 String getName()
Get the name of this voice.

Returns:
  the name

### toString

public String toString()
Returns the name of this Voice.

Overrides:
  `toString` in class `Object`
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(String description)
Set the description of this voice.

Parameters:
  `description` - the human readable description to assign

### getDescription

public String getDescription()
Get the description of this voice.

Returns:
  the human readable description of this voice

### setLocale

protected void setLocale(Locale locale)
Set the locale of this voice.

Parameters:
  `locale` - the locale of this voice.

### getLocale

public Locale getLocale()
Get the locale of this voice.

Returns:
  the locale of this voice.

### setDomain

protected void setDomain(String domain)
Set the domain of this voice.

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

### getDomain

public String getDomain()
Get the domain of this voice.

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

### setStyle

public void setStyle(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 String getStyle()
Gets the voice style. This parameter is designed for human interpretation. Values might include "business", "casual", "robotic", "breathy".

### setOrganization

protected void setOrganization(String organization)
Sets the organization which created this voice. For example "cmu", "sun", ...

Parameters:
  `organization` - the name of the organization

### getOrganization

public 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 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:
  `IOException` - if an IO error occurs while getting processor