SoundClip

java.lang.Object
- acm.util.SoundClip

All Implemented Interfaces:

AudioClip
```
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

Fields
Modifier and Type	Field and Description
`static int`	`LEFT` Identifies the left channel in a stereo sound.
`static int`	`MAX_SAMPLE` Specifies the maximum value of a sample in a sound.
`static int`	`MONO` Number of channels in a mono sound.
`static int`	`RIGHT` Identifies the right channel in a stereo sound.
`static double`	`STANDARD_FRAME_RATE` Specifies the standard frame rate in a sampled sound.
`static int`	`STEREO` Number of channels in a stereo sound.

Constructor Summary

Constructors
Constructor and Description
`SoundClip()` Creates an empty single-channel sound to which samples can be added.
`SoundClip(File file)` Creates a new sound by reading the data from the specified file.
`SoundClip(InputStream in)` Creates a new sound by reading the data from the specified input stream.
`SoundClip(int channels)` Creates an empty sound with the specified number of channels, which must be 1 for mono and 2 for stereo.
`SoundClip(int[] samples)` Creates a new mono sound from the sample array.
`SoundClip(int[] left, int[] right)` Creates a new stereo sound from the two sample arrays.
`SoundClip(String name)` Creates a new sound by reading the data from the specified file.
`SoundClip(URL url)` Creates a new sound by reading the data from the specified URL.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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.
`protected AudioInputStream`	`getAudioInputStream()` Returns an `AudioInputStream` for the sound.
`int`	`getChannelCount()` Returns the number of channels.
`protected byte[]`	`getData()` Returns the byte array containing the sound data.
`double`	`getDuration()` Returns the duration of a sound (in seconds).
`protected AudioFormat`	`getFormat()` Returns the format in which the sound is stored.
`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).
`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.
`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.
`static 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.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - MONO
```
public static final int MONO
```
    Number of channels in a mono sound.
    
    See Also:
    
    Constant Field Values
  - STEREO
```
public static final int STEREO
```
    Number of channels in a stereo sound.
    
    See Also:
    
    Constant Field Values
  - LEFT
```
public static final int LEFT
```
    Identifies the left channel in a stereo sound.
    
    See Also:
    
    Constant Field Values
  - RIGHT
```
public static final int RIGHT
```
    Identifies the right channel in a stereo sound.
    
    See Also:
    
    Constant Field Values
  - STANDARD_FRAME_RATE
```
public static final double STANDARD_FRAME_RATE
```
    Specifies the standard frame rate in a sampled sound.
    
    See Also:
    
    Constant Field Values
  - MAX_SAMPLE
```
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
- Constructor Detail
  - SoundClip
```
public SoundClip()
```
    Creates an empty single-channel sound to which samples can be added.
    
    Usage:
    
    SoundClip sound = new SoundClip();
  - SoundClip
```
public SoundClip(int channels)
```
    Creates an empty sound with the specified number of channels, which must be 1 for mono and 2 for stereo.
    
    Parameters:
    
    channels - The desired number of channels (1 for mono, 2 for stereo)
    
    Usage:
    
    SoundClip sound = new SoundClip(channels);
  - SoundClip
```
public SoundClip(String name)
```
    Creates a new sound by reading the data from the specified file.
    
    Parameters:
    
    name - The file from which the sound is read
    
    Usage:
    
    SoundClip sound = new SoundClip(name);
  - SoundClip
```
public SoundClip(File file)
```
    Creates a new sound by reading the data from the specified file.
    
    Parameters:
    
    file - A File object from which the sound is read
    
    Usage:
    
    SoundClip sound = new SoundClip(file);
  - SoundClip
```
public SoundClip(URL url)
```
    Creates a new sound by reading the data from the specified URL.
    
    Parameters:
    
    url - A network URL containing the sound
    
    Usage:
    
    SoundClip sound = new SoundClip(url);
  - SoundClip
```
public SoundClip(InputStream in)
```
    Creates a new sound by reading the data from the specified input stream.
    
    Parameters:
    
    in - An InputStream from which the sound is read
    
    Usage:
    
    SoundClip sound = new SoundClip(in);
  - SoundClip
```
public SoundClip(int[] samples)
```
    Creates a new mono sound from the sample array.
    
    Parameters:
    
    samples - An array of integers containing the sampled sound
    
    Usage:
    
    SoundClip sound = new SoundClip(samples);
  - SoundClip
```
public SoundClip(int[] left,
                 int[] right)
```
    Creates a new stereo sound from the two sample arrays.
    
    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
    
    Usage:
    
    SoundClip sound = new SoundClip(samples);
- Method Detail
  - play
```
public void play()
```
    Plays the sound through the computer's audio system.
    
    Specified by:
    
    play in interface AudioClip
    
    Usage:
    
    sound.play();
  - loop
```
public void loop()
```
    Plays the sound in a continuous audio loop.
    
    Specified by:
    
    loop in interface AudioClip
    
    Usage:
    
    sound.loop();
  - stop
```
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.
    
    Specified by:
    
    stop in interface AudioClip
    
    Usage:
    
    sound.stop();
  - save
```
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
    
    Parameters:
    
    filename - The name of the file
    
    Usage:
    
    sound.save(filename);
  - save
```
public void save(File file)
```
    Writes the sound to the specified File object.
    
    Parameters:
    
    file - The File object to which the sound is written
    
    Usage:
    
    sound.save(file);
  - getName
```
public String getName()
```
    Returns the name of the sound, which is typically the file name from which it was read.
    
    Returns:
    
    The name of the sound
    
    Usage:
    
    String name = sound.getName();
  - setName
```
public void setName(String name)
```
    Sets a name to identify the sound.
    
    Parameters:
    
    name - The name to use for the sound
    
    Usage:
    
    sound.setName(name);
  - getChannelCount
```
public int getChannelCount()
```
    Returns the number of channels.
    
    Returns:
    
    The number of channels (1 for mono, 2 for stereo)
    
    Usage:
    
    int channels = sound.getChannelCount();
  - isStereo
```
public boolean isStereo()
```
    Returns true if the sound is recorded in stereo.
    
    Returns:
    
    true if the sound is recorded in stereo
    
    Usage:
    
    if (sound.isStereo()) . . .
  - getFrameCount
```
public int getFrameCount()
```
    Returns the number of frames in a sound.
    
    Returns:
    
    The number of frames in a sound
    
    Usage:
    
    int nFrames = sound.getFrameCount();
  - getFrameRate
```
public double getFrameRate()
```
    Returns the frame rate of the sound.
    
    Returns:
    
    The frame rate of the sound (in frames/second)
    
    Usage:
    
    double frameRate = sound.getFrameRate();
  - getDuration
```
public double getDuration()
```
    Returns the duration of a sound (in seconds).
    
    Returns:
    
    The duration of a sound (in seconds)
    
    Usage:
    
    double duration = sound.getDuration();
  - getFrameIndex
```
public int getFrameIndex()
```
    Returns the current frame index in the sound.
    
    Returns:
    
    The current frame index in the sound
    
    Usage:
    
    int frameIndex = sound.getFrameIndex();
  - setFrameIndex
```
public void setFrameIndex(int frameIndex)
```
    Sets the current frame index.
    
    Parameters:
    
    frameIndex - The current frame index in the sound
    
    Usage:
    
    sound.setFrameIndex(frameIndex);
  - rewind
```
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();
  - getVolume
```
public double getVolume()
```
    Returns the overall volume setting for the sound, which is a number between 0 (silent) and 1 (maximum volume).
    
    Returns:
    
    The overall volume setting for the sound
    
    Usage:
    
    double volume = sound.getVolume();
  - setVolume
```
public void setVolume(double volume)
```
    Sets the overall volume setting for the sound, which is a number between 0 (silent) and 1 (maximum volume).
    
    Parameters:
    
    volume - The new overall volume setting for the sound
    
    Usage:
    
    sound.setVolume(volume);
  - getSampleData
```
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.
    
    Returns:
    
    An array of the samples in the sound
    
    Usage:
    
    int[] samples = sound.getSampleData();
  - getSampleData
```
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.
    
    Parameters:
    
    channel - The channel for which samples are requested
    
    Returns:
    
    An array of the samples in the sound
    
    Usage:
    
    int[] samples = sound.getSampleData(channel);
  - addSampleData
```
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.
    
    Parameters:
    
    sample - An integers representing a new sound samples
    
    Usage:
    
    sound.addSampleData(sample);
  - addSampleData
```
public void addSampleData(int left,
                          int right)
```
    Adds the specified samples to the end of the appropriate channels of the stereo sound.
    
    Parameters:
    
    left - An integer containing a single sample for the left channel
    
    right - An integer containing a single sample for the right channel
    
    Usage:
    
    sound.addSampleData(left, right);
  - addSampleData
```
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.
    
    Parameters:
    
    samples - An array of integers containing the new sound samples
    
    Usage:
    
    sound.addSampleData(samples);
  - addSampleData
```
public void addSampleData(int[] left,
                          int[] right)
```
    Adds the specified samples to the end of the appropriate channels of the stereo sound.
    
    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
    
    Usage:
    
    sound.addSampleData(left, right);
  - toString
```
public String toString()
```
    Converts a sound to a string.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    A string representation of the sound
    
    Usage:
    
    String str = sound.toString();
  - sampleToIntensity
```
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.
    
    Parameters:
    
    sample - An integer sample from a digital sound
    
    Returns:
    
    The corresponding intensity value between -1.0 and +1.0
    
    Usage:
    
    double intensity = SoundClip.sampleToIntensity(sample)
  - intensityToSample
```
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.
    
    Parameters:
    
    intensity - An intensity value between -1.0 and +1.0
    
    Returns:
    
    The corresponding integer sample between -32767 and +32767
    
    Usage:
    
    int sample = SoundClip.intensityToSample(intensity)
  - getData
```
protected byte[] getData()
```
    Returns the byte array containing the sound data.
  - getFormat
```
protected AudioFormat getFormat()
```
    Returns the format in which the sound is stored.
  - getAudioInputStream
```
protected AudioInputStream getAudioInputStream()
```
    Returns an AudioInputStream for the sound.

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

Class SoundClip

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

MONO

STEREO

LEFT

RIGHT

STANDARD_FRAME_RATE

MAX_SAMPLE

Constructor Detail

SoundClip

SoundClip

SoundClip

SoundClip

SoundClip

SoundClip

SoundClip

SoundClip

Method Detail

play

loop

stop

save

save

getName

setName

getChannelCount

isStereo

getFrameCount

getFrameRate

getDuration

getFrameIndex

setFrameIndex

rewind

getVolume

setVolume

getSampleData

getSampleData

addSampleData

addSampleData

addSampleData

addSampleData

toString

sampleToIntensity

intensityToSample

getData

getFormat

getAudioInputStream