jAudioFeatureExtractor.jAudioTools
Class AudioMethods

java.lang.Object
  extended by jAudioFeatureExtractor.jAudioTools.AudioMethods

public class AudioMethods
extends java.lang.Object

A holder class for general static methods relating to sampled audio involving classes used in the javax.sound.sampled package. Also includes methods for use in converting back an forth between audio stored using this package and audio stored as samples in arrays of doubles.

Author:
Cory McKay

Constructor Summary
AudioMethods()
           
 
Method Summary
static double[][] clipSamples(double[][] original_samples)
          Clips the given samples so that all values below -1 are set to -1 and all values above 1 are set to 1.
static javax.sound.sampled.AudioInputStream convertToAudioInputStream(double[][] samples, javax.sound.sampled.AudioFormat audio_format)
          Returns an AudioInputStream containing the given samples encoded using the given AudioFormat.
static javax.sound.sampled.AudioInputStream convertUnsupportedFormat(javax.sound.sampled.AudioInputStream audio_input_stream)
          Takes the given AudioInputStream and tests if it is playable.
static double[][] extractSampleValues(javax.sound.sampled.AudioInputStream audio_input_stream)
          Returns an array of doubles representing the samples for each channel in the given AudioInputStream.
static double findMaximumSampleValue(int bit_depth)
          Returns the maximum possible value that a signed sample can have under the given bit depth.
static java.lang.String getAudioFileFormatData(java.io.File file)
          Returns information regarding a given audio file.
static javax.sound.sampled.AudioFileFormat.Type getAudioFileFormatType(java.lang.String file_type_name)
          Returns the appropriate AudioFileFormat.Type corresponding to the given String.
static java.lang.String getAudioFormatData(javax.sound.sampled.AudioFormat audio_format)
          Returns information regarding a given AudioFormat.
static java.lang.String[] getAvailableFileFormatTypes()
          Returns the names of file types for which file writing support is provided by the system.
static java.lang.String getAvailableMixerData()
          Returns information in String form regarding all available system mixers.
static byte[] getBytesFromAudioInputStream(javax.sound.sampled.AudioInputStream audio_input_stream)
          Generates an array of audio bytes based on the contents of the given AudioInputStream.
static javax.sound.sampled.AudioFormat getConvertedAudioFormat(javax.sound.sampled.AudioFormat original_format)
          Returns an AudioFormat with the same sampling rate and number of channels as the passed AudioFormat.
static javax.sound.sampled.AudioInputStream getConvertedAudioStream(javax.sound.sampled.AudioInputStream audio_input_stream)
          Returns a copy of the given AudioInputStream that uses big-endian signed linear PCM encoding, regardless of the original encoding.
static javax.sound.sampled.AudioFormat getCopyOfAudioFormat(javax.sound.sampled.AudioFormat old_audio_format)
          Returns a copy of the given AudioFormat.
static javax.sound.sampled.AudioInputStream getInputStream(byte[] audio_bytes, javax.sound.sampled.AudioFormat audio_format)
          Generates an AudioInputStream based on the given array of bytes and the given AudioFormat.
static javax.sound.sampled.AudioInputStream getInputStream(java.io.ByteArrayOutputStream byte_stream, javax.sound.sampled.AudioFormat audio_format)
          Generates an AudioInputStream based on the given ByteArrayOutputStream and the given AudioFormat.
static javax.sound.sampled.AudioInputStream getInputStream(java.io.File audio_file)
          Generates an AudioInputStream based on the contents of the given File.
static javax.sound.sampled.Mixer getMixer(int mixer_index, AudioEventLineListener listener)
          Returns the Mixer object with the specified index.
static int getNumberBytesNeeded(double duration_in_seconds, javax.sound.sampled.AudioFormat audio_format)
          Returns the number of bytes needed to store samples corresponding to audio of fixed duration.
static int getNumberBytesNeeded(int number_samples, javax.sound.sampled.AudioFormat audio_format)
          Returns the number of bytes needed to store samples corresponding to the given number of samples in a given AudioFormat.
static javax.sound.sampled.SourceDataLine getSourceDataLine(javax.sound.sampled.AudioFormat audio_format, AudioEventLineListener listener)
          Gets a SourceDataLine that can be used for purposes such as writing directly to a speaker.
static javax.sound.sampled.TargetDataLine getTargetDataLine(javax.sound.sampled.AudioFormat audio_format, AudioEventLineListener listener)
          Returns a TargetDataLine that can be used for purposes such as recording from a mic.
static javax.sound.sampled.TargetDataLine getTargetDataLine(javax.sound.sampled.AudioFormat audio_format, javax.sound.sampled.Mixer mixer, AudioEventLineListener listener)
          Returns a TargetDataLine that can be used for purposes such as recording from a mic.
static void saveByteArrayOutputStream(java.io.ByteArrayOutputStream audio, javax.sound.sampled.AudioFormat audio_format, java.io.File save_file, javax.sound.sampled.AudioFileFormat.Type file_type)
          Stores the samples on the ByteArrayOutputStream to the given file.
static void saveToFile(javax.sound.sampled.AudioInputStream audio_input_stream, java.io.File file_to_save_to, javax.sound.sampled.AudioFileFormat.Type file_type)
          Stores the samples coming in on the given AudioInputStream to the given file.
static void writeSamplesToBuffer(double[][] sample_values, int bit_depth, byte[] buffer)
          Writes the samples in the sample_values parameter to the buffer parameter.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AudioMethods

public AudioMethods()
Method Detail

getCopyOfAudioFormat

public static javax.sound.sampled.AudioFormat getCopyOfAudioFormat(javax.sound.sampled.AudioFormat old_audio_format)
Returns a copy of the given AudioFormat.

Parameters:
old_audio_format - The AudioFormat to copy.
Returns:
A copy of old_audio_format.

getAudioFormatData

public static java.lang.String getAudioFormatData(javax.sound.sampled.AudioFormat audio_format)
Returns information regarding a given AudioFormat. This information consists of mixer index, name, version, vendor and description, in that order. A list of any additional property names are also included. The getProperty method of the AudioFormat class may then be used to access the values of these properties using the key listed here. Three common property keys are bitrate, vbr and quality (see the AudioFormat API). These may not be visible, depending on whether they were encoded and on whether the file reader used can see them.

Parameters:
audio_format - The AudioFormat to return data about.
Returns:
Data in string form about the specified AudioFormat.

getAudioFileFormatData

public static java.lang.String getAudioFileFormatData(java.io.File file)
                                               throws java.lang.Exception
Returns information regarding a given audio file. This information consists of the file name, its type, its size and the length of its audio data in KB and in seconds. A list of any additional property names are also included. The getProperty method of the AudioFileFormat class may then be used to access the values of these properties using the key listed here. Six common property keys are duration, author, title, copyright, date and comment. These may not be visible, depending on whether they were encoded and on whether the file reader used can see them. The AudioFormat properties are also returned (see the getAudioFormatData method of this class).

Parameters:
file - The file to return data about.
Returns:
Data in string form about the specified AudioFormat.
Throws:
java.lang.Exception - Throws informative exceptions if the file is invalid or has an unsupported format.

getAvailableFileFormatTypes

public static java.lang.String[] getAvailableFileFormatTypes()
Returns the names of file types for which file writing support is provided by the system. Provided in reverse order of how the AudioSystem.getAudioFileTypes method returns them.

Returns:
The names of system supported audio file formats.

getAudioFileFormatType

public static javax.sound.sampled.AudioFileFormat.Type getAudioFileFormatType(java.lang.String file_type_name)
Returns the appropriate AudioFileFormat.Type corresponding to the given String.

WARNING: Future additions to the Java SDK may make further formats available that are not accounted for here.

Parameters:
file_type_name - The name of the format type desired.
Returns:
The AudioFileFormat.Type corresponding to the given file_type_name. Returns null if the file_type_name does not correspond to any known AudioFileFormat.Type.

getAvailableMixerData

public static java.lang.String getAvailableMixerData()
Returns information in String form regarding all available system mixers. This information consists of mixer index, name, version, vendor and description, in that order.


getMixer

public static javax.sound.sampled.Mixer getMixer(int mixer_index,
                                                 AudioEventLineListener listener)
Returns the Mixer object with the specified index. The mixers corresponding to the given index may be obtained by calling the printAvailableMixers method.

If the listener parameter is not null, then open, start, stop and close events will be sent to the passed listener. If it is null, then the line is returned without any attached listener.

WARNING: The Mixer correxponding to particular indices will vary from system to system.

Parameters:
mixer_index - The index (on the current system) of the mixer to be returned.
listener - Responds to open, start, stop and close events on the returned line. May be null.
Returns:
The specified Mixer.

getTargetDataLine

public static javax.sound.sampled.TargetDataLine getTargetDataLine(javax.sound.sampled.AudioFormat audio_format,
                                                                   AudioEventLineListener listener)
                                                            throws java.lang.Exception
Returns a TargetDataLine that can be used for purposes such as recording from a mic. This line will correspond to a system-specified mixer. This line will be opened and started, and will therefore be recording data when it is returned.

If the listener parameter is not null, then open, start, stop and close events will be sent to the passed listener. If it is null, then the line is returned without any attached listener. WARNING: The TargetDataLine opened here will begin capturing data and storing it in an internal a buffer. The user must be sure to take data from this line quickly enough that its buffer does not overflow, with the result that data is lost.

Parameters:
audio_format - The audio format to be used by the TargetDataLine
listener - Responds to open, start, stop and close events on the returned line. May be null.
Returns:
A TargetDataLine that can be used for purposes such as recording from a mic.
Throws:
java.lang.Exception - Throws an exception if cannot get a valid TargetDataLine.

getTargetDataLine

public static javax.sound.sampled.TargetDataLine getTargetDataLine(javax.sound.sampled.AudioFormat audio_format,
                                                                   javax.sound.sampled.Mixer mixer,
                                                                   AudioEventLineListener listener)
                                                            throws java.lang.Exception
Returns a TargetDataLine that can be used for purposes such as recording from a mic. This line will correspond to the specified Mixer. This line will be opened and started, and will therefore be recording data when it is returned.

If the listener parameter is not null, then open, start, stop and close events will be sent to the passed listener. If it is null, then the line is returned without any attached listener. WARNING: The TargetDataLine opened here will begin capturing data and storing it in an internal buffer. The user must be sure to take data from this line quickly enough that its buffer does not overflow, and data is lost.

Parameters:
audio_format - The audio format to be used by the TargetDataLine
mixer - The Mixer corresponding to the TargetDataLine.
listener - Responds to open, start, stop and close events on the returned line. May be null.
Returns:
A TargetDataLine that can be used for purposes such as recording from a mic.
Throws:
java.lang.Exception - Throws an exception if cannot get a valid TargetDataLine.

getSourceDataLine

public static javax.sound.sampled.SourceDataLine getSourceDataLine(javax.sound.sampled.AudioFormat audio_format,
                                                                   AudioEventLineListener listener)
Gets a SourceDataLine that can be used for purposes such as writing directly to a speaker. This line will correspond to a system-specified mixer. This line will be opened and started, and will therefore be ready to write data when it is returned.

If the listener parameter is not null, then open, start, stop and close events will be sent to the passed listener. If it is null, then the line is returned without any attached listener.

Parameters:
audio_format - The audio format to be used by the SourceDataLine.
listener - Responds to open, start, stop and close events on the returned line. May be null.
Returns:
A SourceDataLine that can be used for purposes such as writing directly to a speaker.

getInputStream

public static javax.sound.sampled.AudioInputStream getInputStream(java.io.ByteArrayOutputStream byte_stream,
                                                                  javax.sound.sampled.AudioFormat audio_format)
Generates an AudioInputStream based on the given ByteArrayOutputStream and the given AudioFormat.

It is important to note that the ByteArrayOutputStream is turned into a fixed size array before playback, so additional information should not be added to it once this mehtod is called. This method is not intended for real-time streamed data, but rather pre-recorded data.

In general, the AudioFormat used for the AudioInputStream and the ByteArrayOutputStream should be the same.

Parameters:
byte_stream - The audio bytes to be played.
audio_format - Ther AudioFormat to use for encoding the AudioInputStream. Should also correspond to the AudioFormat of the bytes of the ByteArrayOutputStream.
Returns:
The AudioInputStream corresponding to the given samples and the given AudioFormat.

getInputStream

public static javax.sound.sampled.AudioInputStream getInputStream(byte[] audio_bytes,
                                                                  javax.sound.sampled.AudioFormat audio_format)
Generates an AudioInputStream based on the given array of bytes and the given AudioFormat. Because of the fixed size of the bytes array, this method is not intended for real-time streamed data, but rather pre-recorded data.

In general, the AudioFormat used for the AudioInputStream and the array of bytes should be the same.

Parameters:
audio_bytes - The audio bytes to be played.
audio_format - Ther AudioFormat to use for encoding the AudioInputStream. Should also correspond to the AudioFormat of audio_bytes.
Returns:
The AudioInputStream corresponding to the given samples and the given AudioFormat.

getInputStream

public static javax.sound.sampled.AudioInputStream getInputStream(java.io.File audio_file)
                                                           throws java.lang.Exception
Generates an AudioInputStream based on the contents of the given File.

Parameters:
audio_file - The audio file to extract the AudioInputStream from.
Returns:
The AudioInputStream extracted from the specified file.
Throws:
java.lang.Exception - Throws informative exceptions if the file is invalid or has an unsupported file format.

getConvertedAudioFormat

public static javax.sound.sampled.AudioFormat getConvertedAudioFormat(javax.sound.sampled.AudioFormat original_format)
Returns an AudioFormat with the same sampling rate and number of channels as the passed AudioFormat. If the bit depth is something other than 8 or 16 bits, then it is converted to 16 bits. The returned AudioFormat, also, will use big-endian signed linear PCM encoding, regardless of the passed format.

Parameters:
original_format - The format from which to extract sampling rate, bit depth and number of channels.
Returns:
The new format using big-endian signed linear PCM encoding and either 8 or 16 bit bit depth.

getConvertedAudioStream

public static javax.sound.sampled.AudioInputStream getConvertedAudioStream(javax.sound.sampled.AudioInputStream audio_input_stream)
Returns a copy of the given AudioInputStream that uses big-endian signed linear PCM encoding, regardless of the original encoding. The bit depth is converted to 16 bits if it is not 8 or 16 bits.

Parameters:
audio_input_stream - The AudioInputStream to convert to a new encoding.
Returns:
A copy of the passed AudioInputStream with the new encoding.

convertUnsupportedFormat

public static javax.sound.sampled.AudioInputStream convertUnsupportedFormat(javax.sound.sampled.AudioInputStream audio_input_stream)
Takes the given AudioInputStream and tests if it is playable. If not, converts it to big-Endian signed 16 bit linear PCM with the original sampling rate and number of channels. Useful for dealing with formats such as MP3s.

Parameters:
audio_input_stream - The audio data to test and possibly convert.
Returns:
The original AudioInputStream if it is playable, and a converted AudioInputStream if it is not.

extractSampleValues

public static double[][] extractSampleValues(javax.sound.sampled.AudioInputStream audio_input_stream)
                                      throws java.lang.Exception
Returns an array of doubles representing the samples for each channel in the given AudioInputStream.

This method is only compatible with audio with bit depths of 8 or 16 bits that is encoded using signed PCM with big endian byte order.

Parameters:
audio_input_stream - The AudioInputStream to convert to sample values.
Returns:
A 2-D array of sample values whose first indice indicates channel and whose second indice indicates sample number. In stereo, indice 0 corresponds to left and 1 to right. All samples should fall between -1 and +1.
Throws:
java.lang.Exception - Throws an informative exception if an invalid paramter is provided.

getBytesFromAudioInputStream

public static byte[] getBytesFromAudioInputStream(javax.sound.sampled.AudioInputStream audio_input_stream)
                                           throws java.lang.Exception
Generates an array of audio bytes based on the contents of the given AudioInputStream. Extracts all of the bytes available in the AudioInputStream at the moment that this method is called.

Parameters:
audio_input_stream - The AudioInputStream to extract the bytes from.
Returns:
The audio bytes extracted from the AudioInputStream. Has the same AudioFileFormat as the specified AudioInputStream.
Throws:
java.lang.Exception - Throws an exception if a problem occurs.

getNumberBytesNeeded

public static int getNumberBytesNeeded(double duration_in_seconds,
                                       javax.sound.sampled.AudioFormat audio_format)
Returns the number of bytes needed to store samples corresponding to audio of fixed duration.

Parameters:
duration_in_seconds - The duration, in seconds, of the audio that needs to be stored.
audio_format - The AudioFormat of the samples to be stored.
Returns:
The number of bytes needed to store the samples.

getNumberBytesNeeded

public static int getNumberBytesNeeded(int number_samples,
                                       javax.sound.sampled.AudioFormat audio_format)
Returns the number of bytes needed to store samples corresponding to the given number of samples in a given AudioFormat.

Parameters:
number_samples - The number of samples to be encoded.
audio_format - The AudioFormat of the samples to be stored.
Returns:
The number of bytes needed to store the samples.

convertToAudioInputStream

public static javax.sound.sampled.AudioInputStream convertToAudioInputStream(double[][] samples,
                                                                             javax.sound.sampled.AudioFormat audio_format)
                                                                      throws java.lang.Exception
Returns an AudioInputStream containing the given samples encoded using the given AudioFormat.

Parameters:
samples - The audio samples to convert. The first indice indicates channel and the second indicates sample number. Sample values vary from -1 to +1.
audio_format - The AudioFormat to use for encoding.
Returns:
The AudioInputStream representing the samples.
Throws:
java.lang.Exception - Throws an exception if an error occurs during conversion.

writeSamplesToBuffer

public static void writeSamplesToBuffer(double[][] sample_values,
                                        int bit_depth,
                                        byte[] buffer)
                                 throws java.lang.Exception
Writes the samples in the sample_values parameter to the buffer parameter. It is implicit that the caller knows what the sampling rate is and will be able to use it to correctly interperet the samples stored in the buffer after writing. Encoding is done using big endian signed PCM samples. Sample vaules greater than 1 or less than -1 are automatically clipped.

Parameters:
sample_values - A 2-D array of doubles whose first indice indicates channel and whose second indice indicates sample value. In stereo, indice 0 corresponds to left and 1 to right. All samples should fall between -1 and +1.
bit_depth - The bit depth to use for encoding the doubles stored in samples_to_modify. Only bit depths of 8 or 16 bits are accepted.
buffer - The buffer of bytes to write synthesized samples to.
Throws:
java.lang.Exception

clipSamples

public static double[][] clipSamples(double[][] original_samples)
                              throws java.lang.Exception
Clips the given samples so that all values below -1 are set to -1 and all values above 1 are set to 1. The returned array is a copy so the original array is not altered.

Parameters:
original_samples - A 2-D array of doubles whose first indice indicates channel and whose second indice indicates sample value. In stereo, indice 0 corresponds to left and 1 to right.
Returns:
A clipped copy of the original_samples parameter.
Throws:
java.lang.Exception - If a null parameter is passed.

findMaximumSampleValue

public static double findMaximumSampleValue(int bit_depth)
Returns the maximum possible value that a signed sample can have under the given bit depth. May be 1 or 2 values smaller than actual max, depending on specifics of encoding used.

Parameters:
bit_depth - The bit depth to examine.
Returns:
The maximum possible positive sample value as a double.

saveByteArrayOutputStream

public static void saveByteArrayOutputStream(java.io.ByteArrayOutputStream audio,
                                             javax.sound.sampled.AudioFormat audio_format,
                                             java.io.File save_file,
                                             javax.sound.sampled.AudioFileFormat.Type file_type)
                                      throws java.lang.Exception
Stores the samples on the ByteArrayOutputStream to the given file.

Parameters:
audio - The audio data to be recorded.
audio_format - The AudioFormat of the audio.
save_file - The file to save the audio to.
file_type - The type of audio file to save to.
Throws:
java.lang.Exception - Throws an exception if an error writing to the file occurs of if null parameters are passed.

saveToFile

public static void saveToFile(javax.sound.sampled.AudioInputStream audio_input_stream,
                              java.io.File file_to_save_to,
                              javax.sound.sampled.AudioFileFormat.Type file_type)
                       throws java.lang.Exception
Stores the samples coming in on the given AudioInputStream to the given file. Just repeats the functionality of the AudioSystem.write method, but with better documentation and exceptions. Useful for non-real-time recording, as well as possibly real-time recording.

Parameters:
audio_input_stream - The audio data to be recorded.
file_to_save_to - The file to save the audio to.
file_type - The type of audio file to save to.
Throws:
java.lang.Exception - Throws an exception if an error writing to the file occurs of if null parameters are passed.