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:

  • 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:

    • PROP_PREFIX

      public static final String PROP_PREFIX
      Prefix for System property names.
      See Also:

    • FEATURE_SILENCE

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

    • FEATURE_JOIN_TYPE

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

    • DEFAULT_AUDIO_PLAYER

      public static final String DEFAULT_AUDIO_PLAYER
      Feature name for the default AudioPlayer class to use.
      See Also:

    • DEFAULT_AUDIO_PLAYER_DEFAULT

      public static final String DEFAULT_AUDIO_PLAYER_DEFAULT
      The default class to use for the DEFAULT_AUDIO_PLAYER.
      See Also:

  • 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:

    • 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:

  • 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

      public void endBatch()
      Ends a batch of utterances.
      See Also:

    • 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:

    • 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:

    • 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