marytts.client

Class MaryClient

java.lang.Object

marytts.client.MaryClient

Direct Known Subclasses:

MaryHttpClient, MarySocketClient

public abstract class MaryClient
extends 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

Nested Classes

Modifier and Type	Class and Description
static interface	MaryClient.AudioPlayerListener A means of letting a caller code know that the audioplayer has finished.
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

Fields

Modifier and Type	Field and Description
protected boolean	beQuiet
protected MaryFormData	data
protected boolean	doProfile

Constructor Summary

Constructors

Modifier	Constructor and Description
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

Methods

Modifier and Type	Method and Description
protected abstract void	_process(String input, String inputType, String outputType, String locale, String audioType, String defaultVoiceName, String defaultStyle, String defaultEffects, Object output, long timeout, boolean streamingAudio, String outputTypeParams, MaryClient.AudioPlayerListener playerListener)
protected abstract void	fillAudioFileFormatAndOutTypes()
protected abstract void	fillDataTypes()
protected abstract void	fillEffectHelpText(String effectName)
protected abstract void	fillLocales()
protected abstract void	fillServerExampleText(String dataType, String locale)
protected abstract void	fillServerVersion()
protected abstract void	fillVoiceExampleTexts(String voicename)
protected abstract void	fillVoices()
Address	getAddress()
Vector<MaryClient.DataType>	getAllDataTypes() Obtain a list of all data types known to the server.
String	getAudioEffects()
static AudioFileFormat.Type	getAudioFileFormatType(String name) Return an audio file format type for the given string.
Vector<String>	getAudioFileFormatTypes() Get the audio file format types known by the server, one per line.
Vector<String>	getAudioOutTypes()
protected abstract String	getDefaultAudioEffects() Request the available audio effects for a voice from the server
abstract String	getFeatures(String locale)
abstract String	getFeaturesForVoice(String voice)
Vector<MaryClient.Voice>	getGeneralDomainVoices() Provide a list of general domain voices known to the server.
Vector<MaryClient.Voice>	getGeneralDomainVoices(Locale locale) Provide a list of general domain voices known to the server.
String	getHost()
Vector<MaryClient.DataType>	getInputDataTypes() Obtain a list of input data types known to the server.
Vector<MaryClient.Voice>	getLimitedDomainVoices() Provide a list of limited domain voices known to the server.
Vector<MaryClient.Voice>	getLimitedDomainVoices(Locale locale) Provide a list of limited domain voices known to the server.
Set<Locale>	getLocales()
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)
Vector<MaryClient.DataType>	getOutputDataTypes() Obtain a list of output data types known to the server.
int	getPort()
String	getServerExampleText(String dataType, String locale) Request an example text for a given data type from the server.
Vector<String>	getVoiceExampleTextsLimitedDomain(String voicename) Request the example texts of a limited domain unit selection voice from the server
Vector<MaryClient.Voice>	getVoices() Provide a list of voices known to the server.
Vector<MaryClient.Voice>	getVoices(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(String effectName)
boolean	isServerVersionAtLeast(String version)
static void	main(String[] args)
void	process(String input, String inputType, String outputType, String locale, String audioType, String defaultVoiceName, OutputStream output)
void	process(String input, String inputType, String outputType, String locale, String audioType, String defaultVoiceName, OutputStream output, long timeout)
void	process(String input, String inputType, String outputType, String locale, String audioType, String defaultVoiceName, String defaultStyle, String defaultEffects, String outputTypeParams, OutputStream output) The standard way to call the MARY client when the output is to go to an output stream.
void	process(String input, String inputType, String outputType, String locale, String audioType, String defaultVoiceName, String defaultStyle, String defaultEffects, String outputTypeParams, 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 String	requestDefaultEffectParameters(String effectName)
String	requestEffectHelpText(String effectName)
abstract String	requestFullEffect(String effectName, String currentEffectParameters)
void	streamAudio(String input, String inputType, String locale, String audioType, String defaultVoiceName, String defaultStyle, 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 IOException

The simplest way to create a mary client. It will connect to the MARY server running on localhost.

Throws:

IOException - if communication with the server fails

MaryClient

protected MaryClient(boolean quiet)
              throws IOException

Throws:

IOException

MaryClient

protected MaryClient(Address serverAddress)
              throws 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:

serverAddress - the address of the server

Throws:

IOException - if communication with the server fails

MaryClient

protected MaryClient(Address serverAddress,
          boolean profile,
          boolean quiet)
              throws 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:

serverAddress - the address of the server

profile - determines whether profiling (timing) information is calculated

quiet - tells the client not to print any of the normal information to stderr

Throws:

IOException - if communication with the server fails

Method Detail

getMaryClient

public static MaryClient getMaryClient()
                                throws IOException

Throws:

IOException

getMaryClient

public static MaryClient getMaryClient(Address serverAddress)
                                throws 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:

serverAddress - address of the server

Returns:

getMaryClient(serverAddress, profile, quiet)

Throws:

IOException - if communication with the server fails

getMaryClient

public static MaryClient getMaryClient(Address serverAddress,
                       boolean profile,
                       boolean quiet)
                                throws IOException

Throws:

IOException

initialise

protected final void initialise(boolean profile,
              boolean quiet)
                         throws IOException

Initialise a connection to the MARY server at the specified host and port.

Parameters:

profile - whether to do profiling

quiet - whether to refrain from printing information to stderr

Throws:

IOException - if communication with the server fails

getAddress

public Address getAddress()

getHost

public String getHost()

getPort

public int getPort()

getAudioFileFormatTypes

public Vector<String> getAudioFileFormatTypes()
                                       throws IOException

Get the audio file format types known by the server, one per line. Each line has the format: extension name

Returns:

data.audioFileFormatTypes if data.audioFileFormatTypes == null || data.audioOutTypes == null

Throws:

IOException - IOException

getAudioOutTypes

public Vector<String> getAudioOutTypes()
                                throws IOException

Throws:

IOException

fillAudioFileFormatAndOutTypes

protected abstract void fillAudioFileFormatAndOutTypes()
                                                throws IOException

Throws:

IOException

fillServerVersion

protected abstract void fillServerVersion()
                                   throws IOException

Throws:

IOException

isServerVersionAtLeast

public boolean isServerVersionAtLeast(String version)
                               throws IOException

Throws:

IOException

getAllDataTypes

public Vector<MaryClient.DataType> getAllDataTypes()
                                            throws 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.

Returns:

data.allDataTypes

Throws:

IOException - if communication with the server fails

getInputDataTypes

public Vector<MaryClient.DataType> getInputDataTypes()
                                              throws 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:

IOException - if communication with the server fails

getOutputDataTypes

public Vector<MaryClient.DataType> getOutputDataTypes()
                                               throws 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:

IOException - if communication with the server fails

fillDataTypes

protected abstract void fillDataTypes()
                               throws IOException

Throws:

IOException

getVoices

public Vector<MaryClient.Voice> getVoices()
                                   throws 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:

IOException - if communication with the server fails

getVoices

public Vector<MaryClient.Voice> getVoices(Locale locale)
                                   throws 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:

IOException - if communication with the server fails

getGeneralDomainVoices

public Vector<MaryClient.Voice> getGeneralDomainVoices()
                                                throws 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:

IOException - if communication with the server fails

getLimitedDomainVoices

public Vector<MaryClient.Voice> getLimitedDomainVoices()
                                                throws 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:

IOException - if communication with the server fails

getGeneralDomainVoices

public Vector<MaryClient.Voice> getGeneralDomainVoices(Locale locale)
                                                throws 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:

IOException - if communication with the server fails

getLimitedDomainVoices

public Vector<MaryClient.Voice> getLimitedDomainVoices(Locale locale)
                                                throws 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:

IOException - if communication with the server fails

fillVoices

protected abstract void fillVoices()
                            throws IOException

Throws:

IOException

getLocales

public Set<Locale> getLocales()
                       throws IOException

Throws:

IOException

fillLocales

protected abstract void fillLocales()
                             throws IOException

Throws:

IOException

getVoiceExampleTextsLimitedDomain

public Vector<String> getVoiceExampleTextsLimitedDomain(String voicename)
                                                 throws IOException

Request the example texts of a limited domain unit selection voice from the server

Parameters:

voicename - the voice

Returns:

the example text

Throws:

IOException - IOException

fillVoiceExampleTexts

protected abstract void fillVoiceExampleTexts(String voicename)
                                       throws IOException

Throws:

IOException

getServerExampleText

public String getServerExampleText(String dataType,
                          String locale)
                            throws 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.

locale - locale

Returns:

the example text, or null if none could be obtained.

Throws:

IOException - if communication with the server fails

fillServerExampleText

protected abstract void fillServerExampleText(String dataType,
                         String locale)
                                       throws IOException

Throws:

IOException

getDefaultAudioEffects

protected abstract String getDefaultAudioEffects()
                                          throws IOException

Request the available audio effects for a voice from the server

Returns:

A string of available audio effects and default parameters, i.e. "FIRFilter,Robot(amount=50)"

Throws:

IOException - IOException

getAudioEffects

public String getAudioEffects()
                       throws IOException

Throws:

IOException

requestDefaultEffectParameters

public abstract String requestDefaultEffectParameters(String effectName)
                                               throws IOException

Throws:

IOException

requestFullEffect

public abstract String requestFullEffect(String effectName,
                       String currentEffectParameters)
                                  throws IOException

Throws:

IOException

isHMMEffect

public abstract boolean isHMMEffect(String effectName)
                             throws IOException

Throws:

IOException

requestEffectHelpText

public String requestEffectHelpText(String effectName)
                             throws IOException

Throws:

IOException

fillEffectHelpText

protected abstract void fillEffectHelpText(String effectName)
                                    throws IOException

Throws:

IOException

getFeatures

public abstract String getFeatures(String locale)
                            throws IOException

Throws:

IOException

getFeaturesForVoice

public abstract String getFeaturesForVoice(String voice)
                                    throws IOException

Throws:

IOException

streamAudio

public void streamAudio(String input,
               String inputType,
               String locale,
               String audioType,
               String defaultVoiceName,
               String defaultStyle,
               String defaultEffects,
               AudioPlayer audioPlayer,
               MaryClient.AudioPlayerListener listener)
                 throws 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.

locale - locale

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.

defaultStyle - defaultStyle

defaultEffects - defaultEffects

audioPlayer - the FreeTTS audio player with which to play the synthesized audio data. The given audio player must already be instantiated. 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:

IOException - if communication with the server fails

See Also:

getInputDataTypes(), getVoices()

process

public void process(String input,
           String inputType,
           String outputType,
           String locale,
           String audioType,
           String defaultVoiceName,
           String defaultStyle,
           String defaultEffects,
           String outputTypeParams,
           OutputStream output)
             throws 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.

locale - locale

defaultStyle - defaultStyle

defaultEffects - defaultEffects

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:

IOException - if communication with the server fails

See Also:

getInputDataTypes(), getOutputDataTypes(), getVoices()

process

public void process(String input,
           String inputType,
           String outputType,
           String locale,
           String audioType,
           String defaultVoiceName,
           OutputStream output)
             throws IOException

Throws:

IOException

process

public void process(String input,
           String inputType,
           String outputType,
           String locale,
           String audioType,
           String defaultVoiceName,
           String defaultStyle,
           String defaultEffects,
           String outputTypeParams,
           OutputStream output,
           long timeout)
             throws 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.

locale - locale

defaultStyle - defaultStyle

defaultEffects - defaultEffects

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:

IOException - if communication with the server fails

See Also:

getInputDataTypes(), getOutputDataTypes(), getVoices()

process

public void process(String input,
           String inputType,
           String outputType,
           String locale,
           String audioType,
           String defaultVoiceName,
           OutputStream output,
           long timeout)
             throws IOException

Throws:

IOException

_process

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

Throws:

IOException

getAudioFileFormatType

public static AudioFileFormat.Type getAudioFileFormatType(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.

Parameters:

name - name

Returns:

the audio file format type if it is known, or null.

usage

public static void usage()

main

public static void main(String[] args)
                 throws IOException,
                        InterruptedException

Throws:

IOException

InterruptedException