Package 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

Modifier and Type
Method
Description
`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.
`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(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 Details

### setAudioFormat

void setAudioFormat(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

AudioFormat getAudioFormat()
Retrieves the audio format for this player

Returns:
  the current audio format

### pause

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

### resume

void resume()
Resumes audio output on this player

### reset

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

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

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

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 canceled or interrupted.

### cancel

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

### close

void close()
Waits for all audio playback to stop, and closes this AudioPlayer.

### getVolume

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

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

long getTime()
Gets the amount of audio played since the last resetTime

Returns:
  the amount of audio in milliseconds

### resetTime

void resetTime()
Resets the audio clock

### startFirstSampleTimer

void startFirstSampleTimer()
Starts the first sample timer

### write

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

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

void showMetrics()
Shows metrics for this audio player