ptolemy.media.javasound

Class LiveSoundJavaSE

java.lang.Object

ptolemy.media.javasound.LiveSoundCommon

ptolemy.media.javasound.LiveSoundJavaSE

All Implemented Interfaces:

LiveSoundInterface

public class LiveSoundJavaSE
extends LiveSoundCommon
implements LiveSoundInterface

Implementation of LiveSoundInterface that in dependent on javax. This actor sequentially outputs audio samples that are captured from the audio input port of the computer. The audio input port typically corresponds to either the microphone input, line-in, or cd audio from the cdrom or dvd drive. It is not possible to select the desired input port under Java. This must be done from the operating system. This actor should be fired often enough to prevent overflow of the internal audio capture buffer. Overflow should be avoided, since it will result in loss of data. Each captured audio sample is converted to a double that may range from -1.0 to 1.0. Thus, the output type of this actor is DoubleToken.

Since:

Ptolemy II 10.0

Version:

$Id$

Author:

Brian K. Vogel and Neil E. Turner and Steve Neuendorffer, Edward A. Lee, Contributor: Dennis Geurts, Ishwinder Singh

Pt.AcceptedRating:

Red (ishwinde)

Pt.ProposedRating:

Red (ishwinde)

Field Summary

Fields inherited from class ptolemy.media.javasound.LiveSoundCommon

_audioInDoubleArray, _bitsPerSample, _bufferSize, _bytesPerSample, _captureData, _captureIsActive, _channels, _liveSoundListeners, _maxSample, _maxSampleReciprocal, _playbackData, _playbackIsActive, _sampleRate, _soundConsumers, _transferSize

Constructor Summary

Constructors

Constructor and Description
LiveSoundJavaSE()

Method Summary

Modifier and Type	Method and Description
void	flushCaptureBuffer(java.lang.Object consumer) Flush queued data from the capture buffer.
void	flushPlaybackBuffer(java.lang.Object producer) Flush queued data from the playback buffer.
int	getBufferSizeCapture() Return the size of the internal capture audio buffer, in samples per channel.
int	getBufferSizePlayback() Return the size of the internal playback audio buffer, in samples per channel.
double[][]	getSamples(java.lang.Object consumer) Return an array of captured audio samples.
void	putSamples(java.lang.Object producer, double[][] samplesArray) Play an array of audio samples.
void	resetCapture() Stop audio capture.
void	resetPlayback() Stop audio playback.
void	setBitsPerSample(int bitsPerSample) Set the number of bits per sample to use for audio capture and playback and notify any registered listeners of the change.
void	setBufferSize(int bufferSize) Request that the internal capture and playback audio buffers have bufferSize samples per channel and notify the registered listeners of the change.
void	setChannels(int channels) Set the number of audio channels to use for capture and playback and notify any registered listeners of the change.
void	setSampleRate(int sampleRate) Set the sample rate to use for audio capture and playback and notify an registered listeners of the change.
void	startCapture(java.lang.Object consumer) Start audio capture.
void	startPlayback(java.lang.Object producer) Start audio playback.
void	stopCapture(java.lang.Object consumer) Stop audio capture.
void	stopPlayback(java.lang.Object producer) Stop audio playback.

Methods inherited from class ptolemy.media.javasound.LiveSoundCommon

_byteArrayToDoubleArray, _doubleArrayToByteArray, _notifyLiveSoundListeners, addLiveSoundListener, getBitsPerSample, getBufferSize, getChannels, getSampleRate, getTransferSize, isCaptureActive, isPlaybackActive, removeLiveSoundListener, setTransferSize

Methods inherited from class java.lang.Object

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

Methods inherited from interface ptolemy.media.javasound.LiveSoundInterface

addLiveSoundListener, getBitsPerSample, getBufferSize, getChannels, getSampleRate, getTransferSize, isCaptureActive, isPlaybackActive, removeLiveSoundListener, setTransferSize

Constructor Detail

LiveSoundJavaSE

public LiveSoundJavaSE()

Method Detail

flushCaptureBuffer

public void flushCaptureBuffer(java.lang.Object consumer)
                        throws java.io.IOException,
                               java.lang.IllegalStateException

Flush queued data from the capture buffer. The flushed data is discarded. It is only legal to flush the capture buffer after startCapture() is called. Flushing an active audio buffer is likely to cause a discontinuity in the data, resulting in a perceptible click.

Note that only the object with the exclusive lock on the capture audio resources is allowed to invoke this method. An exception will occur if the specified object does not have the lock on the playback audio resources.

Specified by:

flushCaptureBuffer in interface LiveSoundInterface

Parameters:

consumer - The object that has an exclusive lock on the capture audio resources.

Throws:

java.lang.IllegalStateException - If audio capture is currently inactive. That is, if startCapture() has not yet been called or if stopCapture() has already been called.

java.io.IOException - If the calling program does not have permission to access the audio capture resources.

flushPlaybackBuffer

public void flushPlaybackBuffer(java.lang.Object producer)
                         throws java.io.IOException,
                                java.lang.IllegalStateException

Flush queued data from the playback buffer. The flushed data is discarded. It is only legal to flush the playback buffer after startPlayback() is called, and only makes sense to do so (but is not required) after putSamples() is called. Flushing an active audio buffer is likely to cause a discontinuity in the data, resulting in a perceptible click.

Note that only the object with the exclusive lock on the playback audio resources is allowed to invoke this method. An exception will occur if the specified object does not have the lock on the playback audio resources.

Specified by:

flushPlaybackBuffer in interface LiveSoundInterface

Parameters:

producer - The object that has an exclusive lock on the playback audio resources.

Throws:

java.lang.IllegalStateException - If audio playback is currently inactive. That is, if startPlayback() has not yet been called or if stopPlayback() has already been called.

java.io.IOException - If the calling program does not have permission to access the audio playback resources.

getBufferSizeCapture

public int getBufferSizeCapture()
                         throws java.lang.IllegalStateException

Return the size of the internal capture audio buffer, in samples per channel.

Specified by:

getBufferSizeCapture in interface LiveSoundInterface

Returns:

The internal buffer size in samples per channel.

Throws:

java.lang.IllegalStateException - If audio capture is inactive.

getBufferSizePlayback

public int getBufferSizePlayback()

Return the size of the internal playback audio buffer, in samples per channel. This may differ from the requested buffer size if the hardware does not support the requested buffer size. If playback has not been started, then will simply return the requested buffer size.

Specified by:

getBufferSizePlayback in interface LiveSoundInterface

Returns:

The internal buffer size in samples per channel.

Throws:

java.lang.IllegalStateException - If audio playback is inactive.

getSamples

public double[][] getSamples(java.lang.Object consumer)
                      throws java.io.IOException,
                             java.lang.IllegalStateException

Return an array of captured audio samples. This method should be repeatedly called to obtain audio data. The returned audio samples will have values in the range [-1, 1], regardless of the audio bit resolution (bits per sample). This method should be called often enough to prevent overflow of the internal audio buffer. If overflow occurs, some audio data will be lost but no exception or other error condition will occur. If the audio data is not yet available, then this method will block until the data is available.

The first index of the returned array represents the channel number (0 for first channel, 1 for second channel). The number of channels is set by the setChannels() method. The second index represents the sample index within a channel. For example, returned array[n][m] contains the (m+1)th sample of the (n+1)th channel. For each channel, n, the length of returned array[n] is equal to the value returned by the getTransferSize() method. The size of the 2nd dimension of the returned array is set by the setTransferSize() method.

Note that only the object with the exclusive lock on the captured audio resources is allowed to invoked this method. An exception will occur if the specified object does not have the lock on the captured audio resources.

Specified by:

getSamples in interface LiveSoundInterface

Parameters:

consumer - The object that has an exclusive lock on the capture audio resources.

Returns:

Two dimensional array of captured audio samples.

Throws:

java.lang.IllegalStateException - If audio capture is currently inactive. That is, if startCapture() has not yet been called or if stopCapture() has already been called.

java.io.IOException - If the calling program does not have permission to access the audio capture resources.

putSamples

public void putSamples(java.lang.Object producer,
                       double[][] samplesArray)
                throws java.io.IOException,
                       java.lang.IllegalStateException

Play an array of audio samples. There will be a delay before the audio data is actually heard, since the audio data in samplesArray is queued to an internal audio buffer. The setBufferSize() method suggests a size for the internal buffer. An upper bound on the latency is given by (bufferSize / sampleRate) seconds. This method should be invoked often enough to prevent underflow of the internal audio buffer. Underflow is undesirable since it will cause audible gaps in audio playback, but no exception or error condition will occur. If the caller attempts to write more data than can be written, this method blocks until the data can be written to the internal audio buffer.

The samples should be in the range (-1, 1). Samples that are outside this range will be hard-clipped so that they fall within this range.

The first index of the specified array represents the channel number (0 for first channel, 1 for second channel, etc.). The number of channels is set by the setChannels() method. The second index represents the sample index within a channel. For example, putSamplesArray[n][m] contains the (m+1)th sample of the (n+1)th channel.

Note that only the object with the exclusive lock on the playback audio resources is allowed to invoke this method. An exception will occur if the specified object does not have the lock on the playback audio resources.

Specified by:

putSamples in interface LiveSoundInterface

Parameters:

producer - The object that has an exclusive lock on the playback audio resources.

samplesArray - A two dimensional array containing the samples to play or write to a file.

Throws:

java.io.IOException - If the calling program does not have permission to access the audio playback resources.

java.lang.IllegalStateException - If audio playback is currently inactive. That is, If startPlayback() has not yet been called or if stopPlayback() has already been called.

resetCapture

public void resetCapture()

Stop audio capture. If audio capture is already inactive, then do nothing. This method should generally not be used, but it may be needed to turn of audio capture for the case where an ill-behaved application exits without calling stopCapture(). The preferred way of stopping audio capture is by calling the stopCapture() method.

Specified by:

resetCapture in interface LiveSoundInterface

resetPlayback

public void resetPlayback()

Stop audio playback. If audio playback is already inactive, then do nothing. This method should generally not be used, but it may be needed to turn of audio playback for the case where an ill-behaved application exits without calling stopPlayback(). The preferred way of stopping audio playback is by calling the stopPlayback() method.

Specified by:

resetPlayback in interface LiveSoundInterface

setBitsPerSample

public void setBitsPerSample(int bitsPerSample)
                      throws java.io.IOException

Set the number of bits per sample to use for audio capture and playback and notify any registered listeners of the change. Allowable values include 8 and 16 bits. If this method is not invoked, then the default value of 16 bits is used.

Specified by:

setBitsPerSample in interface LiveSoundInterface

Parameters:

bitsPerSample - The number of bits per sample.

Throws:

java.io.IOException - If the specified bits per sample is not supported by the audio hardware or by Java.

See Also:

LiveSoundCommon.getBitsPerSample()

setBufferSize

public void setBufferSize(int bufferSize)
                   throws java.io.IOException

Request that the internal capture and playback audio buffers have bufferSize samples per channel and notify the registered listeners of the change. If this method is not invoked, the default value of 1024 is used.

Specified by:

setBufferSize in interface LiveSoundInterface

Parameters:

bufferSize - The suggested size of the internal capture and playback audio buffers, in samples per channel.

Throws:

java.io.IOException - If the specified number of channels is not supported by the audio hardware or by Java.

See Also:

LiveSoundCommon.getBufferSize()

setChannels

public void setChannels(int channels)
                 throws java.io.IOException

Set the number of audio channels to use for capture and playback and notify any registered listeners of the change. Allowable values are 1 (for mono) and 2 (for stereo). If this method is not invoked, the default value of 1 audio channel is used. Note that this method sets the size of the first dimension of the 2-dimensional array used by the putSamples() and getSamples() methods.

Specified by:

setChannels in interface LiveSoundInterface

Parameters:

channels - The number audio channels.

Throws:

java.io.IOException - If the specified number of channels is not supported by the audio hardware or by Java.

See Also:

LiveSoundCommon.getChannels()

setSampleRate

public void setSampleRate(int sampleRate)
                   throws java.io.IOException

Set the sample rate to use for audio capture and playback and notify an registered listeners of the change. Allowable values for this parameter are 8000, 11025, 22050, 44100, and 48000 Hz. If this method is not invoked, then the default value of 8000 Hz is used.

Specified by:

setSampleRate in interface LiveSoundInterface

Parameters:

sampleRate - Sample rate in Hz.

Throws:

java.io.IOException - If the specified sample rate is not supported by the audio hardware or by Java.

See Also:

LiveSoundCommon.getSampleRate()

startCapture

public void startCapture(java.lang.Object consumer)
                  throws java.io.IOException,
                         java.lang.IllegalStateException

Start audio capture. The specified object will be given an exclusive lock on the audio capture resources until the stopCapture() method is called with the same object reference. After this method returns, the getSamples() method may be repeatedly invoked (using the object reference as a parameter) to capture audio.

If audio capture is already active, then an exception will occur.

Specified by:

startCapture in interface LiveSoundInterface

Parameters:

consumer - The object to be given exclusive access to the captured audio resources.

Throws:

java.io.IOException - If another object currently has access to the audio capture resources or if starting the capture or playback throws it.

java.lang.IllegalStateException - If this method is called while audio capture is already active.

startPlayback

public void startPlayback(java.lang.Object producer)
                   throws java.io.IOException,
                          java.lang.IllegalStateException

Start audio playback. The specified object will be given an exclusive lock on the audio playback resources until the stopPlayback() method is called with the same object reference. After this method returns, the putSamples() method may be repeatedly invoked (using the object reference as a parameter) to playback audio.

If audio playback is already active, then an exception will occur.

Specified by:

startPlayback in interface LiveSoundInterface

Parameters:

producer - The object to be given exclusive access to the playback resources.

Throws:

java.io.IOException - If another object currently has access to the audio capture resources or if starting the playback throws it.

java.lang.IllegalStateException - If this method is called while audio playback is already active.

stopCapture

public void stopCapture(java.lang.Object consumer)
                 throws java.io.IOException,
                        java.lang.IllegalStateException

Stop audio capture. If the specified object has the lock on audio capture when this method is invoked, then stop audio capture. Otherwise an exception will occur.

Specified by:

stopCapture in interface LiveSoundInterface

Parameters:

consumer - The object that held on exclusive lock on the captured audio resources when this method was invoked.

Throws:

java.io.IOException - If another object currently has access to the audio capture resources or if stopping the capture throws it.

java.lang.IllegalStateException - If the specified object did not hold an exclusive lock on the captured audio resources when this method was invoked.

stopPlayback

public void stopPlayback(java.lang.Object producer)
                  throws java.io.IOException,
                         java.lang.IllegalStateException

Stop audio playback. If the specified object has the lock on audio playback when this method is invoked, then stop audio playback. Otherwise an exception will occur.

Specified by:

stopPlayback in interface LiveSoundInterface

Parameters:

producer - The object that held on exclusive lock on the playback audio resources when this method was invoked.

Throws:

java.io.IOException - If another object currently has access to the audio capture resources or if stopping the playback throws it.

java.lang.IllegalStateException - If the specified object did not hold an exclusive lock on the playback audio resources when this method was invoked.