com.sun.speech.freetts.audio
Interface AudioPlayer

All Known Implementing Classes:

JavaClipAudioPlayer, JavaStreamingAudioPlayer, MultiFile8BitAudioPlayer, MultiFileAudioPlayer, NullAudioPlayer, RawFileAudioPlayer, SingleFileAudioPlayer

public interface AudioPlayer

Provides an interface to the audio system for use by freetts. Audio is presented to the AudioPlayer as byte arrays. Implementations of this AudioPlayer interface will format the data based upon the current audio format (as set by setAudioFormat) and output the data.

The AudioPlayer interface provides a set of potential synchronization points to allow a specific AudioPlayer to batch output in various ways.

These synchronization points are in pairs: reset, drain are used to bracket output of large amounts of audio data. Typically, an implementation will not return from drain until all queued audio has been played (or cancelled).

The methods: begin, end are used to bracket smaller amounts of audio data (typically associated with a single utterance).

Threading Issues

Most of the methods in an AudioPlayer must be called from a single thread. The only exceptions to this rule are pause, resume, cancel, showMetrics, close, getTime, resetTime which can be called from other threads.

Method Summary

void	begin(int size) Starts the output of a set of data.
void	cancel() Cancels all queued output.
void	close() Waits for all audio playback to stop, and closes this AudioPlayer.
boolean	drain() Waits for all queued audio to be played
boolean	end() Signals the end of a set of data.
javax.sound.sampled.AudioFormat	getAudioFormat() Retrieves the audio format for this player
long	getTime() Gets the amount of audio played since the last resetTime
float	getVolume() Returns the current volume.
void	pause() Pauses all audio output on this player.
void	reset() Prepares for another batch of output.
void	resetTime() Resets the audio clock
void	resume() Resumes audio output on this player
void	setAudioFormat(javax.sound.sampled.AudioFormat format) Sets the audio format to use for the next set of outputs.
void	setVolume(float volume) Sets the current volume.
void	showMetrics() Shows metrics for this audio player
void	startFirstSampleTimer() Starts the first sample timer
boolean	write(byte[] audioData) Writes the given bytes to the audio stream
boolean	write(byte[] audioData, int offset, int size) Writes the given bytes to the audio stream

Method Detail

setAudioFormat

public void setAudioFormat(javax.sound.sampled.AudioFormat format)

Sets the audio format to use for the next set of outputs. Since an audio player can be shared by a number of voices, and since voices can have different AudioFormats (sample rates for example), it is necessary to allow clients to dynamically set the audio format for the player.

Parameters:

format - the audio format

getAudioFormat

public javax.sound.sampled.AudioFormat getAudioFormat()

Retrieves the audio format for this player

Returns:

the current audio format

pause

public void pause()

Pauses all audio output on this player. Play can be resumed with a call to resume

resume

public void resume()

Resumes audio output on this player

reset

public void reset()

Prepares for another batch of output. Larger groups of output (such as all output associated with a single FreeTTSSpeakable) should be grouped between a reset/drain pair.

drain

public boolean drain()

Waits for all queued audio to be played

Returns:

true if the audio played to completion; otherwise false if the audio was stopped

begin

public void begin(int size)

Starts the output of a set of data. Audio data for a single utterance should be grouped between begin/end pairs.

Parameters:

size - the size of data in bytes to be output before end is called.

end

public boolean end()

Signals the end of a set of data. Audio data for a single utterance should be groupd between begin/end pairs.

Returns:

true if the audio was output properly, false if the output was cancelled or interrupted.

cancel

public void cancel()

Cancels all queued output. All 'write' calls until the next reset will return false.

close

public void close()

Waits for all audio playback to stop, and closes this AudioPlayer.

getVolume

public float getVolume()

Returns the current volume. The volume is specified as a number between 0.0 and 1.0, where 1.0 is the maximum volume and 0.0 is the minimum volume.

Returns:

the current volume (between 0 and 1)

setVolume

public void setVolume(float volume)

Sets the current volume. The volume is specified as a number between 0.0 and 1.0, where 1.0 is the maximum volume and 0.0 is the minimum volume.

Parameters:

volume - the new volume (between 0 and 1)

getTime

public long getTime()

Gets the amount of audio played since the last resetTime

Returns:

the amount of audio in milliseconds

resetTime

public void resetTime()

Resets the audio clock

startFirstSampleTimer

public void startFirstSampleTimer()

Starts the first sample timer

write

public boolean write(byte[] audioData)

Writes the given bytes to the audio stream

Parameters:

audioData - audio data to write to the device

Returns:

true of the write completed successfully, false if the write was cancelled.

write

public boolean write(byte[] audioData,
                     int offset,
                     int size)

Writes the given bytes to the audio stream

Parameters:

audioData - audio data to write to the device

offset - the offset into the buffer

size - the number of bytes to write.

Returns:

true of the write completed successfully, false if the write was cancelled.

showMetrics

public void showMetrics()

Shows metrics for this audio player