acm.util
Class SoundClip

java.lang.Object
  acm.util.SoundClip

public class SoundClip
extends Object
implements AudioClip

This class represents a sound, which can be created from a URL, sound file, resource stream, or digital samples.

Field Summary

int	LEFT Identifies the left channel in a stereo sound.
int	MAX_SAMPLE Specifies the maximum value of a sample in a sound.
int	MONO Number of channels in a mono sound.
int	RIGHT Identifies the right channel in a stereo sound.
double	STANDARD_FRAME_RATE Specifies the standard frame rate in a sampled sound.
int	STEREO Number of channels in a stereo sound.

Constructor Summary

SoundClip()

SoundClip(File file)

SoundClip(InputStream in)

SoundClip(int channels)

SoundClip(int[] samples)

SoundClip(int[] left, int[] right)

SoundClip(String name)

SoundClip(URL url)

Method Summary

void	addSampleData(int sample) Adds a single sound sample to the end of the sound.
void	addSampleData(int[] samples) Adds the specified samples to the end of the sound.
void	addSampleData(int[] left, int[] right) Adds the specified samples to the end of the appropriate channels of the stereo sound.
void	addSampleData(int left, int right) Adds the specified samples to the end of the appropriate channels of the stereo sound.
int	getChannelCount() Returns the number of channels.
double	getDuration() Returns the duration of a sound (in seconds).
int	getFrameCount() Returns the number of frames in a sound.
int	getFrameIndex() Returns the current frame index in the sound.
double	getFrameRate() Returns the frame rate of the sound.
String	getName() Returns the name of the sound, which is typically the file name from which it was read.
int[]	getSampleData() Returns an array of integers corresponding to the samples in the primary channel of the sound.
int[]	getSampleData(int channel) Returns an array of integers corresponding to the samples in the specified channel, which is typically represented by LEFT or RIGHT.
double	getVolume() Returns the overall volume setting for the sound, which is a number between 0 (silent) and 1 (maximum volume).
int	intensityToSample(double intensity) Converts an intensity value between -1.0 and +1.0 into the corresponding integer sample in the range -32767 and +32767.
boolean	isStereo() Returns true if the sound is recorded in stereo.
void	loop() Plays the sound in a continuous audio loop.
void	play() Plays the sound through the computer's audio system.
void	rewind() Rewinds the sound to the beginning.
double	sampleToIntensity(int sample) Converts an integer sample in the range -32767 and +32767 into a double between -1.0 and +1.0.
void	save(File file) Writes the sound to the specified File object.
void	save(String filename) Writes a data file containing the specified sound.
void	setFrameIndex(int frameIndex) Sets the current frame index.
void	setName(String name) Sets a name to identify the sound.
void	setVolume(double volume) Sets the overall volume setting for the sound, which is a number between 0 (silent) and 1 (maximum volume).
void	stop() Stops the playback of the sound.
String	toString() Converts a sound to a string.

Field Detail

public static final int LEFT

Identifies the left channel in a stereo sound.

See Also:

Constant Field Values

public static final int MAX_SAMPLE

Specifies the maximum value of a sample in a sound. Samples are signed integers between -MAX_SAMPLE and MAX_SAMPLE.

See Also:

Constant Field Values

public static final int MONO

Number of channels in a mono sound.

See Also:

Constant Field Values

public static final int RIGHT

Identifies the right channel in a stereo sound.

See Also:

Constant Field Values

public static final double STANDARD_FRAME_RATE

Specifies the standard frame rate in a sampled sound.

See Also:

Constant Field Values

public static final int STEREO

Number of channels in a stereo sound.

See Also:

Constant Field Values

Constructor Detail

public SoundClip()

Creates an empty single-channel sound to which samples can be added.

Usage:

SoundClip sound = new SoundClip();

public SoundClip(File file)

Creates a new sound by reading the data from the specified file.

Usage:

SoundClip sound = new SoundClip(file);

Parameter:

file	A File object from which the sound is read

public SoundClip(InputStream in)

Creates a new sound by reading the data from the specified input stream.

Usage:

SoundClip sound = new SoundClip(in);

Parameter:

in	An InputStream from which the sound is read

public SoundClip(int channels)

Creates an empty sound with the specified number of channels, which must be 1 for mono and 2 for stereo.

Usage:

SoundClip sound = new SoundClip(channels);

Parameter:

channels

The desired number of channels (1 for mono, 2 for stereo)

public SoundClip(int[] samples)

Creates a new mono sound from the sample array.

Usage:

SoundClip sound = new SoundClip(samples);

Parameter:

samples

An array of integers containing the sampled sound

public SoundClip(int[] left, int[] right)

Creates a new stereo sound from the two sample arrays.

Usage:

SoundClip sound = new SoundClip(samples);

Parameters:

left	An array of integers containing the samples for the left channel
right	An array of integers containing the samples for the right channel

public SoundClip(String name)

Creates a new sound by reading the data from the specified file.

Usage:

SoundClip sound = new SoundClip(name);

Parameter:

name	The file from which the sound is read

public SoundClip(URL url)

Creates a new sound by reading the data from the specified URL.

Usage:

SoundClip sound = new SoundClip(url);

Parameter:

url	A network URL containing the sound

Method Detail

public void addSampleData(int sample)

Adds a single sound sample to the end of the sound. If the sound is stereo, the new sample is added to both the left and right channel.

Usage:

sound.addSampleData(sample);

Parameter:

sample

An integers representing a new sound samples

public void addSampleData(int[] samples)

Adds the specified samples to the end of the sound. If the sound is stereo, the new samples are added to both the left and right channel.

Usage:

sound.addSampleData(samples);

Parameter:

samples

An array of integers containing the new sound samples

public void addSampleData(int[] left, int[] right)

Adds the specified samples to the end of the appropriate channels of the stereo sound.

Usage:

sound.addSampleData(left, right);

Parameters:

left	An array of integers containing the samples for the left channel
right	An array of integers containing the samples for the right channel

public void addSampleData(int left, int right)

Adds the specified samples to the end of the appropriate channels of the stereo sound.

Usage:

sound.addSampleData(left, right);

Parameters:

left	An integer containing a single sample for the left channel
right	An integer containing a single sample for the right channel

public int getChannelCount()

Returns the number of channels.

Usage:	int channels = sound.getChannelCount();
Returns:	The number of channels (1 for mono, 2 for stereo)

public double getDuration()

Returns the duration of a sound (in seconds).

Usage:	double duration = sound.getDuration();
Returns:	The duration of a sound (in seconds)

public int getFrameCount()

Returns the number of frames in a sound.

Usage:	int nFrames = sound.getFrameCount();
Returns:	The number of frames in a sound

public int getFrameIndex()

Returns the current frame index in the sound.

Usage:	int frameIndex = sound.getFrameIndex();
Returns:	The current frame index in the sound

public double getFrameRate()

Returns the frame rate of the sound.

Usage:	double frameRate = sound.getFrameRate();
Returns:	The frame rate of the sound (in frames/second)

public String getName()

Returns the name of the sound, which is typically the file name from which it was read.

Usage:	String name = sound.getName();
Returns:	The name of the sound

public int[] getSampleData()

Returns an array of integers corresponding to the samples in the primary channel of the sound. For mono sounds, this channel is the only channel; for stereo sounds, it is defined to be the left channel.

Usage:	int[] samples = sound.getSampleData();
Returns:	An array of the samples in the sound

public int[] getSampleData(int channel)

Returns an array of integers corresponding to the samples in the specified channel, which is typically represented by LEFT or RIGHT.

Usage:

int[] samples = sound.getSampleData(channel);

Parameter:

channel

The channel for which samples are requested

Returns:

An array of the samples in the sound

public double getVolume()

Returns the overall volume setting for the sound, which is a number between 0 (silent) and 1 (maximum volume).

Usage:	double volume = sound.getVolume();
Returns:	The overall volume setting for the sound

public static int intensityToSample(double intensity)

Converts an intensity value between -1.0 and +1.0 into the corresponding integer sample in the range -32767 and +32767.

Usage:

int sample = SoundClip.intensityToSample(intensity)

Parameter:

intensity

An intensity value between -1.0 and +1.0

Returns:

The corresponding integer sample between -32767 and +32767

public boolean isStereo()

Returns true if the sound is recorded in stereo.

Usage:	if (sound.isStereo()) . . .
Returns:	true if the sound is recorded in stereo

public void loop()

Plays the sound in a continuous audio loop.

Usage:

sound.loop();

Specified by:

loop in interface AudioClip

public void play()

Plays the sound through the computer's audio system.

Usage:

sound.play();

Specified by:

play in interface AudioClip

public void rewind()

Rewinds the sound to the beginning. This method is useful after you have stopped a sound and want to replay it from the beginning.

Usage:

sound.rewind();

public static double sampleToIntensity(int sample)

Converts an integer sample in the range -32767 and +32767 into a double between -1.0 and +1.0.

Usage:

double intensity = SoundClip.sampleToIntensity(sample)

Parameter:

sample

An integer sample from a digital sound

Returns:

The corresponding intensity value between -1.0 and +1.0

public void save(File file)

Writes the sound to the specified File object.

Usage:

sound.save(file);

Parameter:

file	The File object to which the sound is written

public void save(String filename)

Writes a data file containing the specified sound. The format of the sound is determined by the file extension, as follows:

.au	Sun audio file with ALAW encoding
.wav	Waveform audio format
.aif or .aiff	Audio Interchange File Format

Usage:

sound.save(filename);

Parameter:

filename

The name of the file

public void setFrameIndex(int frameIndex)

Sets the current frame index.

Usage:

sound.setFrameIndex(frameIndex);

Parameter:

frameIndex

The current frame index in the sound

public void setName(String name)

Sets a name to identify the sound.

Usage:

sound.setName(name);

Parameter:

name	The name to use for the sound

public void setVolume(double volume)

Sets the overall volume setting for the sound, which is a number between 0 (silent) and 1 (maximum volume).

Usage:

sound.setVolume(volume);

Parameter:

volume

The new overall volume setting for the sound

public void stop()

Stops the playback of the sound. Calling stop saves the current frame index so that calling start will resume from the point at which it stopped.

Usage:

sound.stop();

Specified by:

stop in interface AudioClip

public String toString()

Converts a sound to a string.

Usage:	String str = sound.toString();
Returns:	A string representation of the sound