ddf.minim
Class FloatSampleTools

java.lang.Object
  ddf.minim.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
• 16-bit
• packed 24-bit (stored in 3 bytes)
• 32-bit

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.ArrayList output, int outOffset, int frameCount, javax.sound.sampled.AudioFormat format) Conversion function to convert an interleaved byte array to a List of interleaved float arrays.
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 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	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

equals, 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.ArrayList output,
                              int outOffset,
                              int frameCount,
                              javax.sound.sampled.AudioFormat format)

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.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(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

Throws:

java.lang.IllegalArgumentException - if one of the parameters is out of bounds

See Also:

byte2floatInterleaved(byte[],int,float[],int,int,AudioFormat)

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 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)

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)