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

(package private) static int	CT_16SB
(package private) static int	CT_16SL
(package private) static int	CT_24SB
(package private) static int	CT_24SL
(package private) static int	CT_32SB
(package private) static int	CT_32SL
(package private) static int	CT_8S
(package private) static int	CT_8U
static float	DEFAULT_DITHER_BITS default number of bits to be dithered: 0.7f
(package private) static int	F_16
(package private) static int	F_24
(package private) static int	F_32
(package private) static int	F_8
(package private) static int	F_BIGENDIAN
(package private) static int	F_SAMPLE_WIDTH_MASK
(package private) static int	F_SIGNED

Method Summary

static void	byte2float(byte[] input, int inByteOffset, List output, int outOffset, int frameCount, AudioFormat format) Conversion function to convert an interleaved byte array to a List of interleaved float arrays.
(package private) static void	byte2floatGeneric(byte[] input, int inByteOffset, int inByteStep, float[] output, int outOffset, int sampleCount, AudioFormat format) Generic conversion function to convert a byte array to a float array.
(package private) static void	byte2floatGeneric(byte[] input, int inByteOffset, int inByteStep, float[] output, int outOffset, int sampleCount, int formatType) Central conversion function from a byte array to a normalized 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.
(package private) static void	checkSupportedSampleSize(int ssib, int channels, int frameSize) only allow "packed" samples -- currently no support for 18, 20, 24_32 bits.
static void	float2byte(List 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.
(package private) static void	float2byteGeneric(float[] input, int inOffset, byte[] output, int outByteOffset, int outByteStep, int sampleCount, AudioFormat format, float ditherBits) Generic conversion function to convert a float array to a byte array.
(package private) static void	float2byteGeneric(float[] input, int inOffset, byte[] output, int outByteOffset, int outByteStep, int sampleCount, int formatType, float ditherBits) Central conversion function from normalized float array to a byte array.
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.
(package private) static String	formatType2Str(int formatType) Return a string representation of this format
(package private) static int	getFormatType(AudioFormat format) Get the formatType code from the given format.
(package private) static int	getFormatType(int ssib, boolean signed, boolean bigEndian)
(package private) static int	getSampleSize(int formatType)

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

F_8

static final int F_8

See Also:

Constant Field Values

F_16

static final int F_16

See Also:

Constant Field Values

F_24

static final int F_24

See Also:

Constant Field Values

F_32

static final int F_32

See Also:

Constant Field Values

F_SAMPLE_WIDTH_MASK

static final int F_SAMPLE_WIDTH_MASK

See Also:

Constant Field Values

F_SIGNED

static final int F_SIGNED

See Also:

Constant Field Values

F_BIGENDIAN

static final int F_BIGENDIAN

See Also:

Constant Field Values

CT_8S

static final int CT_8S

See Also:

Constant Field Values

CT_8U

static final int CT_8U

See Also:

Constant Field Values

CT_16SB

static final int CT_16SB

See Also:

Constant Field Values

CT_16SL

static final int CT_16SL

See Also:

Constant Field Values

CT_24SB

static final int CT_24SB

See Also:

Constant Field Values

CT_24SL

static final int CT_24SL

See Also:

Constant Field Values

CT_32SB

static final int CT_32SB

See Also:

Constant Field Values

CT_32SL

static final int CT_32SL

See Also:

Constant Field Values

Method Detail

checkSupportedSampleSize

static void checkSupportedSampleSize(int ssib,
                                     int channels,
                                     int frameSize)

only allow "packed" samples -- currently no support for 18, 20, 24_32 bits.

Throws:

IllegalArgumentException

getFormatType

static int getFormatType(AudioFormat format)

Get the formatType code from the given format.

Throws:

IllegalArgumentException

getFormatType

static int getFormatType(int ssib,
                         boolean signed,
                         boolean bigEndian)

Throws:

IllegalArgumentException

getSampleSize

static int getSampleSize(int formatType)

formatType2Str

static String formatType2Str(int formatType)

Return a string representation of this format

byte2float

public static void byte2float(byte[] input,
                              int inByteOffset,
                              List output,
                              int outOffset,
                              int frameCount,
                              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:

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

byte2floatGeneric

static void byte2floatGeneric(byte[] input,
                              int inByteOffset,
                              int inByteStep,
                              float[] output,
                              int outOffset,
                              int sampleCount,
                              AudioFormat format)

Generic conversion function to convert a byte array to a float array.

Only PCM formats are accepted. The method will convert all bytes from input[inByteOffset] to input[inByteOffset + (sampleCount * (inByteStep - 1)] to samples from output[outOffset] to output[outOffset+sampleCount-1].

The format's channel count is ignored.

For mono data, set inByteOffset to format.getFrameSize().
For converting interleaved input data, multiply sampleCount by the number of channels and set inByteStep to format.getFrameSize() / format.getChannels().

Parameters:

sampleCount - number of samples to be written to output

inByteStep - how many bytes advance for each output sample in output.

Throws:

IllegalArgumentException - if one of the parameters is out of bounds

See Also:

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

byte2floatGeneric

static void byte2floatGeneric(byte[] input,
                              int inByteOffset,
                              int inByteStep,
                              float[] output,
                              int outOffset,
                              int sampleCount,
                              int formatType)

Central conversion function from a byte array to a normalized float array. In order to accomodate interleaved and non-interleaved samples, this method takes inByteStep as parameter which can be used to flexibly convert the data.

E.g.:
mono->mono: inByteStep=format.getFrameSize()
interleaved_stereo->interleaved_stereo: inByteStep=format.getFrameSize()/2, sampleCount*2
stereo->2 mono arrays:
---inByteOffset=0, outOffset=0, inByteStep=format.getFrameSize()
---inByteOffset=format.getFrameSize()/2, outOffset=1, inByteStep=format.getFrameSize()

float2byte

public static void float2byte(List 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)

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)

float2byteGeneric

static void float2byteGeneric(float[] input,
                              int inOffset,
                              byte[] output,
                              int outByteOffset,
                              int outByteStep,
                              int sampleCount,
                              AudioFormat format,
                              float ditherBits)

Generic conversion function to convert a float array to a byte array.

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

The format's channel count is ignored.

For mono data, set outByteOffset to format.getFrameSize().
For converting interleaved input data, multiply sampleCount by the number of channels and set outByteStep to format.getFrameSize() / format.getChannels().

Parameters:

sampleCount - number of samples in input to be converted.

outByteStep - how many bytes advance for each input sample in input.

Throws:

IllegalArgumentException - if one of the parameters is out of bounds

See Also:

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

float2byteGeneric

static void float2byteGeneric(float[] input,
                              int inOffset,
                              byte[] output,
                              int outByteOffset,
                              int outByteStep,
                              int sampleCount,
                              int formatType,
                              float ditherBits)

Central conversion function from normalized float array to a byte array. In order to accomodate interleaved and non-interleaved samples, this method takes outByteStep as parameter which can be used to flexibly convert the data.

E.g.:
mono->mono: outByteStep=format.getFrameSize()
interleaved stereo->interleaved stereo: outByteStep=format.getFrameSize()/2, sampleCount*2
2 mono arrays->stereo:
---inOffset=0, outByteOffset=0, outByteStep=format.getFrameSize()
---inOffset=1, outByteOffset=format.getFrameSize()/2, outByteStep=format.getFrameSize()