Class SimpleSound

java.lang.Object
  extended by 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: 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: 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.