org.tritonus.share.sampled

Class FloatSampleTools

java.lang.Object

org.tritonus.share.sampled.FloatSampleTools

public class FloatSampleTools
extends 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)
• unpacked 24-bit (stored in 4 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

Fields

Modifier and Type	Field and Description
static float	DEFAULT_DITHER_BITS default number of bits to be dithered: 0.7f

Method Summary

Modifier and Type	Method and Description
static void	byte2float(byte[] input, int inByteOffset, List<float[]> output, int outOffset, int frameCount, AudioFormat format)
static void	byte2float(byte[] input, int inByteOffset, List<float[]> output, int outOffset, int frameCount, 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, Object[] output, int outOffset, int frameCount, AudioFormat format)
static void	byte2float(byte[] input, int inByteOffset, Object[] output, int outOffset, int frameCount, AudioFormat format, boolean allowAddChannel)
static void	byte2float(int channel, byte[] input, int inByteOffset, float[] output, int outOffset, int frameCount, 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, AudioFormat format) Conversion function to convert an interleaved byte array to an interleaved float array.
static void	float2byte(List<float[]> input, int inOffset, byte[] output, int outByteOffset, int frameCount, AudioFormat format, float ditherBits) Conversion function to convert a non-interleaved float audio data to an interleaved byte array.
static void	float2byte(Object[] input, int inOffset, byte[] output, int outByteOffset, int frameCount, AudioFormat format, float ditherBits)
static void	float2byteInterleaved(float[] input, int inOffset, byte[] output, int outByteOffset, int frameCount, 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,
                              List<float[]> output,
                              int outOffset,
                              int frameCount,
                              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,
                              Object[] output,
                              int outOffset,
                              int frameCount,
                              AudioFormat format)

Parameters:

output - an array of float[] arrays

Throws:

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,
                              Object[] output,
                              int outOffset,
                              int frameCount,
                              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:

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,
                              List<float[]> output,
                              int outOffset,
                              int frameCount,
                              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:

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,
                              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:

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,
                                         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:

IllegalArgumentException - if one of the parameters is out of bounds

See Also:

byte2float(byte[],int,List,int,int,AudioFormat)

float2byte

public static void float2byte(List<float[]> input,
                              int inOffset,
                              byte[] output,
                              int outByteOffset,
                              int frameCount,
                              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:

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(Object[] input,
                              int inOffset,
                              byte[] output,
                              int outByteOffset,
                              int frameCount,
                              AudioFormat format,
                              float ditherBits)

Parameters:

input - an array of float[] arrays

Throws:

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,
                                         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:

IllegalArgumentException - if one of the parameters is out of bounds

See Also:

DEFAULT_DITHER_BITS, float2byte(List,int,byte[],int,int,AudioFormat,float)