marytts.client
Class MaryClient

java.lang.Object
  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:

• mary.client.profile (=true/false) - determines whether profiling (timing) information is calculated;
• mary.client.quiet (=true/false) - tells the client not to print any of the normal information to stderr.

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:

• mary.client.profile (=true/false) - determines whether profiling (timing) information is calculated;
• mary.client.quiet (=true/false) - tells the client not to print any of the normal information to stderr.

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