org.daisy.pipeline.tts

Class TTSEngine

java.lang.Object

org.daisy.pipeline.tts.TTSEngine

public abstract class TTSEngine
extends Object

Classes that inherit from TTSEngine are the ones that deal with adapting external TTS processors (e.g. eSpeak and SAPI) to the Pipeline interface, which is used notably by the TextToPcm threads in the conversion from SSML to mp3. TTSEngines are meant to be allocated for every new session so that the end user can change the TTSEngine's parameters between two Pipeline jobs. Most of the methods of TTSEngine must be thread-safe.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TTSEngine.SynthesisResult

Field Summary

Fields

Modifier and Type	Field and Description
protected TTSService	mProvider

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	TTSEngine(TTSService provider)

Method Summary

Modifier and Type	Method and Description
TTSRegistry.TTSResource	allocateThreadResources() This method must be thread-safe.
protected static AudioInputStream	createAudioStream(AudioFormat format, byte[] data) Create an AudioInputStream from an AudioFormat and the audio data.
protected static AudioInputStream	createAudioStream(AudioFormat format, ByteArrayInputStream data)
protected static AudioInputStream	createAudioStream(InputStream stream) Create a AudioInputStream from a InputStream.
int	expectedMillisecPerWord()
abstract Collection<Voice>	getAvailableVoices() Return the list of available voices for this engine.
int	getOverallPriority() Need not be thread-safe.
TTSService	getProvider()
boolean	handlesMarks()
boolean	handlesPronunciation() Whether the TTS engine handles phoneme elements, which is required for prununciation lexicons to have an effect.
boolean	handlesSpeakingRate() Whether the TTS engine handles prosody elements with a rate attribute.
void	interruptCurrentWork(TTSRegistry.TTSResource resource) Force interruption of the execution of synthesize() when the thread-level interruption is not enough to make synthesize() finish.
void	releaseThreadResources(TTSRegistry.TTSResource resources) This method must be thread-safe.
int	reservedThreadNum()
abstract TTSEngine.SynthesisResult	synthesize(net.sf.saxon.s9api.XdmNode sentence, Voice voice, TTSRegistry.TTSResource threadResources) This method must be thread-safe.
protected String	transformSsmlNodeToString(net.sf.saxon.s9api.XdmNode ssml, URL xslt, Map<String,Object> params) Transform an SSML node to a string using a given XSLT and parameter map If this method is called from synthesize(net.sf.saxon.s9api.XdmNode, org.daisy.pipeline.tts.Voice, org.daisy.pipeline.tts.TTSRegistry.TTSResource), the XSLT should not assume that the SSML node is a root element.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

mProvider

protected TTSService mProvider

Constructor Detail

TTSEngine

protected TTSEngine(TTSService provider)

Parameters:

provider - is the service from which the TTSEngine has been allocated.

Method Detail

getProvider

public TTSService getProvider()

Returns:

the service from which the TTSEngine has been allocated.

synthesize

public abstract TTSEngine.SynthesisResult synthesize(net.sf.saxon.s9api.XdmNode sentence,
                                                     Voice voice,
                                                     TTSRegistry.TTSResource threadResources)
                                              throws TTSService.SynthesisException,
                                                     InterruptedException

This method must be thread-safe. But @param threadResources is here to prevent the service from locking internal resources.

Parameters:

sentence - is the sentence to synthesize, as an SSML node. The node is expected to be an s element with an xml:lang attribute. It is however advised that implementations do not assume this is the case. It can also not be assumed that the node is a root element.

voice - is the voice the synthesizer must use. It is guaranteed to be one of those returned by getAvailableVoices(). This parameter can't be null.

threadResources - is the object returned by allocateThreadResource(). It may contain small persistent buffers, opened file streams, TCP connections and so on. The boolean field 'released' is guaranteed to be false, i.e. the resource provided is always valid and will remain so during the call.

Returns:

a TTSEngine.SynthesisResult object containing the audio data and the mark offsets.

Throws:

TTSService.SynthesisException

InterruptedException

getAvailableVoices

public abstract Collection<Voice> getAvailableVoices()
                                              throws TTSService.SynthesisException,
                                                     InterruptedException

Return the list of available voices for this engine. Voices that come before other voices in the list are prioritized by VoiceManager when there are no other discriminating factors. Need not be thread-safe. This method is called from the main thread.

Throws:

TTSService.SynthesisException

InterruptedException

allocateThreadResources

public TTSRegistry.TTSResource allocateThreadResources()
                                                throws TTSService.SynthesisException,
                                                       InterruptedException

This method must be thread-safe. It allocates new resources (such as TCP connections) unique for each thread. Allocations can be made on-the-fly from different threads. It must not catch InterruptuedExceptions.

Returns:

the resources. Must not be null.

Throws:

TTSService.SynthesisException

InterruptedException

releaseThreadResources

public void releaseThreadResources(TTSRegistry.TTSResource resources)
                            throws TTSService.SynthesisException,
                                   InterruptedException

This method must be thread-safe. Deallocations may be performed from different threads but are always performed in the same thread as the one exploiting @param resources.

Parameters:

resources - is the object returned by allocateThreadResource()

Throws:

TTSService.SynthesisException

InterruptedException

interruptCurrentWork

public void interruptCurrentWork(TTSRegistry.TTSResource resource)

Force interruption of the execution of synthesize() when the thread-level interruption is not enough to make synthesize() finish. Must be thread-safe, although the method must not wait for locks.

Parameters:

resource - is the same as the one provided to synthesize()

getOverallPriority

public int getOverallPriority()

Need not be thread-safe. This method is called from the main thread.

reservedThreadNum

public int reservedThreadNum()

Returns:

the number of text-to-pcm threads reserved for this TTS processor. Different values than zero make only sense if the TTS speed is limited by the number of opened resources rather than by the number of cores. In such cases, we want to maximize the time spent on using the TTS resources by avoiding using threads for something else (e.g. audio encoding or calling other TTS processors).

expectedMillisecPerWord

public int expectedMillisecPerWord()

Returns:

the average number of milliseconds the TTS processors is expected to spend to process a single word on a single CPU core. It doesn't need to be accurate. It is used for tuning the timeouts.

handlesMarks

public boolean handlesMarks()

Returns:

true if the TTS engine handles SSML marks, false otherwise. Must be thread-safe.

handlesSpeakingRate

public boolean handlesSpeakingRate()

Whether the TTS engine handles prosody elements with a rate attribute. If this method returns true, the engine is assumed to support all of the following values:

• "x-slow", "slow", "medium", "fast", "x-fast", or "default".
• A non-negative percentage, which acts as a multiplier of the default rate.
• A number that represents speaking rate in words per minute. Note that this does not come from the SSML specification, but it is a value of the CSS speech-rate property.

All values, except for absolute numbers, are relative to the default rate, which is determined by the org.daisy.pipeline.tts.speech-rate property.

handlesPronunciation

public boolean handlesPronunciation()

Whether the TTS engine handles phoneme elements, which is required for prununciation lexicons to have an effect. This method does not say anyhing about which pronunciation alphabets are supported, which phonemes, and for which languages.

transformSsmlNodeToString

protected String transformSsmlNodeToString(net.sf.saxon.s9api.XdmNode ssml,
                                           URL xslt,
                                           Map<String,Object> params)
                                    throws IOException,
                                           net.sf.saxon.s9api.SaxonApiException

Transform an SSML node to a string using a given XSLT and parameter map If this method is called from synthesize(net.sf.saxon.s9api.XdmNode, org.daisy.pipeline.tts.Voice, org.daisy.pipeline.tts.TTSRegistry.TTSResource), the XSLT should not assume that the SSML node is a root element.

Throws:

IOException

net.sf.saxon.s9api.SaxonApiException

createAudioStream

protected static AudioInputStream createAudioStream(AudioFormat format,
                                                    byte[] data)

Create an AudioInputStream from an AudioFormat and the audio data.

createAudioStream

protected static AudioInputStream createAudioStream(AudioFormat format,
                                                    ByteArrayInputStream data)

createAudioStream

protected static AudioInputStream createAudioStream(InputStream stream)
                                             throws UnsupportedAudioFileException,
                                                    IOException

Create a AudioInputStream from a InputStream. This is to work around a bug in AudioSystem which may return AudioInputStream with a wrong AudioInputStream.getFrameLength().

Throws:

UnsupportedAudioFileException

IOException