Package com.cloudgarden.audio

This package provides classes originally intended for redirecting output from a Synthesizer to a File, a SourceDataLine, a remote client or a custom AudioSink, and providing audio data to a Recognizer from a File, TargetDataLine, remote client or a custom AudioSource.

See:
Description

Interface Summary

AudioConnector	An interface to identify AudioObjects which implement both an AudioSink and an AudioSource.
AudioConverter	An interface to identify AudioObjects which implement both an AudioSink and an AudioSource and have different input and output formats
AudioInputServerI	Remote interface for obtaining audio data from a client.
AudioObject	Basic interface which is extended by AudioSource and AudioSink.
AudioOutputServerI	Remote interface for allowing a client to obtain audio data from a server.
AudioServerI	Remote interface for allowing a client to connect to and disconnect from a server, and to get/set it's AudioFormat.
AudioSink	An interface representing a class which accepts audio data, and which can be connected to an AudioSource.
AudioSource	An interface representing a class which generates audio data, and which can be connected to an AudioSink.
ClientListener	Used by a server to receive notices that a client has attached or removed itself to or from an AudioSocketSource, and also to be informed of the bytes transferred to or from a specific client.
ServerListener	Used by a client to receive notices that the server has closed down.
TransferListener	Used to detect when byte data is being transferred and to allow it to be analysed (eg, determine the signal level).

Class Summary

AudioClientSink	This class provides an AudioSink wrapper around a handle to a remote AudioServerSource RMI object.
AudioClientSource	This class provides an AudioSource wrapper around a handle to a remote AudioOutputSocket.
AudioFileSink	AudioSink wrapper for a File, enabling audio data to be written to a File.
AudioFileSource	AudioSource wrapper for a File, enabling audio data to be read from a File.
AudioFormatConverter	Basic audio format converter, which is guaranteed to convert between any two javax.sound.sampled.AudioFormats - this is unlike the javax.sound.sampled.AudioSystem conversion, which sometimes can't provide the needed conversions.
AudioLineSink	AudioSink wrapper for a SourceDataLine.
AudioLineSource	AudioSource wrapper for a TargetDataLine.
AudioMediaFormatConverter	Basic audio format converter, which is guaranteed to convert between any two AudioFormats provided both are 16-bit - this is unlike the javax.sound.sampled.AudioSystem conversion, which sometimes can't provide the needed conversions.
AudioMediaLineSink	AudioSink wrapper for a javax.media playback device, enabling audio data to be played to speakers etc (avoiding the bugs encountered by the javax.sound.sampled playback devices when a TargetDataLine is running at the same time).
AudioMediaLineSource	AudioSource wrapper for a javax.media capture device, enabling audio data to be captured from a microphone etc (avoiding the bugs encountered by the javax.sound.sampled capture devices when a SourceDataLine is running at the same time).
AudioMediaURLSink	Writes audio data to a URL using the JMF packages, with content type defined by one of the FileTypeDescriptor String fields, eg MPEG_AUDIO, QUICKTIME etc
AudioMediaURLSource	AudioSource wrapper for a URL, enabling audio data to be read from a URL.
AudioPipe	A class which has an internal buffer, which it uses to store data read from it's source (set using the setSource method) before being sent to it's sink (set using the setSink method).
AudioServer	This class allows an AudioSink (eg a Recognizer's CGAudioManager) to receive audio input from a remote machine.
AudioServerSink	This class sends audio output to a remote (client) machine.
AudioServerSource	This class receives audio input from a remote (client) machine.
AudioSplitter	A class designed to allow a single AudioSource to supply the same audio data to multiple AudioSinks (useful, say, to broadcast speech to multiple remote clients).
AudioStreamSource	AudioSource wrapper for an AudioInputStream
CGDataSink	This class should only be created by the JSAPI implementation - a new instance is created and returned by a call to CGAudioManager.getDataSink
CGPullBufferDataSource	This class should only be created by the JSAPI implementation - a new instance is created and returned by a call to CGAudioManager.getDataSource
ClientAdapter	Used to recieve notices that a client has attached or removed itself to or from an AudioSocketSource.
ClientEvent	Class to hold information when a ClientListener signals an event.
DefaultAudioClient	The base class which connects to an AudioServerI and handles communication of AudioFormat information with the server.
DefaultAudioConnector
DefaultAudioConverter
DefaultAudioObject	The base class which implements the functionality of a generic AudioObject.
DefaultAudioSink	The base class which implements all the functionality of a generic AudioSink except the write method.
DefaultAudioSource	The base class which implements all the functionality of a generic AudioSource except the read method.
TransferEvent	Class to hold information when a TransferListener signals an event.

Package com.cloudgarden.audio Description

This package provides classes originally intended for redirecting output from a Synthesizer to a File, a SourceDataLine, a remote client or a custom AudioSink, and providing audio data to a Recognizer from a File, TargetDataLine, remote client or a custom AudioSource. The package idoes not depend on the speech packages, however, so can be used separately. Additional classes provide conversion between Java Sound AudioFormats and also JMF file formats like MPEG and GSM. This allows compressed audio data to be transmitted across a network.

AudioSources and AudioSinks
The basic interfaces are AudioSink and AudioSource, which can be connected to each other and provide an easy way to direct audio data from one object to another. An AudioSource provides digital audio data (obtained from say a microphone or a file) to other Java classes, and an AudioSink takes audio data from Java classes (and disposes of it to say a speaker or a file).

AudioSources and AudioSinks have an AudioFormat and a content type associated with them, and these properties are propogated downstream to any AudioSources/Sinks they are connected to. If there is a discontinuity in AudioFormats (say, an AudioFileSource has a 16kHz format and a CGAudioManager has an unchangable AudioFormat of 11.05kHz) an AudioFormatConverter must be used to bridge the gap, or an exception will be thrown.

AudioSources can push data to any AudioSink connected to them by the startSending method. This method should start a Thread which reads data from the AudioSource and writes it to the AudioSink, blocking if no data is available and stopping when a block of length END_OF_DATA is read from the source or the source's stopSending method is called. The startSending method call is also propogated - if an AudioSink connected to the AudioSource also implements the AudioSource interface (eg, is an AudioPipe) then it's startSending method will be invoked when the up-stream AudioSource's startSending method is called. The same applies to the stopSending method.

The propagation of AudioFormat, contentType and start/stopSending method calls allows for simple setup and operation of AudioSource/Sink chains.

TransferListeners can be attached to any AudioSource/Sink to monitor the data being transferred, and even to modify the data.

DefaultAudioSource/Sink
These abstract classes implement the basic functionality of AudioSource and AudioSink. Most of the other classes in the package extend these classes and implement the read or write methods.

AudioLineSource/Sink
These classes allow audio data to be read from a TargetDataLine or written to a SourceDataLine. The constructors can take either an AudioFormat or the parameters for an AudioFormat (creating a DataLine internally), a DataLine or an AudioSource/Sink (from which the AudioFormat used to construct the DataLine is taken).

AudioFileSource/Sink
These classes allow audio data to be read from or written to an audio File. The constructors for an AudioFileSink take a File and AudioFileFormat.Type, and either an AudioFormat or an AudioSource (from which the AudioFormat is taken).

AudioStreamSource
This is a simple wrapper that allows audio data to be read from an AudioInputStream.

AudioServerSource/Sink and AudioClientSource/Sink
These classes can be used for audio data transmission across a network. An AudioServer is an RMI object whose methods are invoked by an AudioClient (usually, the AudioServer resides on the machine with the speech engines and the AudioClient on a remote machine without a speech engine which either sends or receives audio data to/from the AudioServer). To send data to the server, an AudioClientSink/AudioServerSource pairing is used, and to receive data from a server, an AudioServerSink/AudioClientSource pairing is used. eg:

AudioLineSource -> AudioClientSink -(network)-> AudioServerSource -> AudioLineSink

or

AudioLineSource -> AudioServerSink -(network)-> AudioClientSource -> AudioLineSink

ClientListeners can be attached to an AudioServer to monitor the addition/removal of client connections and to monitor the data being transferred to each client (though at present, only one client should be connected to each server).

ServerListeners can be attached to AudioClients to receive notification when a server is closed.

AudioConnectors - AudioPipe
The AudioConnector is an interface that extends both the AudioSink and AudioSource interfaces. The only direct implementation of this interface in this package is the AudioPipe. This has an internal buffer and is useful in situations where audio data needs to be stored for short time periods.

AudioConverters - AudioFormatConverter and AudioMediaFormatConverter
The AudioConverter interface extends AudioConnector and allows for an incoming AudioFormat which may be different from the outgoing AudioFormat. The AudioMediaFormatConverter uses a JMF FileTypeDescriptor to specify conversion from a Java Sound AudioFormat to a JMF AudioFormat or vice-versa. Raw audio data may thus be converted into a compressed format, such as GSM, and transmitted across a network, like this:

AudioLineSource -> AudioMediaFormatConverter (to GSM) -> AudioClientSink -(network)->

        -(network)-> AudioServerSource -> AudioMediaFormatConverter (to PCM) -> AudioLineSink

AudioSplitter
The AudioSplitter allows audio data from a single AudioSource to be sent to multiple AudioSinks. The startSending() thread will read from the source and write to each of the sinks in turn, blocking if a sink is unable to receive data. For this reason it is often useful to have AudioPipes as the sinks attached to an AudioSplitter to buffer the outgoing data and allow the smooth flow of data. eg

AudioLineSource -> AudioSplitter -> AudioPipe -> AudioFileSink

                                 -> AudioPipe -> AudioLineSink

CGAudioManager
Though it is not in this package, the com.cloudgarden.speech.CGAudioManager class implements both the AudioSink and AudioSource interfaces. The AudioSink interface allows data to be sent to a Recognizer, while the AudioSource interface allows data to be read from a Synthesizer. If an AudioSink method is called on a CGAudioManager obtained from a Synthesizer, or an AudioSource method called on a CGAudioManager obtained from a Recognizer, an exception will be thrown.