All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class Audio.SoundBite

java.lang.Object
   |
   +----Audio.SoundBite

public class SoundBite

extends Object

See Also:

SampleRate

left

These data buffers hold the raw (PCM) audio data.

right

SoundBite(boolean, boolean, SampleRate, int)

Create an instance of SoundBite using the settings provided.

SoundBite(String)

Create an instance of SoundBite and load the audio data from the filename provided (.WAV format is assumed).

clear()

Clears the audio data buffers left[], right[].

dispose()

Although the resources used by an instance of SoundBite will be freed once it is garbage collected, in many situations the user may want that reclamation of resources to be expedited.

finalize()

This is usually called by the garbage collector.

getIs16bits()

getIsPlaying()

returns true if playback is currently taking place using this instance of SoundBite.

getIsRecording()

returns true if recording is currently taking place using this instance of SoundBite.

getIsStereo()

getMaxNumSamples()

This is the maximum size for audio data buffers left[], right[].

getMaxSampleRange()

getMidSampleRange()

getMinSampleRange()

getNumSamples()

This is the currently set size for audio data buffers left[], right[].

getSampleRange()

getSamplesPerSec()

playStart()

Starts the playback of the audio data in the data buffers left[], right[] in a separate thread.

playStop()

Force playback to stop.

playWaitFor()

Wait until no playback is being done using this instance of SoundBite.

recordStart()

Starts recording audio data in a separate thread.

recordStop()

Force recording to stop.

recordWaitFor()

Wait until no recording is being done using this instance of SoundBite.

recordWaitForGet()

Wait until no recording is being done using this instance of SoundBite.

save(String)

Save the contents of the audio buffers left[], right[] to a .WAV file.

setNumSamples(int)

Use this to set the number of samples in the audio buffers left[], right[].

 public short left[]

These data buffers hold the raw (PCM) audio data. They are allocated by the constructors. Once allocated the maximum size for audio buffers is fixed.

The user can examine or change the contents of left[], right[] directly and can set the size using setNumSamples()

Since short is signed 16-bit, the same arrays can hold either 8-bit or 16-bit audio. For mono audio, left[] and right[] are identical.

Range of values for left[], right[]

 8-bit data	0..255 (zero = 128, sample range = 256)
 16-bit data	-32,768..32,767 (zero = 0, sample range = 65536)
 

See Also:

setNumSamples, getSampleRange, getMinSampleRange, getMidSampleRange, getMaxSampleRange

 public short right[]

 public SoundBite(String filename) throws SoundBiteReadFileException, SoundBiteAllocBuffersException

Create an instance of SoundBite and load the audio data from the filename provided (.WAV format is assumed). All settings (stereo, mono, 16-bit, 8-bit) as well as the maximum size for the buffers (see getMaxNumSamples()) is set using the information provided in the .WAV file.

The audio buffers left[], right[] are allocated to have the same maximum size (see getMaxNumSamples()) as the file data.

Example:

	try {
		SoundBite	s = new SoundBite("file.wav");
		...
		s.dispose();
	} catch (SoundBiteException e) {
		...
	}
 

 public SoundBite(boolean is_16bits,
                  boolean is_stereo,
                  SampleRate samplespersec,
                  int maxnumsamples) throws SoundBiteBadMaxNumSamplesException, SoundBiteAllocBuffersException

Create an instance of SoundBite using the settings provided. The audio buffers left[], right[] are allocated to the required size ("maxnumsamples"). The audio buffers are initially empty (i.e. getNumSamples() should return 0).

Example:

	try {
		int	numseconds = 5;
		SoundBite	s = new SoundBite(true, true, SampleRate.R_11025, numseconds * SampleRate.R_11025.toInt());
		...
		s.dispose();
	} catch (SoundBiteException e) {
		...
	}
 

 public boolean getIs16bits()

 public boolean getIsStereo()

 public int getSamplesPerSec()

 public int getMaxNumSamples()

This is the maximum size for audio data buffers left[], right[]. The maximum size for the buffers is set by the constructors.

 public int getNumSamples()

This is the currently set size for audio data buffers left[], right[]. This should be less than getMaxNumSamples().

 public int getSampleRange()

 public int getMinSampleRange()

 public int getMidSampleRange()

 public int getMaxSampleRange()

 public void recordWaitFor()

Wait until no recording is being done using this instance of SoundBite.

 public void playWaitFor()

Wait until no playback is being done using this instance of SoundBite.

 public boolean getIsRecording()

returns true if recording is currently taking place using this instance of SoundBite.

 public boolean getIsPlaying()

returns true if playback is currently taking place using this instance of SoundBite.

 public synchronized void save(String filename) throws SoundBiteSaveDiskFullException, SoundBiteSaveOtherException

Save the contents of the audio buffers left[], right[] to a .WAV file. The number of samples saved is equal to getNumSamples().

Example:

	try {
		// construct
		...
		s.save("output.wav");
		...
	} catch (SoundBiteException e) {
		...
	}
 

 public synchronized void dispose()

Although the resources used by an instance of SoundBite will be freed once it is garbage collected, in many situations the user may want that reclamation of resources to be expedited.

It is suggested that this method should be called once the user has finished using an instance of SoundBite. Once this method has been called the user should assume that instance is no longer available.

dispose() will stop any playing or recording that might have been taking place.

For example:

	try {
		SoundBite	s = new SoundBite(...);
		...
		s.dispose();
	} catch (SoundBiteException e) {
		...
	}
 

 protected void finalize() throws Throwable

This is usually called by the garbage collector.

Overrides:

finalize in class Object

 public void setNumSamples(int numsamples) throws SoundBiteBadNumSamplesException

Use this to set the number of samples in the audio buffers left[], right[]. Usually will be used when the user is modifying the contents of the audio buffers.

 public synchronized void playStart() throws SoundBitePlayOpenException, SoundBitePlayOtherException

Starts the playback of the audio data in the data buffers left[], right[] in a separate thread. The user can choose to wait for playback to finish using playWaitFor() or can continue with processing while playback happens in its own thread.

 public void playStop() throws SoundBitePlayStopException

Force playback to stop. Has no effect if no playback is currently taking place.

 public synchronized void recordStart() throws SoundBiteRecordOpenException, SoundBiteRecordOtherException

Starts recording audio data in a separate thread. This data will not appear in the user-accessible data buffers left[], right[] until the user calls recordWaitForGet().

The current implementation of this method does the recording in an internal buffer. This internal buffer isn't copied to the user-accessible data buffers left[], right[] until the user calls recordWaitForGet().

On the other hand playback (using playStart()) automatically copies the user-accessible buffers to the internal buffers and plays the internal buffer data.

So the user should be careful to not play without doing recordWaitForGet(). first.

Compare the sequence:

	recordStart();
		// the recorded data is being written to the internal buffer
		// in a separate thread
	recordWaitFor();
		// finished waiting for the recording to finish
		// the recorded data is in the internal buffer
	playStart();
		// this will write the user-accessible data buffers
		// to the internal buffers
		// which will destroy the recently recorded audio
 

versus:

	recordStart();
	recordWaitForGet();
		// finished waiting for the recording to finish
		// AND copied the internal buffer to the user-accessible data buffers
		// the recorded data is in the internal buffer
		// the recorded data is ALSO in the user-accessible data buffers
	playStart();
		// will play the recently recorded audio
 

The user can choose to wait for recording to finish using recordWaitFor() or recordWaitForGet(), or can continue with processing while recording happens in its own thread. Recording will stop automatically once the data buffers have been filled.

 public synchronized void recordWaitForGet()

Wait until no recording is being done using this instance of SoundBite. Then copy the internal buffer to the user-accessible audio data buffers left[], right[].

 public void recordStop() throws SoundBiteRecordStopException

Force recording to stop. Has no effect if no recording is currently taking place.

The audio that was recorded prior to this stoppage will be available in the internal buffer. As usual, a call to recordWaitForGet() will have to be made to get this data into the user-accessible data buffers left[], right[].

 public void clear()

Clears the audio data buffers left[], right[]. Sets elements 0.. getMaxNumSamples() -1) to getMidSampleRange() .
Does not affect the currently set size for audio data buffers ( getNumSamples() ).

All Packages  Class Hierarchy  This Package  Previous  Next  Index