mckay.utilities.sound.sampled
Class AudioMethodsDSP

java.lang.Object
  extended by mckay.utilities.sound.sampled.AudioMethodsDSP

public class AudioMethodsDSP
extends java.lang.Object

A holder class for general static methods relating to processing signals in the form of samples stored as arrays of doubles.


Constructor Summary
AudioMethodsDSP()
           
 
Method Summary
static void applyClickAvoidanceAttenuationEnvelope(double[][] sample_values, double click_avoid_env_length, float sample_rate)
          Applies linear attenuation to either end of the given samples.
static double[][] applyGain(double[][] samples, double gain)
          Applies a gain to the given samples.
static void applyGainAndPanning(double[][] samples_to_modify, double gain, double panning)
          Apply an overall gain and panning to the provided set of samples.
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 double convertSampleToTime(int sample, float sampling_rate)
          Returns the time corresponding to the given sample indice with the given sampling rate.
static int convertTimeToSample(double time, float sampling_rate)
          Returns the sample corresponding to the given time with the given sampling rate.
static double findMaximumSampleValue(int bit_depth)
          Returns the maximum possible value that a signed sample can have under the given bit depth.
static double[] getAutoCorrelation(double[] signal, int min_lag, int max_lag)
          Calculates the auto-correlation of the given signal.
static double[] getAutoCorrelationLabels(double sampling_rate, int min_lag, int max_lag)
          Returns the bin labels for each bin of an auto-correlation calculation that involved the given paremeters (most likely using the getAutoCorrelation method).
static double[][] getCopyOfSamples(double[][] original_samples)
          Returns a copy of the given array of samples.
static double[] getSamplesMixedDownIntoOneChannel(double[][] audio_samples)
          Returns the given set of samples as a set of samples mixed down into one channel.
static double[] normalizeSamples(double[] samples_to_normalize)
          Normalizes the given samples so that the absolute value of the highest sample amplitude is 1.
static double[][] normalizeSamples(double[][] samples_to_normalize)
          Normalizes the given samples dependantly so that the absolute value of the highest sample amplitude is 1.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AudioMethodsDSP

public AudioMethodsDSP()
Method Detail

applyGain

public static double[][] applyGain(double[][] samples,
                                   double gain)
Applies a gain to the given samples. Note that a negative gain effectively applies a phase shift of pi. There is no guarantee that the returned samples will be between -1 and +1. The returned samples are copies, so changes to them will not affect the original samples.

Parameters:
samples - Audio samles to modify, 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.
gain - The gain to apply.
Returns:
The given audio samples after the application of the given gain.

applyGainAndPanning

public static void applyGainAndPanning(double[][] samples_to_modify,
                                       double gain,
                                       double panning)
                                throws java.lang.Exception
Apply an overall gain and panning to the provided set of samples. This set of samples will be modified by this method. All samples in the provided set of samples should be between -1 and +1 before processing, and the same should be true after processing.

It should be noted that gain and panning do not amplify samples, but rather attenuate them. The provided samples should already take advantage of the full available dynamic range (-1 to +1), and a gain of 1 and and a panning of 0 will maintain this. Other values of gain or panning will cause attenuation.

Parameters:
samples_to_modify - 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.
gain - The overall gain to apply to the samples. This value must be between 0 and 1, with 0 being silence and 1 being maximum amplitude.
panning - The relative strength of the two stereo channels. This parameter is ignored in non-stereo cases. Value must be between -1 and +1, with -1 corresponding to full amplitude on the left channel and silence on the right, and +1 corresponding to the reverse. A value of 0 indicates a balance, and no attenuation is applied to either channel.
Throws:
java.lang.Exception - Throws an exception if an invalid gain or panning value is specified, of if the samples_to_modify parameter is null or contains empty channels.

getSamplesMixedDownIntoOneChannel

public static double[] getSamplesMixedDownIntoOneChannel(double[][] audio_samples)
Returns the given set of samples as a set of samples mixed down into one channel.

Parameters:
audio_samples - Audio samles to modify, 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.
Returns:
The given audio samples mixed down, with equal gain, into one channel.

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.

normalizeSamples

public static double[] normalizeSamples(double[] samples_to_normalize)
Normalizes the given samples so that the absolute value of the highest sample amplitude is 1. Does nothing if also samples are 0.

Parameters:
samples_to_normalize - The samples to normalize.
Returns:
Returns a copy of the given samples after normalization.

normalizeSamples

public static double[][] normalizeSamples(double[][] samples_to_normalize)
Normalizes the given samples dependantly so that the absolute value of the highest sample amplitude is 1. Does nothing if all samples are 0.

Parameters:
samples_to_normalize - The samples to normalize. The first indice denotes channel and the second denotes sample number.
Returns:
Returns a copy of the given samples after normalization.

getCopyOfSamples

public static double[][] getCopyOfSamples(double[][] original_samples)
Returns a copy of the given array of samples.

Parameters:
original_samples - Audio samles to modify, usually with a minimum value of 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.
Returns:
A copy of the original_samples parameter.

convertTimeToSample

public static int convertTimeToSample(double time,
                                      float sampling_rate)
Returns the sample corresponding to the given time with the given sampling rate.

Parameters:
time - The time in seconds to convert to a sample indice.
sampling_rate - The sampling rate of the audio in question.
Returns:
The corresponding sample indice.

convertSampleToTime

public static double convertSampleToTime(int sample,
                                         float sampling_rate)
Returns the time corresponding to the given sample indice with the given sampling rate.

Parameters:
sample - The sample indice to convert to time.
sampling_rate - The sampling rate of the audio in question.
Returns:
The corresponding time in seconds.

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.

getAutoCorrelation

public static double[] getAutoCorrelation(double[] signal,
                                          int min_lag,
                                          int max_lag)
Calculates the auto-correlation of the given signal. The auto-correlation is only calculated between the given lags.

The getAutoCorrelationLabels method can be called to find the labels in Hz for each of the returned bins.

Parameters:
signal - The digital signal to auto-correlate.
min_lag - The minimum lag in samples to look for in the auto-correlation.
max_lag - The maximum lag in samples to look for in the auto-correaltion.
Returns:
The auto-correlation for each lag from min_lag to max_lag. Entry 0 corresponds to min_lag, and the last entry corresponds to max_lag.

getAutoCorrelationLabels

public static double[] getAutoCorrelationLabels(double sampling_rate,
                                                int min_lag,
                                                int max_lag)
Returns the bin labels for each bin of an auto-correlation calculation that involved the given paremeters (most likely using the getAutoCorrelation method).

Parameters:
sampling_rate - The sampling rate that was used to encode the signal that was auto-correlated.
min_lag - The minimum lag in samples that was used in the auto-correlation.
max_lag - The maximum lag in samples that was used in the auto-correlation.
Returns:
The labels, in Hz, for the corresponding bins produced by the getAutoCorrelation method.

applyClickAvoidanceAttenuationEnvelope

public static void applyClickAvoidanceAttenuationEnvelope(double[][] sample_values,
                                                          double click_avoid_env_length,
                                                          float sample_rate)
                                                   throws java.lang.Exception
Applies linear attenuation to either end of the given samples. This is done in order to eliminate clicks. The attenuation on each side is determined by the click_avoid_env_length parameter.

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.
click_avoid_env_length - The duration in seconds of the envelope applied at the beginning and end of the synthesized audio in order to avoid clicks.
sample_rate - The sampling rate that was used to encode the sample_values.
Throws:
java.lang.Exception - Throws an exception if an invalid parameter is passed.