jAudioFeatureExtractor.jAudioTools
Class AudioMethodsSynthesis

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

public class AudioMethodsSynthesis
extends java.lang.Object

A holder class for general static methods relating to sampled audio. Although all methods can be used individually, the synthesizeAndWriteToBuffer method provides a single way of accessing all of the functionality of the other methods.

The methods whose names beginning with "generateSamples" generate synthesized samples in the form of 2-D arrays of doubles, with dimensions of channel and time.

Arrays of this type can be turned into arrays of bytes in standard audio formats using the writeSamplesToBuffer method, or indirectly using the synthesizeAndWriteToBuffer method.

See the descriptions below for information on other available methods.

Author:
Cory McKay

Constructor Summary
AudioMethodsSynthesis()
           
 
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 void applyGainAndPanning(double[][] samples_to_modify, double gain, double panning)
          Apply an overall gain and panning to the provided set of samples.
static double[][] generateSamplesBasicTone(double fund_freq, int number_of_channels, float sample_rate, double max_frac_samp_rate, int total_samples_per_chan)
          Generates sample values for a tone consisting of a sinusoid at a fundamental frequency and additional sinusoids at 1.2 and 1.8 times this frequency.
static double[][] generateSamplesDecayPulse(double fund_freq, int number_of_channels, float sample_rate, double max_frac_samp_rate, int total_samples_per_chan)
          Generates sample values for a tone consisting of a single sinusoid that decays linearly to arrive at silence at the end of the audio.
static double[][] generateSamplesFMSweep(double fund_freq, int number_of_channels, float sample_rate, double max_frac_samp_rate, int total_samples_per_chan)
          Generates sample values for a tone consisting of a single sinusoid.
static double[][] generateSamplesSineWave(double fund_freq, int number_of_channels, float sample_rate, double max_frac_samp_rate, int total_samples_per_chan)
          Generates sample values for a tone consisting of a single sinusoid.
static double[][] generateSamplesStereoPanning(double fund_freq, int number_of_channels, float sample_rate, double max_frac_samp_rate, int total_samples_per_chan)
          Generates sample values for a sound consisting of a stereo sweep, starting with a relatively high frequency sinusoid on the left speaker and moving across to a sinusoid one octave lower on the right speaker.
static double[][] generateSamplesStereoPingpong(double fund_freq, int number_of_channels, float sample_rate, double max_frac_samp_rate, int total_samples_per_chan)
          Generates sample values for a sound consisting of a stereo pinpong, where the signal switches between the four channels four times per second.
static double[][] generateWhiteNoise(int number_of_channels, int total_samples_per_chan)
          Generates sample values for an audio wave consisting of randomly generated white noise.
static java.lang.String[] getSynthesisNames()
          Returns the names of the types of synthesis that can be performed.
static int getSynthesisTypeCode(java.lang.String synthesis_type_name)
          Returns the code for use in the synthesis_type parameter of the synthesizeAndWriteToBuffer method that specifies to the given type of synthesis.
static double[][] synthesizeAndWriteToBuffer(byte[] buffer, double duration, javax.sound.sampled.AudioFormat audio_format, int synthesis_type, double gain, double panning, double fundamental_frequency, double max_frac_samp_rate, double click_avoid_env_length)
          Populates the given buffer with synthesized sound samples using the given AudioFormat.
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

AudioMethodsSynthesis

public AudioMethodsSynthesis()
Method Detail

synthesizeAndWriteToBuffer

public static double[][] synthesizeAndWriteToBuffer(byte[] buffer,
                                                    double duration,
                                                    javax.sound.sampled.AudioFormat audio_format,
                                                    int synthesis_type,
                                                    double gain,
                                                    double panning,
                                                    double fundamental_frequency,
                                                    double max_frac_samp_rate,
                                                    double click_avoid_env_length)
                                             throws java.lang.Exception
Populates the given buffer with synthesized sound samples using the given AudioFormat. Alternatively, returns the sample values in the form of a 2-D array of doubles if the buffer parameter is null. If the buffer parameter is not null, then null is returned and the buffer is filled. Uses the provided synthesis type, overall gain, panning and (sometimes) fudamental to synthesize the audiofrequency.

The size of the buffer parameter along with the AudioFormat used determines the duration of the sound to be generated if the buffer parameter is not null. It is otherwise determined by the duration parameter.

Parameters:
buffer - The buffer of bytes to write synthesized samples to. May be null if prefer samples as a 2-D array of doubles rather than an array of bytes.
duration - The time in seconds to generate. Is ignored if the buffer parameter is not null.
audio_format - The AudioFormat to use for encoding samples to the buffer parameter. Only audio_formats consisting of bit depths of 8 or 16 bits are accepted, and encoding must consist of big endian signed PCM samples.
synthesis_type - The code indicating what type of synthesis is to be used to fill the buffer parameter. These codes can be accessed using the getSynthesisTypeCode method.
gain - The overall loudness of the samples. This value must be between 0.0 and 1.0, with 0.0 being silence and 1.0 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.0 and +1.0, with -1.0 corresponding to full amplitude on the left channel and silence on the right, and +1.0 corresponding to the reverse. A value of 0 indicates equal balance.
fundamental_frequency - The fundamental frequency of the sound to be synthesiszed. Is ignored for some types of synthesis.
max_frac_samp_rate - Used to determine the maximum allowable frequency partial that will be permitted to be synthesized. This is to avoid aliasing, and generally a value of 0.45 is best, with values below 0.5 always needed to ensure protection against aliasing. The maximum allowable frequency is determined by multiplying this value by the sampling rate contained in the audio_format paramter.
click_avoid_env_length - The duration in seconds of an envelope applied at the beginning and end of the synthesized audio in order to avoid clicks. Linear attenuation is used for this amount of time on each end.
Returns:
If the buffer parameter is not null, then null is returned. If the buffer parameter is null, then something is returned: 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.
Throws:
java.lang.Exception - Throws an informative exception if an invalid parameter is specified.

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.

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.

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.

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

getSynthesisTypeCode

public static int getSynthesisTypeCode(java.lang.String synthesis_type_name)
                                throws java.lang.Exception
Returns the code for use in the synthesis_type parameter of the synthesizeAndWriteToBuffer method that specifies to the given type of synthesis.

Parameters:
synthesis_type_name - The name of the type of synthesis to use to generate audio.
Returns:
The code corresponding to the given type of synthesis.
Throws:
java.lang.Exception

getSynthesisNames

public static java.lang.String[] getSynthesisNames()
Returns the names of the types of synthesis that can be performed.

Returns:
An array of strings consisting of the names of available types of synthesis.

generateSamplesSineWave

public static double[][] generateSamplesSineWave(double fund_freq,
                                                 int number_of_channels,
                                                 float sample_rate,
                                                 double max_frac_samp_rate,
                                                 int total_samples_per_chan)
                                          throws java.lang.Exception
Generates sample values for a tone consisting of a single sinusoid. An identical signal is provided to each channel.

This is an example of a standard sample generating method. All of the methods of this type implemented in this class produce a 2-D array of doubles whose first indice corresponds to channel and whose second incice corresponds to sample value. In mono, there is only one channel, and in stereo indice 0 indicates left and indice 1 indicates right. All samples generated by this type of method should fall between -1 and +1.

Parameters:
fund_freq - The fundamental frequency of the tone to be generated.
number_of_channels - The number of channels to generate samples for.
sample_rate - The sampling rate to use for generating samples.
max_frac_samp_rate - Used to determine the maximum allowable frequency partial that will be permitted to be synthesized. This is to avoid aliasing, and generally a value of 0.45 is best, with values below 0.5 always needed to ensure protection against aliasing. The maximum allowable frequency is determined by multiplying this value by the sampling rate contained in the sample_rate paramter.
total_samples_per_chan - The total number of samples to generate per channel. Combined with sample_rate, this can be used to find the time duration of the sound to be generated.
Returns:
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 fall between -1 and +1.
Throws:
java.lang.Exception - Throws an exception if invalid parameters provided.

generateSamplesBasicTone

public static double[][] generateSamplesBasicTone(double fund_freq,
                                                  int number_of_channels,
                                                  float sample_rate,
                                                  double max_frac_samp_rate,
                                                  int total_samples_per_chan)
                                           throws java.lang.Exception
Generates sample values for a tone consisting of a sinusoid at a fundamental frequency and additional sinusoids at 1.2 and 1.8 times this frequency. All three sinusoids have equal amplitudes. An identical signal is provided to each channel.

This is an example of a standard sample generating method. All of the methods of this type implemented in this class produce a 2-D array of doubles whose first indice corresponds to channel and whose second incice corresponds to sample value. In mono, there is only one channel, and in stereo indice 0 indicates left and indice 1 indicates right. All samples generated by this type of method should fall between -1 and +1.

Parameters:
fund_freq - The fundamental frequency of the tone to be generated.
number_of_channels - The number of channels to generate samples for.
sample_rate - The sampling rate to use for generating samples.
max_frac_samp_rate - Used to determine the maximum allowable frequency partial that will be permitted to be synthesized. This is to avoid aliasing, and generally a value of 0.45 is best, with values below 0.5 always needed to ensure protection against aliasing. The maximum allowable frequency is determined by multiplying this value by the sampling rate contained in the sample_rate paramter.
total_samples_per_chan - The total number of samples to generate per channel. Combined with sample_rate, this can be used to find the time duration of the sound to be generated.
Returns:
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 fall between -1 and +1.
Throws:
java.lang.Exception - Throws an exception if invalid parameters provided.

generateSamplesStereoPanning

public static double[][] generateSamplesStereoPanning(double fund_freq,
                                                      int number_of_channels,
                                                      float sample_rate,
                                                      double max_frac_samp_rate,
                                                      int total_samples_per_chan)
                                               throws java.lang.Exception
Generates sample values for a sound consisting of a stereo sweep, starting with a relatively high frequency sinusoid on the left speaker and moving across to a sinusoid one octave lower on the right speaker.

This is an example of a standard sample generating method. All of the methods of this type implemented in this class produce a 2-D array of doubles whose first indice corresponds to channel and whose second incice corresponds to sample value. In mono, there is only one channel, and in stereo indice 0 indicates left and indice 1 indicates right. All samples generated by this type of method should fall between -1 and +1.

Parameters:
fund_freq - The frequency of the tone on the left and twice the frequency of the tone on the right.
number_of_channels - The number of channels to generate samples for.
sample_rate - The sampling rate to use for generating samples.
max_frac_samp_rate - Used to determine the maximum allowable frequency partial that will be permitted to be synthesized. This is to avoid aliasing, and generally a value of 0.45 is best, with values below 0.5 always needed to ensure protection against aliasing. The maximum allowable frequency is determined by multiplying this value by the sampling rate contained in the sample_rate paramter.
total_samples_per_chan - The total number of samples to generate per channel. Combined with sample_rate, this can be used to find the time duration of the sound to be generated.
Returns:
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 fall between -1 and +1.
Throws:
java.lang.Exception - Throws an exception if invalid parameters provided.

generateSamplesStereoPingpong

public static double[][] generateSamplesStereoPingpong(double fund_freq,
                                                       int number_of_channels,
                                                       float sample_rate,
                                                       double max_frac_samp_rate,
                                                       int total_samples_per_chan)
                                                throws java.lang.Exception
Generates sample values for a sound consisting of a stereo pinpong, where the signal switches between the four channels four times per second. The signal on the right is 0.8 times the frequency of the signal on the right.

This is an example of a standard sample generating method. All of the methods of this type implemented in this class produce a 2-D array of doubles whose first indice corresponds to channel and whose second incice corresponds to sample value. In mono, there is only one channel, and in stereo indice 0 indicates left and indice 1 indicates right. All samples generated by this type of method should fall between -1 and +1.

Parameters:
fund_freq - The frequency of the tone on the left and 1.25 times the frequency of the tone on the right.
number_of_channels - The number of channels to generate samples for.
sample_rate - The sampling rate to use for generating samples.
max_frac_samp_rate - Used to determine the maximum allowable frequency partial that will be permitted to be synthesized. This is to avoid aliasing, and generally a value of 0.45 is best, with values below 0.5 always needed to ensure protection against aliasing. The maximum allowable frequency is determined by multiplying this value by the sampling rate contained in the sample_rate paramter.
total_samples_per_chan - The total number of samples to generate per channel. Combined with sample_rate, this can be used to find the time duration of the sound to be generated.
Returns:
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 fall between -1 and +1.
Throws:
java.lang.Exception - Throws an exception if invalid parameters provided.

generateSamplesFMSweep

public static double[][] generateSamplesFMSweep(double fund_freq,
                                                int number_of_channels,
                                                float sample_rate,
                                                double max_frac_samp_rate,
                                                int total_samples_per_chan)
                                         throws java.lang.Exception
Generates sample values for a tone consisting of a single sinusoid. that undergoes a gradual linear frequency increase from 1/10 of the provided fundamental_frequency at the beginning of the sound to the fundamental_frequency at the end of the sound. An identical signal is provided to each channel.

This is an example of a standard sample generating method. All of the methods of this type implemented in this class produce a 2-D array of doubles whose first indice corresponds to channel and whose second incice corresponds to sample value. In mono, there is only one channel, and in stereo indice 0 indicates left and indice 1 indicates right. All samples generated by this type of method should fall between -1 and +1.

Parameters:
fund_freq - The final frequency of the tone to be generated.
number_of_channels - The number of channels to generate samples for.
sample_rate - The sampling rate to use for generating samples.
max_frac_samp_rate - Used to determine the maximum allowable frequency partial that will be permitted to be synthesized. This is to avoid aliasing, and generally a value of 0.45 is best, with values below 0.5 always needed to ensure protection against aliasing. The maximum allowable frequency is determined by multiplying this value by the sampling rate contained in the sample_rate paramter.
total_samples_per_chan - The total number of samples to generate per channel. Combined with sample_rate, this can be used to find the time duration of the sound to be generated.
Returns:
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 fall between -1 and +1.
Throws:
java.lang.Exception - Throws an exception if invalid parameters provided.

generateSamplesDecayPulse

public static double[][] generateSamplesDecayPulse(double fund_freq,
                                                   int number_of_channels,
                                                   float sample_rate,
                                                   double max_frac_samp_rate,
                                                   int total_samples_per_chan)
                                            throws java.lang.Exception
Generates sample values for a tone consisting of a single sinusoid that decays linearly to arrive at silence at the end of the audio. An identical signal is provided to each channel.

This is an example of a standard sample generating method. All of the methods of this type implemented in this class produce a 2-D array of doubles whose first indice corresponds to channel and whose second incice corresponds to sample value. In mono, there is only one channel, and in stereo indice 0 indicates left and indice 1 indicates right. All samples generated by this type of method should fall between -1 and +1.

Parameters:
fund_freq - The fundamental frequency of the tone to be generated.
number_of_channels - The number of channels to generate samples for.
sample_rate - The sampling rate to use for generating samples.
max_frac_samp_rate - Used to determine the maximum allowable frequency partial that will be permitted to be synthesized. This is to avoid aliasing, and generally a value of 0.45 is best, with values below 0.5 always needed to ensure protection against aliasing. The maximum allowable frequency is determined by multiplying this value by the sampling rate contained in the sample_rate paramter.
total_samples_per_chan - The total number of samples to generate per channel. Combined with sample_rate, this can be used to find the time duration of the sound to be generated.
Returns:
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 fall between -1 and +1.
Throws:
java.lang.Exception - Throws an exception if invalid parameters provided.

generateWhiteNoise

public static double[][] generateWhiteNoise(int number_of_channels,
                                            int total_samples_per_chan)
                                     throws java.lang.Exception
Generates sample values for an audio wave consisting of randomly generated white noise.

This is an example of a standard sample generating method. All of the methods of this type implemented in this class produce a 2-D array of doubles whose first indice corresponds to channel and whose second incice corresponds to sample value. In mono, there is only one channel, and in stereo indice 0 indicates left and indice 1 indicates right. All samples generated by this type of method should fall between -1 and +1.

Parameters:
number_of_channels - The number of channels to generate samples for.
total_samples_per_chan - The total number of samples to generate per channel.
Returns:
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 fall between -1 and +1.
Throws:
java.lang.Exception - Throws an exception if invalid parameters provided.