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.