ddf.minim.javasound
Class FloatSampleTools

java.lang.Object
  extended by ddf.minim.javasound.FloatSampleTools

public class FloatSampleTools
extends java.lang.Object

Utility functions for handling data in normalized float arrays. Each sample is linear in the range of [-1.0f, +1.0f].

Currently, the following bit sizes are supported:

8-bit data can be unsigned or signed. All other data is only supported in signed encoding.

Author:
Florian Bomers
See Also:
FloatSampleBuffer

Field Summary
static float DEFAULT_DITHER_BITS
          default number of bits to be dithered: 0.7f
 
Method Summary
static void byte2float(byte[] input, int inByteOffset, java.util.List<float[]> output, int outOffset, int frameCount, javax.sound.sampled.AudioFormat format)
           
static void byte2float(byte[] input, int inByteOffset, java.util.List<float[]> output, int outOffset, int frameCount, javax.sound.sampled.AudioFormat format, boolean allowAddChannel)
          Conversion function to convert an interleaved byte array to a List of interleaved float arrays.
static void byte2float(byte[] input, int inByteOffset, java.lang.Object[] output, int outOffset, int frameCount, javax.sound.sampled.AudioFormat format)
           
static void byte2float(byte[] input, int inByteOffset, java.lang.Object[] output, int outOffset, int frameCount, javax.sound.sampled.AudioFormat format, boolean allowAddChannel)
           
static void byte2float(int channel, byte[] input, int inByteOffset, float[] output, int outOffset, int frameCount, javax.sound.sampled.AudioFormat format)
          Conversion function to convert one audio channel in an interleaved byte array to a float array.
static void byte2floatInterleaved(byte[] input, int inByteOffset, float[] output, int outOffset, int frameCount, javax.sound.sampled.AudioFormat format)
          Conversion function to convert an interleaved byte array to an interleaved float array.
static void float2byte(java.util.List<float[]> input, int inOffset, byte[] output, int outByteOffset, int frameCount, javax.sound.sampled.AudioFormat format, float ditherBits)
          Conversion function to convert a non-interleaved float audio data to an interleaved byte array.
static void float2byte(java.lang.Object[] input, int inOffset, byte[] output, int outByteOffset, int frameCount, javax.sound.sampled.AudioFormat format, float ditherBits)
           
static void float2byteInterleaved(float[] input, int inOffset, byte[] output, int outByteOffset, int frameCount, javax.sound.sampled.AudioFormat format, float ditherBits)
          Conversion function to convert an interleaved float array to an interleaved byte array.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_DITHER_BITS

public static final float DEFAULT_DITHER_BITS
default number of bits to be dithered: 0.7f

See Also:
Constant Field Values
Method Detail

byte2float

public static void byte2float(byte[] input,
                              int inByteOffset,
                              java.util.List<float[]> output,
                              int outOffset,
                              int frameCount,
                              javax.sound.sampled.AudioFormat format)
See Also:
byte2float(byte[] input, int inByteOffset, Object[] output, int outOffset, int frameCount, AudioFormat format, boolean allowAddChannel)

byte2float

public static void byte2float(byte[] input,
                              int inByteOffset,
                              java.lang.Object[] output,
                              int outOffset,
                              int frameCount,
                              javax.sound.sampled.AudioFormat format)
Parameters:
output - an array of float[] arrays
Throws:
java.lang.ArrayIndexOutOfBoundsException - if output does not format.getChannels() elements
See Also:
byte2float(byte[] input, int inByteOffset, Object[] output, int outOffset, int frameCount, AudioFormat format, boolean allowAddChannel)

byte2float

public static void byte2float(byte[] input,
                              int inByteOffset,
                              java.lang.Object[] output,
                              int outOffset,
                              int frameCount,
                              javax.sound.sampled.AudioFormat format,
                              boolean allowAddChannel)
Parameters:
output - an array of float[] arrays
allowAddChannel - if true, and output has fewer channels than format, then only output.length channels are filled
Throws:
java.lang.ArrayIndexOutOfBoundsException - if output does not format.getChannels() elements
See Also:
byte2float(byte[] input, int inByteOffset, Object[] output, int outOffset, int frameCount, AudioFormat format, boolean allowAddChannel)

byte2float

public static void byte2float(byte[] input,
                              int inByteOffset,
                              java.util.List<float[]> output,
                              int outOffset,
                              int frameCount,
                              javax.sound.sampled.AudioFormat format,
                              boolean allowAddChannel)
Conversion function to convert an interleaved byte array to a List of interleaved float arrays. The float arrays will contain normalized samples in the range [-1.0, +1.0]. The input array provides bytes in the format specified in format.

Only PCM formats are accepted. The method will convert all byte values from input[inByteOffset] to input[inByteOffset + (frameCount * format.getFrameSize()) - 1] to floats from output(n)[outOffset] to output(n)[outOffset + frameCount - 1]

Parameters:
input - the audio data in an byte array
inByteOffset - index in input where to start the conversion
output - list of float[] arrays which receive the converted audio data. if the list does not contain enough elements, or individual float arrays are not large enough, they are created.
outOffset - the start offset in output
frameCount - number of frames to be converted
format - the input format. Only packed PCM is allowed
allowAddChannel - if true, channels may be added to output to match the number of input channels, otherwise, only the first output.size() channels of input data are converted.
Throws:
java.lang.IllegalArgumentException - if one of the parameters is out of bounds
See Also:
byte2floatInterleaved(byte[],int,float[],int,int,AudioFormat)

byte2float

public static void byte2float(int channel,
                              byte[] input,
                              int inByteOffset,
                              float[] output,
                              int outOffset,
                              int frameCount,
                              javax.sound.sampled.AudioFormat format)
Conversion function to convert one audio channel in an interleaved byte array to a float array. The float array will contain normalized samples in the range [-1.0, +1.0]. The input array provides bytes in the format specified in format.

Only PCM formats are accepted. The method will convert all byte values from input[inByteOffset] to input[inByteOffset + (frameCount * format.getFrameSize()) - 1] to floats from output(n)[outOffset] to output(n)[outOffset + frameCount - 1]

Parameters:
channel - the channel number to extract from the input audio data
input - the audio data in an byte array
inByteOffset - index in input where to start the conversion
output - the of float array which receives the converted audio data.
outOffset - the start offset in output
frameCount - number of frames to be converted
format - the input format. Only packed PCM is allowed
Throws:
java.lang.IllegalArgumentException - if one of the parameters is out of bounds

byte2floatInterleaved

public static void byte2floatInterleaved(byte[] input,
                                         int inByteOffset,
                                         float[] output,
                                         int outOffset,
                                         int frameCount,
                                         javax.sound.sampled.AudioFormat format)
Conversion function to convert an interleaved byte array to an interleaved float array. The float array will contain normalized samples in the range [-1.0f, +1.0f]. The input array provides bytes in the format specified in format.

Only PCM formats are accepted. The method will convert all byte values from input[inByteOffset] to input[inByteOffset + (frameCount * format.getFrameSize()) - 1] to floats from output[outOffset] to output[outOffset + (frameCount * format.getChannels()) - 1]

Parameters:
input - the audio data in an byte array
inByteOffset - index in input where to start the conversion
output - the float array that receives the converted audio data
outOffset - the start offset in output
frameCount - number of frames to be converted
format - the input format. Only packed PCM is allowed
Throws:
java.lang.IllegalArgumentException - if one of the parameters is out of bounds
See Also:
byte2float(byte[],int,List,int,int,AudioFormat)

float2byte

public static void float2byte(java.util.List<float[]> input,
                              int inOffset,
                              byte[] output,
                              int outByteOffset,
                              int frameCount,
                              javax.sound.sampled.AudioFormat format,
                              float ditherBits)
Conversion function to convert a non-interleaved float audio data to an interleaved byte array. The float arrays contains normalized samples in the range [-1.0f, +1.0f]. The output array will receive bytes in the format specified in format. Exactly format.getChannels() channels are converted regardless of the number of elements in input. If input does not provide enough channels, an IllegalArgumentException is thrown.

Only PCM formats are accepted. The method will convert all samples from input(n)[inOffset] to input(n)[inOffset + frameCount - 1] to byte values from output[outByteOffset] to output[outByteOffset + (frameCount * format.getFrameSize()) - 1]

Dithering should be used when the output resolution is significantly lower than the original resolution. This includes if the original data was 16-bit and it is now converted to 8-bit, or if the data was generated in the float domain. No dithering need to be used if the original sample data was in e.g. 8-bit and the resulting output data has a higher resolution. If dithering is used, a sensitive value is DEFAULT_DITHER_BITS.

Parameters:
input - a List of float arrays with the input audio data
inOffset - index in the input arrays where to start the conversion
output - the byte array that receives the converted audio data
outByteOffset - the start offset in output
frameCount - number of frames to be converted.
format - the output format. Only packed PCM is allowed
ditherBits - if 0, do not dither. Otherwise the number of bits to be dithered
Throws:
java.lang.IllegalArgumentException - if one of the parameters is out of bounds
See Also:
DEFAULT_DITHER_BITS, float2byteInterleaved(float[],int,byte[],int,int,AudioFormat,float)

float2byte

public static void float2byte(java.lang.Object[] input,
                              int inOffset,
                              byte[] output,
                              int outByteOffset,
                              int frameCount,
                              javax.sound.sampled.AudioFormat format,
                              float ditherBits)
Parameters:
input - an array of float[] arrays
Throws:
java.lang.ArrayIndexOutOfBoundsException - if one of the parameters is out of bounds
See Also:
float2byte(Object[], int, byte[], int, int, AudioFormat, float)

float2byteInterleaved

public static void float2byteInterleaved(float[] input,
                                         int inOffset,
                                         byte[] output,
                                         int outByteOffset,
                                         int frameCount,
                                         javax.sound.sampled.AudioFormat format,
                                         float ditherBits)
Conversion function to convert an interleaved float array to an interleaved byte array. The float array contains normalized samples in the range [-1.0f, +1.0f]. The output array will receive bytes in the format specified in format.

Only PCM formats are accepted. The method will convert all samples from input[inOffset] to input[inOffset + (frameCount * format.getChannels()) - 1] to byte values from output[outByteOffset] to output[outByteOffset + (frameCount * format.getFrameSize()) - 1]

Dithering should be used when the output resolution is significantly lower than the original resolution. This includes if the original data was 16-bit and it is now converted to 8-bit, or if the data was generated in the float domain. No dithering need to be used if the original sample data was in e.g. 8-bit and the resulting output data has a higher resolution. If dithering is used, a sensitive value is DEFAULT_DITHER_BITS.

Parameters:
input - the audio data in normalized samples
inOffset - index in input where to start the conversion
output - the byte array that receives the converted audio data
outByteOffset - the start offset in output
frameCount - number of frames to be converted.
format - the output format. Only packed PCM is allowed
ditherBits - if 0, do not dither. Otherwise the number of bits to be dithered
Throws:
java.lang.IllegalArgumentException - if one of the parameters is out of bounds
See Also:
DEFAULT_DITHER_BITS, float2byte(List,int,byte[],int,int,AudioFormat,float)