Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## Class SimpleSound

    java.lang.Object
      SimpleSound

Direct Known Subclasses:
  Sound

    public class SimpleSound

extends Object

The `SimpleSound` class is an implementation of the Java Sound API specifically designed for use with students. http://java.sun.com/products/java-media/sound/index.html

This class allows for easy playback, and manipulation of AU, AIFF, and WAV files.

Code & ideas for this class related to playing and viewing the sound were borrowed from the Java Sound Demo: http://java.sun.com/products/java-media/sound/ samples/JavaSoundDemo/ Also, some code borrowed from Tritonus as noted. Copyright Georgia Institute of Technology 2004

Author:
  Ellie Harmon, ellie@cc.gatech.edu, Barbara Ericson ericson@mindspring.com

Field Summary
`static int` | `MAX_NEG` Constant for max negative value
`static int` | `MAX_POS` Constant for max positive value

Constructor Summary
`SimpleSound()` Constructs a `SimpleSound` of 3 seconds long.
`SimpleSound(int numFrames)` Constructs a `SimpleSound` of the specified length.
`SimpleSound(int sampleSizeInBits, boolean isBigEndian)` Constructs a simple sound with the given sample size in bits and type of endian (big or little)
`SimpleSound(int numFrames, int sampleRate)` Constructs a `SimpleSound` of the specified length.
`SimpleSound(SimpleSound sound)` Constructor that creates a new SimpleSound by copying a passed SimpleSound
`SimpleSound(String fileName)` Constructs a new SimpleSound from the given file.

Method Summary
`byte[]` | `asArray()` Method to return the byte array
`void` | `blockingPlay()` Plays the sound, then sleeps for how long the sound SHOULD last.
`void` | `blockingPlayAtRateDur(double rate, double durInFrames)` First, checks the value of durInFrames to make sure that it is not larger than Integer.MAX_VALUE to guarrantee safe casting.
`void` | `blockingPlayAtRateInRange(float rate, int startFrame, int endFrame)` Calls `playAtRateInRange(rate, startFrame, endFrame, true)` .
`void` | `blockingPlayOld()` Creates a new Playback thread, starts it, then waits for the entire sound to finish playing before it returns.
`static void` | `convert(String mp3File, String wavFile)` Method to convert a mp3 sound into a wav sound
`void` | `explore()` Method to open a sound viewer on a copy of this sound
`AudioFileFormat` | `getAudioFileFormat()` Method that returns the AudioFileFormat describing this simple sound.
`byte[]` | `getBuffer()` Method that returns the byte array representation of this simple sound.
`int` | `getChannels()` Obtains the number of channels of this sound.
`boolean` | `getDEBUG()` Method to get the value of the debug flag
`String` | `getFileName()` Method that returns the name of the file this sound came from.
`byte[]` | `getFrame(int frameNum)` Returns an array containing all of the bytes in the specified frame.
`int` | `getLeftSample(int frameNum)` Obtains the left sample of the audio data contained at the specified frame.
`int` | `getLength()` Method to return the length of the sound as the number of samples
`int` | `getLengthInBytes()` Obtains the length of this sound in bytes.
`int` | `getLengthInFrames()` Obtains the length of the audio data contained in the file, expressed in sample frames.
`int` | `getNumSamples()` Returns the number of samples in this sound
`Vector` | `getPlaybacks()` Method that returns the vector of playback threads currently active on this sound.
`int` | `getRightSample(int frameNum)` Obtains the right sample of the audio data contained at the specified frame.
`SoundSample` | `getSample(int frameNum)` Method to create and return a SoundSample object for the given frame number
`SoundSample[]` | `getSamples()` Method to create and return an array of SoundSample objects
`int` | `getSampleValue(int frameNum)` If this is a mono sound, obtains the single sample contained within this frame, else obtains the first (left) sample contained in the specified frame.
`int` | `getSampleValueAt(int index)` Method to get the sample at the passed index and handle any SoundExceptions
`double` | `getSamplingRate()` Method to get the sampling rate of this sound
`SoundExplorer` | `getSoundExplorer()` Method that returns the SoundExplorer
`boolean` | `isStereo()` Method to check if a sound is stereo (2 channels) or not
`void` | `loadFromFile(String inFileName)` Resets the fields of this sound so that it now represents the sound in the specified file.
`AudioInputStream` | `makeAIS()` Creates an `AudioInputStream` for this sound from the `buffer` and the `audioFileFormat`.
`void` | `play()` Creates a new Playback thread and starts it.
`void` | `playAtRateDur(double rate, double durInFrames)` Checks the value of durInFrames to make sure that it is not larger than Integer.MAX_VALUE to guarrantee safe casting.
`void` | `playAtRateInRange(float rate, int startFrame, int endFrame)` Calls `playAtRateInRange(rate, startFrame, endFrame, false)` .
`void` | `playAtRateInRange(float rate, int startFrame, int endFrame, boolean isBlocking)` Plays the specified segment of this sound at the given sample rate.
`static void` | `playNote(int key, int duration, int intensity)` Method to play a note using MIDI
`void` | `printError(String message)` Invokes `printError(message, null)`
`void` | `printError(String message, Exception e)` Prints the given String to the "standard" error output stream, then prints a stack trace on the exception, and then exits the program.
`void` | `removePlayback(Playback playbackToRemove)` Deletes the specified playback object from the Vector.
`void` | `setAudioFileFormat(AudioFileFormat newAudioFileFormat)` Changes the AudioFileFormat of this sound.
`void` | `setBuffer(byte[] newBuffer)` Changes the byte array that represents this sound.
`void` | `setFrame(int frameNum, byte[] theFrame)` Changes the value of each byte of the specified frame.
`void` | `setLeftSample(int frameNum, int sample)`
`void` | `setRightSample(int frameNum, int sample)`
`void` | `setSampleValue(int frameNum, int sample)` Changes the value of the sample found at the specified frame.
`void` | `setSampleValueAt(int index, int value)` Method to set the sample value at the passed index to the passed value
`void` | `setSoundExplorer(SoundExplorer soundExplorer)` Changes the explorer of this object.
`String` | `toString()` Obtains a string representation of this JavaSound.
`void` | `write(String fileName)` Method to write this sound to a file
`void` | `writeToFile(String outFileName)` Creates an audioInputStream from this sound, and then writes this stream out to the file with the specified name.

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

Field Detail

### MAX_NEG

    public static final int MAX_NEG

  Constant for max negative value

  See Also:
    Constant Field Values

### MAX_POS

    public static final int MAX_POS

  Constant for max positive value

  See Also:
    Constant Field Values

Constructor Detail

### SimpleSound

    public SimpleSound()

  Constructs a `SimpleSound` of 3 seconds long.

### SimpleSound

    public SimpleSound(int numFrames)

  Constructs a `SimpleSound` of the specified length. This sound will simply consist of an empty byte array, and an `AudioFileFormat` with the following values:
  - `AudioFileFormat.Type.WAVE`
  - 22.05K sampling rate
  - 16 bit sample
  - 1 channel
  - signed PCM encoding
  - small-endian byte order
  Note that no new sound file is created, we only represent the sound with a buffer and the AudioFileFormat. If a file is desired, then the method `writeToFile(String filename)` must be called on this newly created sound.

  Parameters:
    `numFrames` - the number of samples in the sound
  See Also:
    `write(String filename)`

### SimpleSound

    public SimpleSound(int numFrames,
                       int sampleRate)

  Constructs a `SimpleSound` of the specified length. This sound will simply consist of an empty byte array, and an `AudioFileFormat` with the following values:
  - `AudioFileFormat.Type.WAVE`
  - 22.05K sampling rate
  - 16 bit sample
  - 1 channel
  - signed PCM encoding
  - small-endian byte order
  Note that no new sound file is created, we only represent the sound with a buffer and the AudioFileFormat. If a file is desired, then the method `writeToFile(String filename)` must be called on this newly created sound.

  Parameters:
    `numFrames` - the number of samples in the sound
  See Also:
    `write(String filename)`

### SimpleSound

    public SimpleSound(int sampleSizeInBits,
                       boolean isBigEndian)

  Constructs a simple sound with the given sample size in bits and type of endian (big or little)

### SimpleSound

    public SimpleSound(String fileName)

  Constructs a new SimpleSound from the given file.

  Parameters:
    `fileName` - The File from which to create this sound.
  See Also:
    `loadFromFile(String filename)`

### SimpleSound

    public SimpleSound(SimpleSound sound)

  Constructor that creates a new SimpleSound by copying a passed SimpleSound

  Parameters:
    `sound` - the sound to copy

Method Detail

### getBuffer

    public byte[] getBuffer()

  Method that returns the byte array representation of this simple sound.

  Returns:
    the sound represented as a byte array

### getAudioFileFormat

    public AudioFileFormat getAudioFileFormat()

  Method that returns the AudioFileFormat describing this simple sound.

  Returns:
    the AudioFileFormat describing this sound
  See Also:
    `AudioFileFormat`

### getSamplingRate

    public double getSamplingRate()

  Method to get the sampling rate of this sound

  Returns:
    the sampling rate in number of samples per second

### getSoundExplorer

    public SoundExplorer getSoundExplorer()

  Method that returns the SoundExplorer

  Returns:
    the sound explorer

### asArray

    public byte[] asArray()

  Method to return the byte array

  Returns:
    an array of bytes which represents the simple sound
  See Also:
    `getBuffer()`

### getPlaybacks

    public Vector getPlaybacks()

  Method that returns the vector of playback threads currently active on this sound.

  Returns:
    the vector of playback threads for this simple sound

### getFileName

    public String getFileName()

  Method that returns the name of the file this sound came from. If this sound did not originate with a file, this value will be null.

  Returns:
    the file name associated with this sound or null
  See Also:
    `loadFromFile(String fileName)`

### getDEBUG

    public boolean getDEBUG()

  Method to get the value of the debug flag

  Returns:
    true if in debug mode else false

### setBuffer

    public void setBuffer(byte[] newBuffer)

  Changes the byte array that represents this sound.

  Parameters:
    `newBuffer` - a byte array representation of the new sound we want this to represent.

### setAudioFileFormat

    public void setAudioFileFormat(AudioFileFormat newAudioFileFormat)

  Changes the AudioFileFormat of this sound.

  Parameters:
    `newAudioFileFormat` - the new audioFileFormat that describes this sound.
  See Also:
    `AudioFileFormat`

### setSoundExplorer

    public void setSoundExplorer(SoundExplorer soundExplorer)

  Changes the explorer of this object.

  Parameters:
    `soundExplorer` - the new SoundExplorer to use
  See Also:
    `SoundExplorer`

### makeAIS

    public AudioInputStream makeAIS()

  Creates an `AudioInputStream` for this sound from the `buffer` and the `audioFileFormat`.

  Returns:
    an AudioInputStream representing this sound.
  See Also:
    `AudioInputStream`

### printError

    public void printError(String message)

  Invokes `printError(message, null)`

  Throws:
    `SoundException` - Will throw under every circumstance. This way we can catch the exception in JES.
  See Also:
    `printError(String message, Exception e)`

### printError

    public void printError(String message,
                           Exception e)

  Prints the given String to the "standard" error output stream, then prints a stack trace on the exception, and then exits the program. If the String is null, then nothing happens, the method just returns. If the Exception is null, then it prints the String and then exits the program.

  Parameters:
    `message` - A description of the error
    `e` - The exception, if any, that was caught regarding the error
  Throws:
    `SoundException` - Will throw under every circumstance. This way we can catch the exception in JES.

### isStereo

    public boolean isStereo()

  Method to check if a sound is stereo (2 channels) or not

  Returns:
    true if in stereo else false

### write

    public void write(String fileName)

  Method to write this sound to a file

  Parameters:
    `fileName` - the name of the file to write to

### writeToFile

    public void writeToFile(String outFileName)
                     throws SoundException

  Creates an audioInputStream from this sound, and then writes this stream out to the file with the specified name. If no file exists, one is created. If a file already exists, then it is overwritten. This does not check the extension of the fileName passed in to make sure it agrees with the `AudioFileFormat.Type` of this sound.

  Parameters:
    `outFileName` - The name of the file to write this sound to
  Throws:
    `SoundException` - if any error is encountered while writing to the file.

### loadFromFile

    public void loadFromFile(String inFileName)
                      throws SoundException

  Resets the fields of this sound so that it now represents the sound in the specified file. If successful, the fileName ariable is updated such that it is equivalent to `inFileName`.

  Parameters:
    `inFileName` - the path and filename of the sound we want to represent.
  Throws:
    `SoundException` - if any problem is encountered while reading in from the file.

### play

    public void play()

  Creates a new Playback thread and starts it. The thread is guarranteed to finish playing the sound as long as the program doesn't exit before it is done. This method does not block, however. So, if you invoke `play()` multiple times in a row, sounds will simply play on top of eachother - "accidental mixing"

  See Also:
    `Playback`

### blockingPlayOld

    public void blockingPlayOld()

  Creates a new Playback thread, starts it, then waits for the entire sound to finish playing before it returns. This method is guarranteed to play the entire sound, and does not allow for any "accidental mixing"

  See Also:
    `Playback`

### blockingPlay

    public void blockingPlay()

  Plays the sound, then sleeps for how long the sound SHOULD last.

### playAtRateDur

    public void playAtRateDur(double rate,
                              double durInFrames)
                       throws SoundException

  Checks the value of durInFrames to make sure that it is not larger than Integer.MAX_VALUE to guarrantee safe casting. Also checks the value of rate to make sure that it is not larger than Float.MAX_VALUE before casting.

  Parameters:
    `rate` - a double representing the change in sampleRate (==frameRate) for playing back this sound
    `durInFrames` - a double representing how much of this sound we want to play.
  Throws:
    `SoundException` - if there are problems playing the sound.
  See Also:
    `playAtRateInRange(float rate, int startFrame, int endFrame, boolean isBlocking)`

### blockingPlayAtRateDur

    public void blockingPlayAtRateDur(double rate,
                                      double durInFrames)
                               throws SoundException

  First, checks the value of durInFrames to make sure that it is not larger than Integer.MAX_VALUE to guarrantee safe casting. Simmilarly, checks the value of rate to make sure that it is not larger than FLoat.MAX_VALUE before casting.

  Parameters:
    `rate` - a double representing the change in sampleRate (==frameRate) for playing back this sound
    `durInFrames` - a double representing how much of this sound we want to play
  Throws:
    `SoundException` - if there are problems playing the sound.
  See Also:
    `playAtRateInRange(float range, int startFrame, int endFrame, boolean isBlocking)`

### playAtRateInRange

    public void playAtRateInRange(float rate,
                                  int startFrame,
                                  int endFrame)
                           throws SoundException

  Calls `playAtRateInRange(rate, startFrame, endFrame, false)` .

  Parameters:
    `rate` - a float representing the change in sampleRate (==frameRate) for playing back this sound
    `startFrame` - an int representing the frame at which we want to begin playing the sound
    `endFrame` - an int representing the frame at which want to stop playing the sound
  Throws:
    `SoundException` - if there are problems playing the sound.
  See Also:
    `playAtRateInRange(float range, int startFrame, int endFrame, boolean isBlocking)`

### blockingPlayAtRateInRange

    public void blockingPlayAtRateInRange(float rate,
                                          int startFrame,
                                          int endFrame)
                                   throws SoundException

  Calls `playAtRateInRange(rate, startFrame, endFrame, true)` .

  Parameters:
    `rate` - a float representing the change in sampleRate (==frameRate) for playing back this sound
    `startFrame` - an int representing the frame at which we want to begin playing the sound
    `endFrame` - an int representing the frame at which want to stop playing the sound
  Throws:
    `SoundException` - if there are problems playing the sound.
  See Also:
    `playAtRateInRange(float range, int startFrame, int endFrame, boolean isBlocking)`

### playAtRateInRange

    public void playAtRateInRange(float rate,
                                  int startFrame,
                                  int endFrame,
                                  boolean isBlocking)
                           throws SoundException

  Plays the specified segment of this sound at the given sample rate. Then it saves the old fields (buffer and audioFileFormat) of this sound into temporary variables, and setting the fields of this sound to modified values. Then it creates a Playback thread on this sound (with the modified values) and starts the thread. The values for buffer and audioFileFormat are restored to their original values before the method returns.

  Parameters:
    `rate` - The change in the sampleRate (==frameRate) for playing back this sound. The old SampleRate is multiplied by this value. So, if rate = 2, the sound will play twice as fast (half the length), and if rate = .5, the sound will play half as fast (twice the length).
    `startFrame` - The index of the frame where we want to begin play
    `endFrame` - The index of the frame where we want to end play
    `isBlocking` - If true, this method waits until the thread is done playing the sound before returning. If false, it simply starts the thread and then returns.
  Throws:
    `SoundException` - if there are any problems playing the sound.

### removePlayback

    public void removePlayback(Playback playbackToRemove)

  Deletes the specified playback object from the Vector. This should only be called from within the run() method of an individual playback thread.

  See Also:
    `Playback.run()`

### getFrame

    public byte[] getFrame(int frameNum)
                    throws SoundException

  Returns an array containing all of the bytes in the specified frame.

  Parameters:
    `frameNum` - the index of the frame to access
  Returns:
    the array containing all of the bytes in frame `frameNum`
  Throws:
    `SoundException` - if the frame number is invalid.

### getLengthInFrames

    public int getLengthInFrames()

  Obtains the length of the audio data contained in the file, expressed in sample frames.

  Returns:
    the number of sample frames of audio data in the file

### getNumSamples

    public int getNumSamples()

  Returns the number of samples in this sound

  Returns:
    the number of sample frames

### getSample

    public SoundSample getSample(int frameNum)

  Method to create and return a SoundSample object for the given frame number

  Returns:
    a SoundSample object for this frame number

### getSamples

    public SoundSample[] getSamples()

  Method to create and return an array of SoundSample objects

  Returns:
    the array of SoundSample objects

### getSampleValueAt

    public int getSampleValueAt(int index)

  Method to get the sample at the passed index and handle any SoundExceptions

  Parameters:
    `index` - the desired index
  Returns:
    the sample value

### getSampleValue

    public int getSampleValue(int frameNum)
                       throws SoundException

  If this is a mono sound, obtains the single sample contained within this frame, else obtains the first (left) sample contained in the specified frame.

  Parameters:
    `frameNum` - the index of the frame to access
  Returns:
    an integer representation of the bytes contained within the specified frame
  Throws:
    `SoundException` - if the frame number is invalid.

### getLeftSample

    public int getLeftSample(int frameNum)
                      throws SoundException

  Obtains the left sample of the audio data contained at the specified frame.

  Parameters:
    `frameNum` - the index of the frame to access
  Returns:
    an int representation of the bytes contained in the specified frame.
  Throws:
    `SoundException` - if the frameNumber is invalid

### getRightSample

    public int getRightSample(int frameNum)
                       throws SoundException

  Obtains the right sample of the audio data contained at the specified frame.

  Parameters:
    `frameNum` - the index of the frame to access
  Returns:
    an int representation of the bytes contained in the specified frame.
  Throws:
    `SoundException` - if the frameNumber is invalid, or the encoding isn't supported.

### getLengthInBytes

    public int getLengthInBytes()

  Obtains the length of this sound in bytes. Note, that this number is not neccessarily the same as the length of this sound's file in bytes.

  Returns:
    the sound length in bytes

### getLength

    public int getLength()

  Method to return the length of the sound as the number of samples

  Returns:
    the length of the sound as the number of samples

### getChannels

    public int getChannels()

  Obtains the number of channels of this sound.

  Returns:
    the number of channels (1 for mono, 2 for stereo), or `AudioSystem.NOT_SPECIFIED`
  See Also:
    `AudioSystem.NOT_SPECIFIED`

### setFrame

    public void setFrame(int frameNum,
                         byte[] theFrame)
                  throws SoundException

  Changes the value of each byte of the specified frame.

  Parameters:
    `frameNum` - the index of the frame to change
    `theFrame` - the byte array that will be copied into this sound's buffer in place of the specified frame.
  Throws:
    `SoundException` - if the frameNumber is invalid.

### setSampleValueAt

    public void setSampleValueAt(int index,
                                 int value)

  Method to set the sample value at the passed index to the passed value

  Parameters:
    `index` - the index
    `value` - the new value

### setSampleValue

    public void setSampleValue(int frameNum,
                               int sample)
                        throws SoundException

  Changes the value of the sample found at the specified frame. If this sound has more than one channel, then this defaults to setting only the first (left) sample.

  Parameters:
    `frameNum` - the index of the frame where the sample should be changed
    `sample` - an int representation of the new sample to put in this sound's buffer at the specified frame
  Throws:
    `SoundException` - if the frameNumber is invalid, or another problem is encountered

### setLeftSample

    public void setLeftSample(int frameNum,
                              int sample)
                       throws SoundException

  Throws:
    `SoundException`

### setRightSample

    public void setRightSample(int frameNum,
                               int sample)
                        throws SoundException

  Throws:
    `SoundException`

### explore

    public void explore()

  Method to open a sound viewer on a copy of this sound

### playNote

    public static void playNote(int key,
                                int duration,
                                int intensity)

  Method to play a note using MIDI

  Parameters:
    `key` - the piano key to play
    `duration` - how long to play the note
    `intensity` - how hard to strike the note from (0-127)

### convert

    public static void convert(String mp3File,
                               String wavFile)

  Method to convert a mp3 sound into a wav sound

  Parameters:
    `mp3File` -
    `wavFile` -

### toString

    public String toString()

  Obtains a string representation of this JavaSound.

  Overrides:
    `toString` in class `Object`
  Returns:
    a String representation of this JavaSound.

Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD