com.cloudgarden.speech
Class CGAudioManager

java.lang.Object
  |
  +--com.cloudgarden.speech.CGAudioManager

All Implemented Interfaces:

AudioManager, AudioObject, AudioSink, AudioSource

public class CGAudioManager

extends java.lang.Object

implements AudioManager, AudioSource, AudioSink

In addition to the functions offered by the javax.speech.AudioManager class, this class provides several methods for redirecting audio input/output. It allows the input to a Recognizer to come from an AudioSource, and Synthesizer output to be sent to an AudioSink.

The setSource method ensures that input to the recognizer comes always from a single well-defined source at any time. Likewise, the setSink method defines a single AudioSink to receive output from a Synthesizer.

The getDataSource and getDataSink methods provide JMF DataSource and DataSink objects.

Fields inherited from interface com.cloudgarden.audio.AudioObject

END_OF_DATA

Method Summary

void	addAudioListener(AudioListener listener)
void	addTransferListener(TransferListener listener) Adds a TransferListener to receive notification when data is passed to or from this AudioObject
void	bytesTransferred(byte[] data, int offset, int numBytes, int direction)
boolean	canSetAudioFormat() Used to test whether the AudioFormat of the Synthesizer or Recognizer can be set using the setAudioFormat method.
void	closeInput() Closes the input stream - and allows the CGAudioManager.drain() method (as well as the drain method of any sinks/sources connected to it) to exit.
void	closeOutput() Closes the output stream - causes the read method to return END_OF_DATA when the current synthesized speech has finished.
void	closeOutputFile() Closes the wave audio file opened in a preceding setOutputFile call.
void	drain() Blocks until END_OF_DATA is written to or read from this AudioObject.
javax.sound.sampled.AudioFormat	getAudioFormat() Used to obtain the AudioFormat of the Synthesizer or Recognizer from which this CGAudioManager was obtained.
java.lang.String	getContentType()
javax.media.DataSink	getDataSink() Returns a javax.media.DataSink object which allows audio data to be sent to a Recognizer using the JMF.
javax.media.protocol.DataSource	getDataSource() Returns a javax.media.protocol.DataSource object which allows audio data from a Synthesizer to be manipulated using the JMF.
AudioSink	getSink() Returns the AudioSink set using setSink
AudioSource	getSource() Returns the AudioSource set by setSource
boolean	isAudioDeviceValid()
boolean	isPaused()
boolean	isSending() Returns true if the thread started by the startSending method is still writing data to the AudioSink.
boolean	isWaiting() Returns true if no data has yet been written or read from this AudioObject
int	read(byte[] data, int len) Convenience method - should call read(data, 0, len)
int	read(byte[] data, int offset, int len) Used to read data from this source - called by the AudioSink which this source is connected to (if its startGetting method is used) so need not be called explicitly by an application.
void	removeAudioListener(AudioListener listener)
void	removeTransferListener(TransferListener listener)
void	setAudioFormat(javax.sound.sampled.AudioFormat format) Sets the AudioFormat for this AudioObject.
void	setBufferSize(int size)
void	setContentType(java.lang.String contentType) Does nothing, since the content type is fixed at RAW
void	setDefaultInput() Sets the input to a Recognizer to come from the default input device (usually the microphone on the local machine).
void	setDefaultOutput() Redirects output to the default output.
void	setInputFile(java.lang.String fileName) Deprecated. Use either the setSource or getDataSink method
void	setOutputFile(java.lang.String fileName, int freq, int bits) Deprecated. Use either the setSink or getDataSource method
void	setPaused(boolean paused) If paused is true, writing or reading data to or from this AudioObject will block until setPaused(false) is called.
void	setSink(AudioSink sink) Sets the sink for this source - this method should also call the setSource method on the sink object (making sure to avaoid an endless loop) to ensure that source and sink are connected to each other (and not to different sinks/sources).
void	setSource(AudioSource source) Sets the source for this sink - this method should also call the setSink method on the source object (while avoiding an endless loop) to ensure that sink and source are connected to each other (and not to different sinks/sources).
void	startSending() This method should start a thread which repeatedly writes data to the AudioSink object which this object is connected to, until it writes data with length END_OF_DATA, or until the stopSending method is called.
void	stopSending()
int	write(byte[] data, int len) Convenience method - should call write(data, 0, len)
int	write(byte[] data, int offset, int len) Used to write data to this sink - called by the AudioSource which this sink is connected to (if its startSending method is used) so need not be called explicitly by an application.

Methods inherited from class java.lang.Object

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

Method Detail

addAudioListener

public void addAudioListener(AudioListener listener)

Specified by:

addAudioListener in interface AudioManager

removeAudioListener

public void removeAudioListener(AudioListener listener)

Specified by:

removeAudioListener in interface AudioManager

addTransferListener

public void addTransferListener(TransferListener listener)

Description copied from interface: AudioObject

Adds a TransferListener to receive notification when data is passed to or from this AudioObject

Specified by:

addTransferListener in interface AudioObject

removeTransferListener

public void removeTransferListener(TransferListener listener)

Specified by:

removeTransferListener in interface AudioObject

Following copied from interface: com.cloudgarden.audio.AudioObject

See Also:

addTransferListener

bytesTransferred

public void bytesTransferred(byte[] data,
                             int offset,
                             int numBytes,
                             int direction)

getAudioFormat

public javax.sound.sampled.AudioFormat getAudioFormat()

Used to obtain the AudioFormat of the Synthesizer or Recognizer from which this CGAudioManager was obtained.

Specified by:

getAudioFormat in interface AudioObject

Returns:

the AudioFormat of the Synthesizer or Recognizer from which this CGAudioManager was obtained.

canSetAudioFormat

public boolean canSetAudioFormat()

Used to test whether the AudioFormat of the Synthesizer or Recognizer can be set using the setAudioFormat method. For example, the AudioFormat of SAPI4 synthesizers cannot be set and any Line or Stream passed in to the setOutput method should first have it's AudioFormat set to the value obtained from the getAudioFormat method.

Specified by:

canSetAudioFormat in interface AudioObject

Returns:

true if the AudioFormat of the Synthesizer or Recognizer can be set via the setAudioFormat method.

setAudioFormat

public void setAudioFormat(javax.sound.sampled.AudioFormat format)
                    throws java.io.IOException

Description copied from interface: AudioObject

Sets the AudioFormat for this AudioObject. If this object is connected to an AudioSource or an AudioSink, then the source/sink's AudioFormat is set equal to that of this AudioObject. Note: if the sink is an AudioConverter then the setIncomingAudioFormat method is called instead of setAudioFormat.

This ensures that the AudioFormat is uniform along a set of connected AudioObjects until the format is changed by an AudioConverter.

Specified by:

setAudioFormat in interface AudioObject

Following copied from interface: com.cloudgarden.audio.AudioObject

Throws:

java.io.IOException - if unable to set the AudioFormat for any reason (eg. if canSetAudioFormat returns false and setAudioFormat is used to try to change the AudioFormat).

See Also:

AudioObject.getAudioFormat()

isAudioDeviceValid

public boolean isAudioDeviceValid()

setPaused

public void setPaused(boolean paused)

Description copied from interface: AudioObject

If paused is true, writing or reading data to or from this AudioObject will block until setPaused(false) is called.

Specified by:

setPaused in interface AudioObject

setInputFile

public void setInputFile(java.lang.String fileName)
                  throws AudioException,
                         EngineException,
                         EngineStateError,
                         java.io.IOException

Deprecated. Use either the setSource or getDataSink method

setDefaultInput

public void setDefaultInput()

Sets the input to a Recognizer to come from the default input device (usually the microphone on the local machine).

closeInput

public void closeInput()

Closes the input stream - and allows the CGAudioManager.drain() method (as well as the drain method of any sinks/sources connected to it) to exit.

setOutputFile

public void setOutputFile(java.lang.String fileName,
                          int freq,
                          int bits)
                   throws AudioException,
                          EngineException,
                          EngineStateError,
                          java.io.IOException

Deprecated. Use either the setSink or getDataSource method

Note: This method has been succeeded by the setSink method and AudioFileSink class, but may be used if for some reason that approach fails.

Allows the Synthesizer's output to be saved directly to a wave audio file. This method can be called at any time after the Synthesizer has been allocated. The closeOutputFile method should be called after the speech has finished. In this way speech may be piped to one file then another. The file name must end in .wav or .wave, the "bits" parameter must equal 8 or 16 and the "frequency" must equal 11 or 22 (kHz).

Note: Setting output to a file using this method changes the behaviour of the Synthesizer's "speak" methods from the "normal" case when speech is output asynchronously to an audio device.

After output has been set to a file using this method, the "speek" methods will write speech synchronously to the file, and no SpeechEvents will be sent during or after writing speech to the file. Restoring output to the audio device will cause the "speek" methods to execute asynchronously again.

To reset audio output to the default audio device (usually the speakers), this method should be called with a null fileName parameter.

This method operates as defined only when a Synthesizer is in the ALLOCATED state. The call blocks if the Synthesizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown for synthesizers in the DEALLOCATED or DEALLOCATING_RESOURCES states.

Parameters:

fileName - file name to save audio to - must end in ".wav" or ".wave"

bits - audio resolution - 8 or 16 bits

frequency - audio frequency in kHz - must be 11 or 22

Throws:

AudioException - if either bits or frequency or fileName is invalid.

EngineException - if not called on a Synthesizer object

EngineStateError - if called for a synthesizer in the DEALLOCATED or DEALLOCATING_RESOURCES states

java.io.IOException - if the operation failed in any way when trying to open the output file.

See Also:

closeOutputFile()

closeOutputFile

public void closeOutputFile()
                     throws EngineException,
                            java.io.IOException

Closes the wave audio file opened in a preceding setOutputFile call. This method should be called before any subsequent calls to setOutputFile.

Throws:

EngineException - if not called on a Synthesizer object

EngineStateError - if called for a synthesizer in the DEALLOCATED or DEALLOCATING_RESOURCES states

java.io.IOException - if the operation failed in any way when trying to close the output file.

See Also:

setOutputFile(String, int, int)

setDefaultOutput

public void setDefaultOutput()
                      throws AudioException,
                             EngineException,
                             EngineStateError,
                             java.io.IOException

Redirects output to the default output.

closeOutput

public void closeOutput()

Closes the output stream - causes the read method to return END_OF_DATA when the current synthesized speech has finished.

getDataSink

public javax.media.DataSink getDataSink()
                                 throws EngineException,
                                        java.io.IOException

Returns a javax.media.DataSink object which allows audio data to be sent to a Recognizer using the JMF. Note that the DataSink object cannot be obtained from the Manager in the method Manager.createDataSink because this DataSink is not registered with the Manager as handling a specific type of media. It can, however, be used in the same way as any other DataSink - see the examples.dictation.DictationFromMPEGFile example for a demonstration of recognizing speech from an MP3 file.

The Recognizer can use only a single AudioSource or a single DataSink at any one time, and so a call to the getDataSink method overrides any previous call to the getDataSink or setSource methods.

This method should only be called after a Recognizer has been allocated but before the Recognizer.requestFocus method is called - see the examples.recognition.DictationFromMPEGFile sample code.

Once the DataSink is finished being used, closeInput() should be called.

Throws:

EngineException - if not called on a Recognizer object

getDataSource

public javax.media.protocol.DataSource getDataSource()
                                              throws EngineException,
                                                     java.io.IOException

Returns a javax.media.protocol.DataSource object which allows audio data from a Synthesizer to be manipulated using the JMF. Note that the DataSource object cannot be obtained from the Manager in the method Manager.createDataSource because this DataSource is not registered with the Manager as handling a specific type of media. It can, however, be used in the same way as any other DataSource - see the examples.synthesis.SpeakToMPEGFile example for a demonstration of writing speech to an MP3 file.

The Synthesizer can use only a single AudioSink or a single DataSource at any one time, and so a call to the getDataSource method overrides any previous call to the getDataSource or setSink methods.

Once the DataSource is finished being used, closeOutput() should be called.

Throws:

EngineException - if not called on a Synthesizer object

setSink

public void setSink(AudioSink sink)
             throws java.io.IOException

Description copied from interface: AudioSource

Sets the sink for this source - this method should also call the setSource method on the sink object (making sure to avaoid an endless loop) to ensure that source and sink are connected to each other (and not to different sinks/sources). Also ensures continuity of the AudioFormat and ContentType (as described below).

If the sink's AudioFormat is null or the sink's format differs from this AudioSource's format, then the sink's format is set equal to that of this AudioSource.

If the sink's AudioFormat is not null and this AudioSource's format is null then this AudioSource's format is set equal to the sink's.

The same is done for the ContentType as described above for the AudioFormat.

Note: if the sink is an AudioConverter then the get/setIncomingAudioFormat method is called instead of get/setAudioFormat.

Specified by:

setSink in interface AudioSource

Following copied from interface: com.cloudgarden.audio.AudioSource

See Also:

AudioSource.getSink()

isSending

public boolean isSending()

Description copied from interface: AudioSource

Returns true if the thread started by the startSending method is still writing data to the AudioSink.

Specified by:

isSending in interface AudioSource

Following copied from interface: com.cloudgarden.audio.AudioSource

See Also:

AudioSource.startSending()

setSource

public void setSource(AudioSource source)
               throws java.io.IOException

Description copied from interface: AudioSink

Sets the source for this sink - this method should also call the setSink method on the source object (while avoiding an endless loop) to ensure that sink and source are connected to each other (and not to different sinks/sources). Also ensures continuity of the AudioFormat and ContentType (as described below).

If the source's AudioFormat is null or the source's format differs from this AudioSink's format, then the source's format is set equal to that of this AudioSink.

If the source's AudioFormat is not null and this AudioSink's format is null then this AudioSink's format is set equal to the source's.

The same is done for the ContentType as described above for the AudioFormat.

Specified by:

setSource in interface AudioSink

Following copied from interface: com.cloudgarden.audio.AudioSink

See Also:

AudioSink.getSource()

read

public int read(byte[] data,
                int len)
         throws java.io.IOException

Description copied from interface: AudioSource

Convenience method - should call read(data, 0, len)

Specified by:

read in interface AudioSource

read

public int read(byte[] data,
                int offset,
                int len)
         throws java.io.IOException

Description copied from interface: AudioSource

Used to read data from this source - called by the AudioSink which this source is connected to (if its startGetting method is used) so need not be called explicitly by an application. Blocks if this source is paused. Returns the number of bytes read, or END_OF_DATA if all the available data has been read - eg if the end of a file has been reached, or if the stopSending() method has been called.

Specified by:

read in interface AudioSource

Following copied from interface: com.cloudgarden.audio.AudioSource

See Also:

AudioSource.setSink(com.cloudgarden.audio.AudioSink), AudioSink#startGetting, AudioObject.setPaused(boolean)

write

public int write(byte[] data,
                 int len)
          throws java.io.IOException

Description copied from interface: AudioSink

Convenience method - should call write(data, 0, len)

Specified by:

write in interface AudioSink

write

public int write(byte[] data,
                 int offset,
                 int len)
          throws java.io.IOException

Description copied from interface: AudioSink

Used to write data to this sink - called by the AudioSource which this sink is connected to (if its startSending method is used) so need not be called explicitly by an application. Blocks if this sink is paused.

Specified by:

write in interface AudioSink

Following copied from interface: com.cloudgarden.audio.AudioSink

See Also:

AudioSink.setSource(com.cloudgarden.audio.AudioSource), AudioSource.startSending(), AudioObject.setPaused(boolean)

setBufferSize

public void setBufferSize(int size)

startSending

public void startSending()
                  throws java.io.IOException

Description copied from interface: AudioSource

This method should start a thread which repeatedly writes data to the AudioSink object which this object is connected to, until it writes data with length END_OF_DATA, or until the stopSending method is called. If an error occurs while the thread is sending data it could be detected by calling the drain method.

Specified by:

startSending in interface AudioSource

Following copied from interface: com.cloudgarden.audio.AudioSource

Throws:

an - IOException if the source is unable to start sending data - for example, if an audio file is unable to be opened to supply the data to be sent.

See Also:

AudioSource.setSink(com.cloudgarden.audio.AudioSink), AudioObject.drain()

stopSending

public void stopSending()

Specified by:

stopSending in interface AudioSource

Following copied from interface: com.cloudgarden.audio.AudioSource

See Also:

AudioSource.startSending()

drain

public void drain()
           throws java.io.IOException

Description copied from interface: AudioObject

Blocks until END_OF_DATA is written to or read from this AudioObject. For sinks such as an AudioLineSink, or sources such as AudioLineSource should also drain the line.

Specified by:

drain in interface AudioObject

isWaiting

public boolean isWaiting()

Description copied from interface: AudioObject

Returns true if no data has yet been written or read from this AudioObject

Specified by:

isWaiting in interface AudioObject

getSource

public AudioSource getSource()

Description copied from interface: AudioSink

Returns the AudioSource set by setSource

Specified by:

getSource in interface AudioSink

Following copied from interface: com.cloudgarden.audio.AudioSink

See Also:

AudioSink.setSource(com.cloudgarden.audio.AudioSource)

getSink

public AudioSink getSink()

Description copied from interface: AudioSource

Returns the AudioSink set using setSink

Specified by:

getSink in interface AudioSource

Following copied from interface: com.cloudgarden.audio.AudioSource

See Also:

AudioSource.setSink(com.cloudgarden.audio.AudioSink)

isPaused

public boolean isPaused()

Specified by:

isPaused in interface AudioObject

getContentType

public java.lang.String getContentType()

Specified by:

getContentType in interface AudioObject

Following copied from interface: com.cloudgarden.audio.AudioObject

See Also:

setContentType

setContentType

public void setContentType(java.lang.String contentType)

Does nothing, since the content type is fixed at RAW

Specified by:

setContentType in interface AudioObject