Class 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

      Fields 
      Modifier and Type Field Description
      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

      Constructors 
      Constructor Description
      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

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      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.
      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.
      void load()
      Deprecated.
      As of FreeTTS 1.2, replaced by allocate().
      protected abstract void loader()
      Loads voice specific data.
      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 setVolume​(float vol)
      Sets the volume.
      void setWaveDumpFile​(java.lang.String waveDumpFile)
      Sets the dumpfile for this voice.
      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.
      boolean speak​(org.w3c.dom.Document doc)
      Speaks the given document.
      void startBatch()
      Starts a batch of utterances.
      java.lang.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 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
      • 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.
        Overrides:
        toString in class java.lang.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​(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