marytts.client
Class MaryClient

java.lang.Object
  extended by marytts.client.MaryClient
Direct Known Subclasses:
MaryHttpClient, MarySocketClient

public abstract class MaryClient
extends java.lang.Object

An HTTP client implementing the MARY protocol. It can be used as a command line client or from within java code.

Author:
Marc Schröder, oytun.turk
See Also:
A GUI interface to this client, Description of the MARY protocol

Nested Class Summary
static interface MaryClient.AudioPlayerListener
          A means of letting a caller code know that the audioplayer has finished.
 class MaryClient.AudioPlayerWriter
           
static class MaryClient.DataType
          An abstraction of server info about available data types.
static class MaryClient.Voice
          An abstraction of server info about available voices.
static class MaryClient.WarningReader
           
 
Field Summary
protected  boolean beQuiet
           
protected  MaryFormData data
           
protected  boolean doProfile
           
 
Constructor Summary
protected MaryClient()
          The simplest way to create a mary client.
protected MaryClient(Address serverAddress)
          The typical way to create a mary client.
protected MaryClient(Address serverAddress, boolean profile, boolean quiet)
          An alternative way to create a mary client, which works with applets.
protected MaryClient(boolean quiet)
           
 
Method Summary
protected abstract  void _process(java.lang.String input, java.lang.String inputType, java.lang.String outputType, java.lang.String locale, java.lang.String audioType, java.lang.String defaultVoiceName, java.lang.String defaultStyle, java.lang.String defaultEffects, java.lang.Object output, long timeout, boolean streamingAudio, java.lang.String outputTypeParams, MaryClient.AudioPlayerListener playerListener)
           
protected abstract  void fillAudioFileFormatAndOutTypes()
           
protected abstract  void fillDataTypes()
           
protected abstract  void fillEffectHelpText(java.lang.String effectName)
           
protected abstract  void fillServerExampleText(java.lang.String dataType, java.lang.String locale)
           
protected abstract  void fillServerVersion()
           
protected abstract  void fillVoiceExampleTexts(java.lang.String voicename)
           
protected abstract  void fillVoices()
           
 Address getAddress()
           
 java.util.Vector<MaryClient.DataType> getAllDataTypes()
          Obtain a list of all data types known to the server.
 java.lang.String getAudioEffects()
           
static javax.sound.sampled.AudioFileFormat.Type getAudioFileFormatType(java.lang.String name)
          Return an audio file format type for the given string.
 java.util.Vector<java.lang.String> getAudioFileFormatTypes()
          Get the audio file format types known by the server, one per line.
 java.util.Vector<java.lang.String> getAudioOutTypes()
           
protected abstract  java.lang.String getDefaultAudioEffects()
          Request the available audio effects for a voice from the server
abstract  java.lang.String getFeatures(java.lang.String locale)
           
abstract  java.lang.String getFeaturesForVoice(java.lang.String voice)
           
 java.util.Vector<MaryClient.Voice> getGeneralDomainVoices()
          Provide a list of general domain voices known to the server.
 java.util.Vector<MaryClient.Voice> getGeneralDomainVoices(java.util.Locale locale)
          Provide a list of general domain voices known to the server.
 java.lang.String getHost()
           
 java.util.Vector<MaryClient.DataType> getInputDataTypes()
          Obtain a list of input data types known to the server.
 java.util.Vector<MaryClient.Voice> getLimitedDomainVoices()
          Provide a list of limited domain voices known to the server.
 java.util.Vector<MaryClient.Voice> getLimitedDomainVoices(java.util.Locale locale)
          Provide a list of limited domain voices known to the server.
static MaryClient getMaryClient()
           
static MaryClient getMaryClient(Address serverAddress)
          The typical way to create a mary client.
static MaryClient getMaryClient(Address serverAddress, boolean profile, boolean quiet)
           
 java.util.Vector<MaryClient.DataType> getOutputDataTypes()
          Obtain a list of output data types known to the server.
 int getPort()
           
 java.lang.String getServerExampleText(java.lang.String dataType, java.lang.String locale)
          Request an example text for a given data type from the server.
 java.util.Vector<java.lang.String> getVoiceExampleTextsLimitedDomain(java.lang.String voicename)
          Request the example texts of a limited domain unit selection voice from the server
 java.util.Vector<MaryClient.Voice> getVoices()
          Provide a list of voices known to the server.
 java.util.Vector<MaryClient.Voice> getVoices(java.util.Locale locale)
          Provide a list of voices known to the server for the given locale.
protected  void initialise(boolean profile, boolean quiet)
          Initialise a connection to the MARY server at the specified host and port.
abstract  boolean isHMMEffect(java.lang.String effectName)
           
 boolean isServerVersionAtLeast(java.lang.String version)
           
static void main(java.lang.String[] args)
           
 void process(java.lang.String input, java.lang.String inputType, java.lang.String outputType, java.lang.String locale, java.lang.String audioType, java.lang.String defaultVoiceName, java.io.OutputStream output)
           
 void process(java.lang.String input, java.lang.String inputType, java.lang.String outputType, java.lang.String locale, java.lang.String audioType, java.lang.String defaultVoiceName, java.io.OutputStream output, long timeout)
           
 void process(java.lang.String input, java.lang.String inputType, java.lang.String outputType, java.lang.String locale, java.lang.String audioType, java.lang.String defaultVoiceName, java.lang.String defaultStyle, java.lang.String defaultEffects, java.lang.String outputTypeParams, java.io.OutputStream output)
          The standard way to call the MARY client when the output is to go to an output stream.
 void process(java.lang.String input, java.lang.String inputType, java.lang.String outputType, java.lang.String locale, java.lang.String audioType, java.lang.String defaultVoiceName, java.lang.String defaultStyle, java.lang.String defaultEffects, java.lang.String outputTypeParams, java.io.OutputStream output, long timeout)
          An alternative way to call the MARY client when the output is to go to an output stream, with a timeout.
abstract  java.lang.String requestDefaultEffectParameters(java.lang.String effectName)
           
 java.lang.String requestEffectHelpText(java.lang.String effectName)
           
abstract  java.lang.String requestFullEffect(java.lang.String effectName, java.lang.String currentEffectParameters)
           
 void streamAudio(java.lang.String input, java.lang.String inputType, java.lang.String locale, java.lang.String audioType, java.lang.String defaultVoiceName, java.lang.String defaultStyle, java.lang.String defaultEffects, AudioPlayer audioPlayer, MaryClient.AudioPlayerListener listener)
          Call the mary client to stream audio via the given audio player.
static void usage()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

data

protected MaryFormData data

beQuiet

protected boolean beQuiet

doProfile

protected boolean doProfile
Constructor Detail

MaryClient

protected MaryClient()
              throws java.io.IOException
The simplest way to create a mary client. It will connect to the MARY server running on localhost.

Throws:
java.io.IOException - if communication with the server fails
java.net.UnknownHostException - if the host could not be found

MaryClient

protected MaryClient(boolean quiet)
              throws java.io.IOException
Throws:
java.io.IOException

MaryClient

protected MaryClient(Address serverAddress)
              throws java.io.IOException
The typical way to create a mary client. It will connect to the MARY client running at the given host and port. This constructor reads two system properties:

Parameters:
host - the host where to contact a MARY server
port - the socket port where to contact a MARY server
Throws:
java.io.IOException - if communication with the server fails
java.net.UnknownHostException - if the host could not be found

MaryClient

protected MaryClient(Address serverAddress,
                     boolean profile,
                     boolean quiet)
              throws java.io.IOException
An alternative way to create a mary client, which works with applets. It will connect to the MARY client running at the given host and port. Note that in applets, the host must be the same as the one from which the applet was loaded; otherwise, a security exception is thrown.

Parameters:
host - the host where to contact a MARY server
port - the socket port where to contact a MARY server
profile - determines whether profiling (timing) information is calculated
quiet - tells the client not to print any of the normal information to stderr
Throws:
java.io.IOException - if communication with the server fails
java.net.UnknownHostException - if the host could not be found
Method Detail

getMaryClient

public static MaryClient getMaryClient()
                                throws java.io.IOException
Throws:
java.io.IOException

getMaryClient

public static MaryClient getMaryClient(Address serverAddress)
                                throws java.io.IOException
The typical way to create a mary client. It will connect to the MARY server running at the given host and port, either as a HTTP or as a Socket server. This constructor reads two system properties:

Parameters:
host - the host where to contact a MARY server
port - the socket port where to contact a MARY server
Throws:
java.io.IOException - if communication with the server fails
java.net.UnknownHostException - if the host could not be found

getMaryClient

public static MaryClient getMaryClient(Address serverAddress,
                                       boolean profile,
                                       boolean quiet)
                                throws java.io.IOException
Throws:
java.io.IOException

initialise

protected final void initialise(boolean profile,
                                boolean quiet)
                         throws java.io.IOException
Initialise a connection to the MARY server at the specified host and port.

Parameters:
serverHost - the host where to contact a MARY server
serverPort - the socket port where to contact a MARY server
profile - whether to do profiling
quiet - whether to refrain from printing information to stderr
Throws:
java.io.IOException - if communication with the server fails
java.net.UnknownHostException - if the host could not be found

getAddress

public Address getAddress()

getHost

public java.lang.String getHost()

getPort

public int getPort()

getAudioFileFormatTypes

public java.util.Vector<java.lang.String> getAudioFileFormatTypes()
                                                           throws java.io.IOException
Get the audio file format types known by the server, one per line. Each line has the format: extension name

Returns:
Throws:
java.io.IOException
java.net.UnknownHostException

getAudioOutTypes

public java.util.Vector<java.lang.String> getAudioOutTypes()
                                                    throws java.io.IOException
Throws:
java.io.IOException

fillAudioFileFormatAndOutTypes

protected abstract void fillAudioFileFormatAndOutTypes()
                                                throws java.io.IOException
Throws:
java.io.IOException

fillServerVersion

protected abstract void fillServerVersion()
                                   throws java.io.IOException
Throws:
java.io.IOException

isServerVersionAtLeast

public boolean isServerVersionAtLeast(java.lang.String version)
                               throws java.io.IOException
Throws:
java.io.IOException

getAllDataTypes

public java.util.Vector<MaryClient.DataType> getAllDataTypes()
                                                      throws java.io.IOException
Obtain a list of all data types known to the server. If the information is not yet available, the server is queried. This is optional information which is not required for the normal operation of the client, but may help to avoid incompatibilities.

Throws:
java.lang.Exception - if communication with the server fails
java.io.IOException

getInputDataTypes

public java.util.Vector<MaryClient.DataType> getInputDataTypes()
                                                        throws java.io.IOException
Obtain a list of input data types known to the server. If the information is not yet available, the server is queried. This is optional information which is not required for the normal operation of the client, but may help to avoid incompatibilities.

Returns:
a Vector of MaryHttpClient.DataType objects.
Throws:
java.lang.Exception - if communication with the server fails
java.io.IOException

getOutputDataTypes

public java.util.Vector<MaryClient.DataType> getOutputDataTypes()
                                                         throws java.io.IOException
Obtain a list of output data types known to the server. If the information is not yet available, the server is queried. This is optional information which is not required for the normal operation of the client, but may help to avoid incompatibilities.

Returns:
a Vector of MaryHttpClient.DataType objects.
Throws:
java.io.IOException - if communication with the server fails
java.net.UnknownHostException - if the host could not be found

fillDataTypes

protected abstract void fillDataTypes()
                               throws java.io.IOException
Throws:
java.io.IOException

getVoices

public java.util.Vector<MaryClient.Voice> getVoices()
                                             throws java.io.IOException
Provide a list of voices known to the server. If the information is not yet available, query the server for it. This is optional information which is not required for the normal operation of the client, but may help to avoid incompatibilities.

Returns:
a Vector of MaryHttpClient.Voice objects.
Throws:
java.io.IOException - if communication with the server fails
java.net.UnknownHostException - if the host could not be found

getVoices

public java.util.Vector<MaryClient.Voice> getVoices(java.util.Locale locale)
                                             throws java.io.IOException
Provide a list of voices known to the server for the given locale. If the information is not yet available, query the server for it. This is optional information which is not required for the normal operation of the client, but may help to avoid incompatibilities.

Parameters:
locale - the requested voice locale
Returns:
a Vector of MaryHttpClient.Voice objects, or null if no voices exist for that locale.
Throws:
java.io.IOException - if communication with the server fails
java.net.UnknownHostException - if the host could not be found

getGeneralDomainVoices

public java.util.Vector<MaryClient.Voice> getGeneralDomainVoices()
                                                          throws java.io.IOException
Provide a list of general domain voices known to the server. If the information is not yet available, query the server for it. This is optional information which is not required for the normal operation of the client, but may help to avoid incompatibilities.

Returns:
a Vector of MaryHttpClient.Voice objects, or null if no such voices exist.
Throws:
java.io.IOException - if communication with the server fails
java.net.UnknownHostException - if the host could not be found

getLimitedDomainVoices

public java.util.Vector<MaryClient.Voice> getLimitedDomainVoices()
                                                          throws java.io.IOException
Provide a list of limited domain voices known to the server. If the information is not yet available, query the server for it. This is optional information which is not required for the normal operation of the client, but may help to avoid incompatibilities.

Returns:
a Vector of MaryHttpClient.Voice objects, or null if no such voices exist.
Throws:
java.lang.Exception - if communication with the server fails
java.io.IOException

getGeneralDomainVoices

public java.util.Vector<MaryClient.Voice> getGeneralDomainVoices(java.util.Locale locale)
                                                          throws java.io.IOException
Provide a list of general domain voices known to the server. If the information is not yet available, query the server for it. This is optional information which is not required for the normal operation of the client, but may help to avoid incompatibilities.

Parameters:
locale - the requested voice locale
Returns:
a Vector of MaryHttpClient.Voice objects, or null if no such voices exist.
Throws:
java.lang.Exception - if communication with the server fails
java.io.IOException

getLimitedDomainVoices

public java.util.Vector<MaryClient.Voice> getLimitedDomainVoices(java.util.Locale locale)
                                                          throws java.io.IOException
Provide a list of limited domain voices known to the server. If the information is not yet available, query the server for it. This is optional information which is not required for the normal operation of the client, but may help to avoid incompatibilities.

Parameters:
locale - the requested voice locale
Returns:
a Vector of MaryHttpClient.Voice objects, or null if no such voices exist.
Throws:
java.lang.Exception - if communication with the server fails
java.io.IOException

fillVoices

protected abstract void fillVoices()
                            throws java.io.IOException
Throws:
java.io.IOException

getVoiceExampleTextsLimitedDomain

public java.util.Vector<java.lang.String> getVoiceExampleTextsLimitedDomain(java.lang.String voicename)
                                                                     throws java.io.IOException
Request the example texts of a limited domain unit selection voice from the server

Parameters:
voicename - the voice
Returns:
the example text
Throws:
java.io.IOException
java.net.UnknownHostException

fillVoiceExampleTexts

protected abstract void fillVoiceExampleTexts(java.lang.String voicename)
                                       throws java.io.IOException
Throws:
java.io.IOException

getServerExampleText

public java.lang.String getServerExampleText(java.lang.String dataType,
                                             java.lang.String locale)
                                      throws java.io.IOException
Request an example text for a given data type from the server.

Parameters:
dataType - the string representation of the data type, e.g. "RAWMARYXML". This is optional information which is not required for the normal operation of the client, but may help to avoid incompatibilities.
Returns:
the example text, or null if none could be obtained.
Throws:
java.io.IOException - if communication with the server fails
java.net.UnknownHostException - if the host could not be found

fillServerExampleText

protected abstract void fillServerExampleText(java.lang.String dataType,
                                              java.lang.String locale)
                                       throws java.io.IOException
Throws:
java.io.IOException

getDefaultAudioEffects

protected abstract java.lang.String getDefaultAudioEffects()
                                                    throws java.io.IOException
Request the available audio effects for a voice from the server

Parameters:
voicename - the voice
Returns:
A string of available audio effects and default parameters, i.e. "FIRFilter,Robot(amount=50)"
Throws:
java.io.IOException
java.net.UnknownHostException

getAudioEffects

public java.lang.String getAudioEffects()
                                 throws java.io.IOException
Throws:
java.io.IOException

requestDefaultEffectParameters

public abstract java.lang.String requestDefaultEffectParameters(java.lang.String effectName)
                                                         throws java.io.IOException
Throws:
java.io.IOException

requestFullEffect

public abstract java.lang.String requestFullEffect(java.lang.String effectName,
                                                   java.lang.String currentEffectParameters)
                                            throws java.io.IOException
Throws:
java.io.IOException

isHMMEffect

public abstract boolean isHMMEffect(java.lang.String effectName)
                             throws java.io.IOException
Throws:
java.io.IOException

requestEffectHelpText

public java.lang.String requestEffectHelpText(java.lang.String effectName)
                                       throws java.io.IOException
Throws:
java.io.IOException

fillEffectHelpText

protected abstract void fillEffectHelpText(java.lang.String effectName)
                                    throws java.io.IOException
Throws:
java.io.IOException

getFeatures

public abstract java.lang.String getFeatures(java.lang.String locale)
                                      throws java.io.IOException
Throws:
java.io.IOException

getFeaturesForVoice

public abstract java.lang.String getFeaturesForVoice(java.lang.String voice)
                                              throws java.io.IOException
Throws:
java.io.IOException

streamAudio

public void streamAudio(java.lang.String input,
                        java.lang.String inputType,
                        java.lang.String locale,
                        java.lang.String audioType,
                        java.lang.String defaultVoiceName,
                        java.lang.String defaultStyle,
                        java.lang.String defaultEffects,
                        AudioPlayer audioPlayer,
                        MaryClient.AudioPlayerListener listener)
                 throws java.io.IOException
Call the mary client to stream audio via the given audio player. The server will provide audio data as it is being generated. If the connection to the server is not too slow, streaming will be attractive because it reduces considerably the amount of time one needs to wait for the first audio to play.

Parameters:
input - a textual representation of the input data
inputType - the name of the input data type, e.g. TEXT or RAWMARYXML.
audioType - the name of the audio format, e.g. "WAVE" or "MP3".
defaultVoiceName - the name of the voice to use, e.g. de7 or us1.
audioPlayer - the FreeTTS audio player with which to play the synthesised audio data. The given audio player must already be instanciated. See the package com.sun.speech.freetts.audio in FreeTTS for implementations of AudioPlayer.
listener - a means for letting calling code know that the AudioPlayer has finished.
Throws:
java.io.IOException - if communication with the server fails
java.net.UnknownHostException - if the host could not be found
See Also:
getInputDataTypes(), getVoices()

process

public void process(java.lang.String input,
                    java.lang.String inputType,
                    java.lang.String outputType,
                    java.lang.String locale,
                    java.lang.String audioType,
                    java.lang.String defaultVoiceName,
                    java.lang.String defaultStyle,
                    java.lang.String defaultEffects,
                    java.lang.String outputTypeParams,
                    java.io.OutputStream output)
             throws java.io.IOException
The standard way to call the MARY client when the output is to go to an output stream.

Parameters:
input - a textual representation of the input data
inputType - the name of the input data type, e.g. TEXT or RAWMARYXML.
outputType - the name of the output data type, e.g. AUDIO or ACOUSTPARAMS.
audioType - the name of the audio format, e.g. "WAVE" or "MP3".
defaultVoiceName - the name of the voice to use, e.g. de7 or us1.
audioEffects - the audio effects and their parameters to be applied as a post-processing step, e.g. Robot(Amount=100), Whisper(amount=50)
outputTypeParams - any additional parameters, e.g. for output type TARGETFEATURES, the space-separated list of features to produce. Can be null.
output - the output stream into which the data from the server is to be written.
Throws:
java.io.IOException - if communication with the server fails
java.net.UnknownHostException - if the host could not be found
See Also:
getInputDataTypes(), getOutputDataTypes(), getVoices()

process

public void process(java.lang.String input,
                    java.lang.String inputType,
                    java.lang.String outputType,
                    java.lang.String locale,
                    java.lang.String audioType,
                    java.lang.String defaultVoiceName,
                    java.io.OutputStream output)
             throws java.io.IOException
Throws:
java.io.IOException

process

public void process(java.lang.String input,
                    java.lang.String inputType,
                    java.lang.String outputType,
                    java.lang.String locale,
                    java.lang.String audioType,
                    java.lang.String defaultVoiceName,
                    java.lang.String defaultStyle,
                    java.lang.String defaultEffects,
                    java.lang.String outputTypeParams,
                    java.io.OutputStream output,
                    long timeout)
             throws java.io.IOException
An alternative way to call the MARY client when the output is to go to an output stream, with a timeout.

Parameters:
input - a textual representation of the input data
inputType - the name of the input data type, e.g. TEXT or RAWMARYXML.
outputType - the name of the output data type, e.g. AUDIO or ACOUSTPARAMS.
audioType - the name of the audio format, e.g. "WAVE" or "MP3".
defaultVoiceName - the name of the voice to use, e.g. de7 or us1.
audioEffects - the audio effects and their parameters to be applied as a post-processing step, e.g. Robot(Amount=100), Whisper(amount=50)
outputTypeParams - any additional parameters, e.g. for output type TARGETFEATURES, the space-separated list of features to produce. Can be null.
output - the output stream into which the data from the server is to be written.
timeout - if >0, sets a timer to as many milliseconds; if processing is not finished by then, the connection with the Mary server is forcefully cut, resulting in an IOException.
Throws:
java.io.IOException - if communication with the server fails
java.net.UnknownHostException - if the host could not be found
See Also:
getInputDataTypes(), getOutputDataTypes(), getVoices()

process

public void process(java.lang.String input,
                    java.lang.String inputType,
                    java.lang.String outputType,
                    java.lang.String locale,
                    java.lang.String audioType,
                    java.lang.String defaultVoiceName,
                    java.io.OutputStream output,
                    long timeout)
             throws java.io.IOException
Throws:
java.io.IOException

_process

protected abstract void _process(java.lang.String input,
                                 java.lang.String inputType,
                                 java.lang.String outputType,
                                 java.lang.String locale,
                                 java.lang.String audioType,
                                 java.lang.String defaultVoiceName,
                                 java.lang.String defaultStyle,
                                 java.lang.String defaultEffects,
                                 java.lang.Object output,
                                 long timeout,
                                 boolean streamingAudio,
                                 java.lang.String outputTypeParams,
                                 MaryClient.AudioPlayerListener playerListener)
                          throws java.io.IOException
Throws:
java.io.IOException

getAudioFileFormatType

public static javax.sound.sampled.AudioFileFormat.Type getAudioFileFormatType(java.lang.String name)
Return an audio file format type for the given string. In addition to the built-in types, this can deal with MP3 supported by tritonus.

Returns:
the audio file format type if it is known, or null.
See Also:
#canCreateMP3(), #canCreateOgg()

usage

public static void usage()

main

public static void main(java.lang.String[] args)
                 throws java.io.IOException,
                        java.lang.InterruptedException
Throws:
java.io.IOException
java.lang.InterruptedException