jAudioFeatureExtractor.jAudioTools
Class AudioSamples

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

public class AudioSamples
extends java.lang.Object

A class for holding audio samples and associated audio formatting information. Samples are stored as arrays of doubles, generally for use in analysis and signal processing. Samples are stored maintaining any channel segregation as well as mixed down to a single channel. Values can vary between -1 and +1.

Each object of this class is assigned a string at instantiation that can be used externally as a reference. Although not used internally by the methods of this class, it will generally be best to assign a unique value to this string, such as a filename.

Includes constructors for generating and storing the samples from AudioInputStreams, audio files or existing arrays of sample values.

Includes methods for accessing samples as a whole or as segments, and also for returning the samples after having been broken into equally sized windows of specified sizes. A method is also present for saving the samples to a File. Methods are also available for checking if any sample values fall out of the allowable ranges (i.e. between -1 and +1) and for normalizing samples so that the maximum amplitude will have an absolute value of 1. Methods are also available for getting copies of objects of this class as well as for getting formatted information about them. The samples can also be changed externally.

Author:
Cory McKay

Field Summary
protected  javax.sound.sampled.AudioFormat audio_format
          The AudioFormat used to encode the samples field.
protected  double[][] channel_samples
          Audio samles, with a minimum value of -1 and a maximum value of +1.
protected  double[] samples
          Audio samles, with a minimum value of -1 and a maximum value of +1.
protected  java.lang.String unique_ID
          A unique identifier that external objects can use to identify each individual object of this class.
 
Constructor Summary
AudioSamples(javax.sound.sampled.AudioInputStream audio_input_stream, java.lang.String unique_identifier, boolean normalize_if_clipped)
          Store the given AudioInputStream as samples and the corresponding AudioFormat.
AudioSamples(double[][] audio_samples, javax.sound.sampled.AudioFormat audio_format, java.lang.String unique_identifier, boolean normalize_if_clipped)
          Store the given samples with the associated AudioFormat.
AudioSamples(double[][] audio_samples, float sampling_rate, java.lang.String unique_identifier, boolean normalize_if_clipped)
          Store the given samples with the associated sampling rate.
AudioSamples(java.io.File audio_file, java.lang.String unique_identifier, boolean normalize_if_clipped)
          Store the given audio file as samples and the corresponding AudioFormat.
 
Method Summary
 double checkChannelSegregatedSamplesForClipping()
          Returns the maximum deviation in the stored sample values outside the permissible range of -1 to +1.
 double checkMixedDownSamplesForClipping()
          Returns the maximum deviation in the stored mixed down sample values outside the permissible range of -1 to +1.
 javax.sound.sampled.AudioFormat getAudioFormat()
          Returns the AudioFormat associated with the stored samples.
 javax.sound.sampled.AudioInputStream getAudioInputStreamChannelSegregated()
          Returns the stored audio samples in the form of an AudioInputStream.
 javax.sound.sampled.AudioInputStream getAudioInputStreamChannelSegregated(double start_time, double end_time)
          Returns the stored audio samples between the given times in the form of an AudioInputStream.
 javax.sound.sampled.AudioInputStream getAudioInputStreamChannelSegregated(int start_sample, int end_sample)
          Returns the stored audio samples between the given samples in the form of an AudioInputStream.
 javax.sound.sampled.AudioInputStream getAudioInputStreamMixedDown()
          Returns the stored audio samples in the form of an AudioInputStream.
 javax.sound.sampled.AudioInputStream getAudioInputStreamMixedDown(double start_time, double end_time)
          Returns the stored audio samples between the given times in the form of an AudioInputStream.
 javax.sound.sampled.AudioInputStream getAudioInputStreamMixedDown(int start_sample, int end_sample)
          Returns the stored audio samples between the given samples in the form of an AudioInputStream.
 AudioSamples getCopyOfAudioSamples()
          Returns a copy of this AudioSamples object.
 double getDuration()
          Returns the total length of the stored audio in seconds.
 double getMaximumAmplitude()
          Returns the maximum amplitude value in all of the channels.
 int getNumberChannels()
          Returns the number of channels of stored audio.
 int getNumberSamplesPerChannel()
          Returns the total number of samples per channel in the stored audio.
 java.lang.String getRecordingInfo()
          Returns a formatted description of the AudioFormat of the samples as well as the number of samples per channel, the duration in seconds of the recording and the maximum sample amplitude.
 double[][] getSamplesChannelSegregated()
          Returns the stored audio samples.
 double[][] getSamplesChannelSegregated(double start_time, double end_time)
          Returns the stored audio samples between the given times in secondes.
 double[][] getSamplesChannelSegregated(int start_sample, int end_sample)
          Returns the stored audio samples between the given sample indices.
 double[] getSamplesMixedDown()
          Returns the stored audio samples.
 double[] getSamplesMixedDown(double start_time, double end_time)
          Returns the stored audio samples between the given times.
 double[] getSamplesMixedDown(int start_sample, int end_sample)
          Returns the stored audio samples between the given sample indices.
 double[][][] getSampleWindowsChannelSegregated(double window_duration)
          Returns the stored audio samples divided into windows of equal lengths.
 double[][][] getSampleWindowsChannelSegregated(int window_size)
          Returns the stored audio samples divided into windows of equal lengths.
 double[][] getSampleWindowsMixedDown(double window_duration)
          Returns the stored audio samples divided into windows of equal lengths.
 double[][] getSampleWindowsMixedDown(int window_size)
          Returns the stored audio samples divided into windows of equal lengths.
 float getSamplingRate()
          Returns the sampling rate that is associated with the stored samples.
 double getSamplingRateAsDouble()
          Returns the sampling rate that is associated with the stored samples.
 java.lang.String getUniqueIdentifier()
          Returns the identifier assigned to an object of this class at instantiation.
 void normalize()
          Normalizes both the channel segregated samples and the samples mixed down into one channel so that the absolute value of the highest sample amplitude is 1.
 void normalizeChannelSegretatedSamples()
          Normalizes the channel segregated samples so that the absolute value of the highest sample amplitude is 1.
 void normalizeIfClipped()
          Checks the mixed down and channel segregated samples separately to see if either one has values outside of the permitted range (-1 to +1).
 void normalizeMixedDownSamples()
          Normalizes the samples mixed down into one channel so that the absolute value of the highest sample amplitude is 1.
 void saveAudio(java.io.File save_file, boolean multi_channel, javax.sound.sampled.AudioFileFormat.Type save_file_type, boolean normalize_if_clipped)
          Saves the currently stored samples to the specified file.
 void setSamples(double[][] new_samples)
          Updates the samples stored in an object of this class.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

unique_ID

protected java.lang.String unique_ID
A unique identifier that external objects can use to identify each individual object of this class. Not used internally by objects of this class.


samples

protected double[] samples
Audio samles, with a minimum value of -1 and a maximum value of +1. If audio is multi-channel, all channels are mixed down into this one channel.


channel_samples

protected double[][] channel_samples
Audio samles, with a minimum value of -1 and a maximum value of +1. Is set to null if only one channel of audio is present. First indice corresponds to channel and second indice corresponds to sample number.


audio_format

protected javax.sound.sampled.AudioFormat audio_format
The AudioFormat used to encode the samples field. Will always involve big-endian signed linear PCM encoding and a bit depth of eith 8 or 16 bits.

Constructor Detail

AudioSamples

public AudioSamples(java.io.File audio_file,
                    java.lang.String unique_identifier,
                    boolean normalize_if_clipped)
             throws java.lang.Exception
Store the given audio file as samples and the corresponding AudioFormat.

IMPORTANT: Note that, regardless of the AudioFormat in the given file, it will be converted and stored using big-endian signed linear PCM encoding. Sampling rate and number of channels is maintained, but bit depth will be changed to 16 bits if it is not either 8 or 16 bits.

Parameters:
audio_file - A reference to an audio file from which to extract and store samples as double values.
unique_identifier - The string that will be used by external objects to uniquely identify the instantiated AudioSamples object.
normalize_if_clipped - If set to true, then normalizes audio so the absolute value of the highest amplitude sample is 1. Does this if and only if one or more of the samples is outside the allowable range of sample values (-1 to 1). If set to false, then does not normalize, regardless of sample values.
Throws:
java.lang.Exception - Throws an informative exception if the samples cannot be extracted from the file.

AudioSamples

public AudioSamples(javax.sound.sampled.AudioInputStream audio_input_stream,
                    java.lang.String unique_identifier,
                    boolean normalize_if_clipped)
             throws java.lang.Exception
Store the given AudioInputStream as samples and the corresponding AudioFormat.

IMPORTANT: Note that the AudioFormat in the AudioInputStream will be converted and stored as big-endian signed linear PCM encoding with. Sampling rate and number of channels is maintained, but bit depth will be changed to 16 bits if it is not either 8 or 16 bits.

Parameters:
audio_input_stream - An AudioInputStream from which to extract and store samples as double values.
unique_identifier - The string that will be used by external objects to uniquely identify the instantiated AudioSamples object.
normalize_if_clipped - If set to true, then normalizes audio so the absolute value of the highest amplitude sample is 1. Does this if and only if one or more of the samples is outside the allowable range of sample values (-1 to 1). If set to false, then does not normalize, regardless of sample values.
Throws:
java.lang.Exception - Throws an informative exception if the samples cannot be extracted from the AudioInputStream.

AudioSamples

public AudioSamples(double[][] audio_samples,
                    javax.sound.sampled.AudioFormat audio_format,
                    java.lang.String unique_identifier,
                    boolean normalize_if_clipped)
             throws java.lang.Exception
Store the given samples with the associated AudioFormat.

IMPORTANT: Note that, regardless of the given AudioFormat, it will be converted and samples will be stored as big-endian signed linear PCM encoding. Sampling rate and number of channels is maintained, but bit depth will be changed to 16 bits if it is not either 8 or 16 bits.

Parameters:
audio_samples - Audio samles to store, with a minimum value of -1 and a maximum value of +1. The first indice corresponds to the channel and the second indice corresponds to the sample number.
audio_format - The AudioFormat to use for interpereting the given samples.
unique_identifier - The string that will be used by external objects to uniquely identify the instantiated AudioSamples object.
normalize_if_clipped - If set to true, then normalizes audio so the absolute value of the highest amplitude sample is 1. Does this if and only if one or more of the samples is outside the allowable range of sample values (-1 to 1). If set to false, then does not normalize, regardless of sample values.
Throws:
java.lang.Exception - Throws an informative exception if the samples cannot be extracted from the audio_samples.

AudioSamples

public AudioSamples(double[][] audio_samples,
                    float sampling_rate,
                    java.lang.String unique_identifier,
                    boolean normalize_if_clipped)
             throws java.lang.Exception
Store the given samples with the associated sampling rate. A default AudioFormat is generated.

Parameters:
audio_samples - Audio samles to store, with a minimum value of -1 and a maximum value of +1. The first indice corresponds to the channel and the second indice corresponds to the sample number.
sampling_rate - The sampling rate to associate with the given samples.
unique_identifier - The string that will be used by external objects to uniquely identify the instantiated AudioSamples object.
normalize_if_clipped - If set to true, then normalizes audio so the absolute value of the highest amplitude sample is 1. Does this if and only if one or more of the samples is outside the allowable range of sample values (-1 to 1). If set to false, then does not normalize, regardless of sample values.
Throws:
java.lang.Exception - Throws an informative exception if the samples cannot be extracted from the audio_samples.
Method Detail

getCopyOfAudioSamples

public AudioSamples getCopyOfAudioSamples()
                                   throws java.lang.Exception
Returns a copy of this AudioSamples object. All fields are copies, not references to the original fields, so no changes made to the copies will change the original

Returns:
A copy of this object.
Throws:
java.lang.Exception - Throws an informative exception if the copy cannot be made.

getRecordingInfo

public java.lang.String getRecordingInfo()
Returns a formatted description of the AudioFormat of the samples as well as the number of samples per channel, the duration in seconds of the recording and the maximum sample amplitude.

Returns:
A formatted description of the recording.

getUniqueIdentifier

public java.lang.String getUniqueIdentifier()
Returns the identifier assigned to an object of this class at instantiation.

Returns:
The identifier of this object.

getAudioFormat

public javax.sound.sampled.AudioFormat getAudioFormat()
Returns the AudioFormat associated with the stored samples.

Returns:
The AudioFormat associated with the stored samples.

getSamplingRate

public float getSamplingRate()
Returns the sampling rate that is associated with the stored samples.

Returns:
The sampling rate associated with the stored samples in the form of a float.

getSamplingRateAsDouble

public double getSamplingRateAsDouble()
Returns the sampling rate that is associated with the stored samples.

Returns:
The sampling rate associated with the stored samples in the form of a double.

getNumberSamplesPerChannel

public int getNumberSamplesPerChannel()
Returns the total number of samples per channel in the stored audio.

Returns:
The total number of samples per channel in the stored audio.

getDuration

public double getDuration()
Returns the total length of the stored audio in seconds.

Returns:
The length of the stored audio in seconds.

getNumberChannels

public int getNumberChannels()
Returns the number of channels of stored audio.

Returns:
The number of channels of stored audio.

getSamplesMixedDown

public double[] getSamplesMixedDown()
Returns the stored audio samples. If the audio data originally consisted of multiple channels, then the returned samples represent the audio after mixing down into a single channel.

Returns:
The audio samples stored in this object. These have a minimum value of -1 and a maximum value of +1.

getSamplesMixedDown

public double[] getSamplesMixedDown(int start_sample,
                                    int end_sample)
                             throws java.lang.Exception
Returns the stored audio samples between the given sample indices. If the audio data originally consisted of multiple channels, then the returned samples represent the audio after mixing down into a single channel.

Parameters:
start_sample - The sample indice of the first sample to return. Must be 0 or higher and must be less than end_sample.
end_sample - The sample indice of the last sample to return. Must be less than the total number of samples.
Returns:
The audio samples stored in this object. These have a minimum value of -1 and a maximum value of +1. Only the samples within (and including) the given sample indices are returned. Only one (potentially combined) channel of audio is returned.
Throws:
java.lang.Exception - Throws an informative exception if the given start sample or end sample are outside acceptable ranges.

getSamplesMixedDown

public double[] getSamplesMixedDown(double start_time,
                                    double end_time)
                             throws java.lang.Exception
Returns the stored audio samples between the given times. If the audio data originally consisted of multiple channels, then the returned samples represent the audio after mixing down into a single channel.

Parameters:
start_time - The time, in seconds, of the first sample to return. Must be 0 or higher and must be less than end_time.
end_time - The time, in seconds, of the last sample to return. return. Must be less than or equal to the total duration.
Returns:
The audio samples stored in this object. These have a minimum value of -1 and a maximum value of +1. Only the samples within (and including) the given times are returned. Only one (potentially combined) channel of audio is returned.
Throws:
java.lang.Exception - Throws an informative exception if the given times are outside acceptable ranges.

getSampleWindowsMixedDown

public double[][] getSampleWindowsMixedDown(int window_size)
                                     throws java.lang.Exception
Returns the stored audio samples divided into windows of equal lengths. The last window is extended past the length of the stored samples if necessary and is zero padded. If the audio data originally consisted of multiple channels, then the returned samples represent the audio after mixing down into a single channel.

Parameters:
window_size - The length in samples of the windows that the samples are to divided into.
Returns:
The audio samples stored in this object after being broken into equally sized windows of the specified size. The last window is zero-padded if necessary. The samples have a minimum value of -1 and a maximum value of +1. Only one (potentially combined) channel of audio is returned. The first indice specifies the window and the second indice specifies the sample index within the window.
Throws:
java.lang.Exception - Throws an exception if a negative or 0 window size is specified.

getSampleWindowsMixedDown

public double[][] getSampleWindowsMixedDown(double window_duration)
                                     throws java.lang.Exception
Returns the stored audio samples divided into windows of equal lengths. The last window is extended past the length of the stored samples if necessary and is zero padded. If the audio data originally consisted of multiple channels, then the returned samples represent the audio after mixing down into a single channel.

Parameters:
window_duration - The duration in seconds of the windows that the samples are divided into.
Returns:
The audio samples stored in this object after being broken into equally sized windows of the specified size. The last window is zero-padded if necessary. The samples have a minimum value of -1 and a maximum value of +1. Only one (potentially combined) channel of audio is returned. The first indice specifies the window and the second indice specifies the sample index within the window.
Throws:
java.lang.Exception - Throws an exception if a negative or 0 window size is specified.

getAudioInputStreamMixedDown

public javax.sound.sampled.AudioInputStream getAudioInputStreamMixedDown()
                                                                  throws java.lang.Exception
Returns the stored audio samples in the form of an AudioInputStream. If the audio data originally consisted of multiple channels, then the returned samples represent the audio after mixing down into a single channel.

Returns:
The entire set of samples mixed down into one channel. Returned in the form of an AudioInputStream.
Throws:
java.lang.Exception - Throws an exception if a a problem occurs during conversion.

getAudioInputStreamMixedDown

public javax.sound.sampled.AudioInputStream getAudioInputStreamMixedDown(int start_sample,
                                                                         int end_sample)
                                                                  throws java.lang.Exception
Returns the stored audio samples between the given samples in the form of an AudioInputStream. If the audio data originally consisted of multiple channels, then the returned samples represent the audio after mixing down into a single channel.

Parameters:
start_sample - The sample indice of the first sample to return. Must be 0 or higher and must be less than end_sample.
end_sample - The sample indice of the last sample to return. Must be less than the total number of samples.
Returns:
The specified set of samples mixed down into one channel. Returned in the form of an AudioInputStream.
Throws:
java.lang.Exception - Throws an informative exception if the given start sample or end sample are outside acceptable ranges or if error occurs during conversion.

getAudioInputStreamMixedDown

public javax.sound.sampled.AudioInputStream getAudioInputStreamMixedDown(double start_time,
                                                                         double end_time)
                                                                  throws java.lang.Exception
Returns the stored audio samples between the given times in the form of an AudioInputStream. If the audio data originally consisted of multiple channels, then the returned samples represent the audio after mixing down into a single channel.

Parameters:
start_time - The time, in seconds, of the first sample to return. Must be 0 or higher and must be less than end_time.
end_time - The time, in seconds, of the last sample to return. return. Must be less than or equal to the total duration.
Returns:
The specified set of samples mixed down into one channel. Returned in the form of an AudioInputStream.
Throws:
java.lang.Exception - Throws an informative exception if the given start time or end time are outside acceptable ranges or if error occurs during conversion.

getSamplesChannelSegregated

public double[][] getSamplesChannelSegregated()
Returns the stored audio samples.

Returns:
The audio samples stored in this object. These have a minimum value of -1 and a maximum value of +1. The first indice corresponds to the channel and the second indice corresponds to the sample number.

getSamplesChannelSegregated

public double[][] getSamplesChannelSegregated(int start_sample,
                                              int end_sample)
                                       throws java.lang.Exception
Returns the stored audio samples between the given sample indices.

Parameters:
start_sample - The sample indice of the first sample to return. Must be 0 or higher and must be less than end_sample.
end_sample - The sample indice of the last sample to return. Must be less than the total number of samples.
Returns:
The audio samples stored in this object. These have a minimum value of -1 and a maximum value of +1. The first indice corresponds to the channel and the second indice corresponds to the sample number.
Throws:
java.lang.Exception - Throws an informative exception if the given start sample or end sample are outside acceptable ranges.

getSamplesChannelSegregated

public double[][] getSamplesChannelSegregated(double start_time,
                                              double end_time)
                                       throws java.lang.Exception
Returns the stored audio samples between the given times in secondes.

Parameters:
start_time - The time, in seconds, of the first sample to return. Must be 0 or higher and must be less than end_time.
end_time - The time, in seconds, of the last sample to return. return. Must be less than or equal to the total duration.
Returns:
The audio samples stored in this object. These have a minimum value of -1 and a maximum value of +1. The first indice corresponds to the channel and the second indice corresponds to the sample number. Only the samples within (and including) the given times are returned.
Throws:
java.lang.Exception - Throws an informative exception if the given times are outside acceptable ranges.

getSampleWindowsChannelSegregated

public double[][][] getSampleWindowsChannelSegregated(int window_size)
                                               throws java.lang.Exception
Returns the stored audio samples divided into windows of equal lengths. The last window is extended past the length of the stored samples if necessary and is zero padded.

Parameters:
window_size - The length in samples of the windows that the samples are to divided into.
Returns:
The audio samples stored in this object after being broken into equally sized windows of the specified size. The last window is zero-padded if necessary. The samples have a minimum value of -1 and a maximum value of +1. The first indice specifies the channel, the second indice specifies the window and the third indice specifies the sample index within the window.
Throws:
java.lang.Exception - Throws an exception if a negative or 0 window size is specified.

getSampleWindowsChannelSegregated

public double[][][] getSampleWindowsChannelSegregated(double window_duration)
                                               throws java.lang.Exception
Returns the stored audio samples divided into windows of equal lengths. The last window is extended past the length of the stored samples if necessary and is zero padded.

Parameters:
window_duration - The duration in seconds of the windows that the samples are divided into.
Returns:
The audio samples stored in this object after being broken into equally sized windows of the specified size. The last window is zero-padded if necessary. The samples have a minimum value of -1 and a maximum value of +1. The first indice specifies the channel, the second indice specifies the window and the third indice specifies the sample index within the window.
Throws:
java.lang.Exception - Throws an exception if a negative or 0 window size is specified.

getAudioInputStreamChannelSegregated

public javax.sound.sampled.AudioInputStream getAudioInputStreamChannelSegregated()
                                                                          throws java.lang.Exception
Returns the stored audio samples in the form of an AudioInputStream.

Returns:
The entire set of samples returned in the form of an AudioInputStream.
Throws:
java.lang.Exception - Throws an exception if a a problem occurs during conversion.

getAudioInputStreamChannelSegregated

public javax.sound.sampled.AudioInputStream getAudioInputStreamChannelSegregated(int start_sample,
                                                                                 int end_sample)
                                                                          throws java.lang.Exception
Returns the stored audio samples between the given samples in the form of an AudioInputStream.

Parameters:
start_sample - The sample indice of the first sample to return. Must be 0 or higher and must be less than end_sample.
end_sample - The sample indice of the last sample to return. Must be less than the total number of samples.
Returns:
The specified set of samples returned in the form of an of an AudioInputStream.
Throws:
java.lang.Exception - Throws an informative exception if the given start sample or end sample are outside acceptable ranges or if error occurs during conversion.

getAudioInputStreamChannelSegregated

public javax.sound.sampled.AudioInputStream getAudioInputStreamChannelSegregated(double start_time,
                                                                                 double end_time)
                                                                          throws java.lang.Exception
Returns the stored audio samples between the given times in the form of an AudioInputStream.

Parameters:
start_time - The time, in seconds, of the first sample to return. Must be 0 or higher and must be less than end_time.
end_time - The time, in seconds, of the last sample to return. return. Must be less than or equal to the total duration.
Returns:
The specified set of samples returned in the form of an of an AudioInputStream.
Throws:
java.lang.Exception - Throws an informative exception if the given start time or end time are outside acceptable ranges or if error occurs during conversion.

saveAudio

public void saveAudio(java.io.File save_file,
                      boolean multi_channel,
                      javax.sound.sampled.AudioFileFormat.Type save_file_type,
                      boolean normalize_if_clipped)
               throws java.lang.Exception
Saves the currently stored samples to the specified file.

WARNING: Will automatically overwrite given file if it already exists.

Parameters:
save_file - The File to save the audio samples to.
multi_channel - If this is true, then any separate channels are saved on separate channels. If this is false, then saved file has only one channel, onto which all samples have been mixed down to.
save_file_type - The AudioFileFormat.Type to use for saving the audio. A default value is used if this is null.
normalize_if_clipped - If set to true, then normalizes audio so the absolute value of the highest amplitude sample is 1. Does this if and only if one or more of the samples to save is outside the allowable range of sample values (-1 to 1). If set to false, then does not normalize, regardless of sample values. WARNING: This will normalize the samples stored in memory as well.
Throws:
java.lang.Exception - Throws an informative exception if the samples cannot be succesfully saved to the file.

normalizeIfClipped

public void normalizeIfClipped()
Checks the mixed down and channel segregated samples separately to see if either one has values outside of the permitted range (-1 to +1). If so, normalizes the appropriate samples so that the absolute value of the highest amplitude sample is 1.


getMaximumAmplitude

public double getMaximumAmplitude()
Returns the maximum amplitude value in all of the channels.

Returns:
The maximum amplitude (absolute) value in any one channel.

checkMixedDownSamplesForClipping

public double checkMixedDownSamplesForClipping()
Returns the maximum deviation in the stored mixed down sample values outside the permissible range of -1 to +1. Returns -1.0 if all samples fall withing the permissible range.

Returns:
The maximum deviation from the permissible sample values. -1 if all sample values fall within the allowable range.

checkChannelSegregatedSamplesForClipping

public double checkChannelSegregatedSamplesForClipping()
Returns the maximum deviation in the stored sample values outside the permissible range of -1 to +1. Returns -1.0 if all samples fall withing the permissible range. Does this dependantly over all channels, but not over the mixed down channels (unless only one channel is present).

Returns:
The maximum deviation from the permissible sample values. -1 if all sample values fall within the allowable range.

normalizeMixedDownSamples

public void normalizeMixedDownSamples()
Normalizes the samples mixed down into one channel so that the absolute value of the highest sample amplitude is 1. Does nothing if all samples are 0.


normalizeChannelSegretatedSamples

public void normalizeChannelSegretatedSamples()
Normalizes the channel segregated samples so that the absolute value of the highest sample amplitude is 1. Does nothing if all samples are 0.


normalize

public void normalize()
Normalizes both the channel segregated samples and the samples mixed down into one channel so that the absolute value of the highest sample amplitude is 1. Does nothing if all samples are 0.


setSamples

public void setSamples(double[][] new_samples)
                throws java.lang.Exception
Updates the samples stored in an object of this class. The given new samples must have the same number of channels as the original data. The stored samples are a copy of the given samples, so changes to the passed array will not affect the information stored here.

Parameters:
new_samples - Audio samles to store, usually with a minimum value of -1 and a maximum value of +1. The first indice corresponds to the channel and the second indice corresponds to the sample number.
Throws:
java.lang.Exception - Throws an exception if an invalid parameter is passed (null entries, non-matching number of channels or samples per channel.