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