comirva.audio.util
Class AudioPreProcessor

java.lang.Object
  comirva.audio.util.AudioPreProcessor

public class AudioPreProcessor
extends java.lang.Object

AudioPreProcessor

Description:

This class simplifies the access to audio streams. It frees you from taking care of the encoding of the input stream. The samples of the audio stream get converted and are stored as double values. The sample rate of the output stream can be specified. The output stream has only one channel. If the input stream has more than one channel, it will get reduced. If the input stream is encoded the Java Sound API will be used for decoding the stream. Also some of the audio conversion operations use the API. So be sure to have correctly configured your Java Audio System.

Internally the class has to ensure, that the input buffer is never null and always large enough. It also has to ensure that the number of bits per sample is either 8, 16, 24 or 32. Furthermore the frame size is given in bytes and is always the number of bits per sample divided by eight. If the sample size of the input stream is unknown (-1), the sample size internally used will be 16.

Field Summary

static float

DEFAULT_SAMPLE_RATE default sample rate of the output stream

Constructor Summary

AudioPreProcessor(javax.sound.sampled.AudioInputStream in)
An AudioPreProcessor encapsulates an AudioInputStream object permitting an easy access to the audio data.

AudioPreProcessor(javax.sound.sampled.AudioInputStream in, float sampleRate)
An AudioPreProcessor encapsulates an AudioInputStream object permitting an easy access to the audio data.

Method Summary

int	append(double[] buffer, int start, int len) Appends a specified number of samples to an array.
static javax.sound.sampled.AudioInputStream	convertBitsPerSample(javax.sound.sampled.AudioInputStream in, int bitsPerSample) Converts the number bits used to represent one sample within an AudioInputStream by returning a new a new stream using the given number of bits to represent one sample.
static javax.sound.sampled.AudioInputStream	convertByteOrder(javax.sound.sampled.AudioInputStream in, boolean isBigEndian) Converts the byte order of an AudioInputStream by returning a new a new stream using the given byte order (big/little Endian).
static javax.sound.sampled.AudioInputStream	convertChannels(javax.sound.sampled.AudioInputStream in, int channels) Converts the number of channels of an AudioInputStream by returning a new stream with the given number of channels.
static javax.sound.sampled.AudioInputStream	convertSampleRate(javax.sound.sampled.AudioInputStream in, float sampleRate) Converts the sample rate of an AudioInputStream by returning a new stream with the given sample rate.
static javax.sound.sampled.AudioInputStream	convertToPCM(javax.sound.sampled.AudioInputStream in) Converts an AudioInputStream with arbitrary encoding into an AudioInputStream with signed pulse code modulation (PCM_SIGNED).
int	fastSkip(int len) This method only skips on frame basis.
double[]	get(int len) Returns a specified number of samples.
float	getSampleRate() Returns the sample rate of the output stream.
int	skip(int len) Skips a specified number of samples.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_SAMPLE_RATE

public static final float DEFAULT_SAMPLE_RATE

default sample rate of the output stream

See Also:

Constant Field Values

Constructor Detail

AudioPreProcessor

public AudioPreProcessor(javax.sound.sampled.AudioInputStream in,
                         float sampleRate)
                  throws java.lang.IllegalArgumentException

An AudioPreProcessor encapsulates an AudioInputStream object permitting an easy access to the audio data. The audio samples of the output stream are in the range of [-1, 1].

Parameters:

in - AudioInputStream the audio input stream to encapsulate, must not be a null value

sampleRate - int the sampleRate of the output stream, must be greater than zero and less or equal the sample rate of the input stream, such that a conversion is possible; none integer values are rounded

Throws:

java.lang.IllegalArgumentException - raised if method contract is violated

AudioPreProcessor

public AudioPreProcessor(javax.sound.sampled.AudioInputStream in)
                  throws java.lang.IllegalArgumentException

An AudioPreProcessor encapsulates an AudioInputStream object permitting an easy access to the audio data. The default constructor uses the default sample rate for the output stream.

Parameters:

in - AudioInputStream the audio input stream to encapsulate, must not be a null value

Throws:

java.lang.IllegalArgumentException - raised if method contract is violated

Method Detail

getSampleRate

public float getSampleRate()

Returns the sample rate of the output stream.

Returns:

the sample rate of the output data

skip

public int skip(int len)
         throws java.lang.IllegalArgumentException,
                java.io.IOException

Skips a specified number of samples. Internally this is done by reading the specified number of bytes. This is because the skipping of encoded streams is only possible on frame basis.

Parameters:

len - number of samples to skip, must be a positive value

Returns:

the number of samples actually skipped within the input stream

Throws:

java.lang.IllegalArgumentException - raised if method contract is violated

java.io.IOException - if there are any problems regarding the inputstream

See Also:

fastSkip(int)

fastSkip

public int fastSkip(int len)
             throws java.lang.IllegalArgumentException,
                    java.io.IOException

This method only skips on frame basis. Therefore you cannot skip a precise number of bytes. You should at least skip one frame, or no bytes will be skipped. The real number of skipped bytes will be returned.

Parameters:

len - number of samples to skip, must be a positive value

Returns:

the number of samples actually skipped within the input stream

Throws:

java.lang.IllegalArgumentException - raised if method contract is violated

java.io.IOException - if there are any problems regarding the inputstream

get

public double[] get(int len)
             throws java.lang.IllegalArgumentException,
                    java.io.IOException

Returns a specified number of samples.

Parameters:

len - a number of samples to return, must be a positive value

Returns:

an array of samples, the size of the array is the number of samples read

Throws:

java.lang.IllegalArgumentException - raised if method contract is violated

java.io.IOException - if there are any problems regarding the inputstream

append

public int append(double[] buffer,
                  int start,
                  int len)
           throws java.lang.IllegalArgumentException,
                  java.io.IOException

Appends a specified number of samples to an array.

Parameters:

buffer - the buffer for the samples to be written in, must not be a null value and sufficient large to hold the number of samples specified by len

start - start index at which the new samples are filled into the array, must be greater equal zero; starting form this index there must be enough space to hold the number of samples specified by len

len - number of samples to be written into the buffer, must be greater than or equal to zero.

Returns:

number of samples actually read form the input stream

Throws:

java.lang.IllegalArgumentException - raised if method contract is violated

java.io.IOException - if there are any problems regarding the inputstream

convertToPCM

public static javax.sound.sampled.AudioInputStream convertToPCM(javax.sound.sampled.AudioInputStream in)
                                                         throws java.lang.IllegalArgumentException

Converts an AudioInputStream with arbitrary encoding into an AudioInputStream with signed pulse code modulation (PCM_SIGNED). If the input stream is already a PCM_SIGNED encoded stream this method has no effect. The sample size (in bits) of the input stream is unknown (-1) a default sample size of 16 bits will be used for the target format.The conversion is done using the Java Sound API. Therefore only conversion supported by your audio system can be performed.

Parameters:

in - AudioInputStream the original audio stream, must not be a null value

Returns:

AudioInputStream a pcm signed encoded audio stream

Throws:

java.lang.IllegalArgumentException - raised if method contract is violated or if the conversion is not supported by your audio system

convertSampleRate

public static javax.sound.sampled.AudioInputStream convertSampleRate(javax.sound.sampled.AudioInputStream in,
                                                                     float sampleRate)
                                                              throws java.lang.IllegalArgumentException

Converts the sample rate of an AudioInputStream by returning a new stream with the given sample rate. It might be useful to convert the audio stream to PCM_SIGNED first, since your audio system might not support the direct conversion with other encodings.

Parameters:

in - AudioInputStream the original audio stream, must not be a null value

sampleRate - float the sample rate to convert, must be greater null and less or equal the sample rate of the input stream

Returns:

AudioInputStream an audio stream with the given sample rate

Throws:

java.lang.IllegalArgumentException - raised if method contract is violated or if the conversion is not supported by your audio system

convertChannels

public static javax.sound.sampled.AudioInputStream convertChannels(javax.sound.sampled.AudioInputStream in,
                                                                   int channels)
                                                            throws java.lang.IllegalArgumentException

Converts the number of channels of an AudioInputStream by returning a new stream with the given number of channels. It might be useful to convert the audio stream to PCM_SIGNED first, since your audio system might not support the direct conversion with other encodings.

Parameters:

in - AudioInputStream the original audio stream, must not be a null value

channels - int the number of channels to convert to, must be greater null

Returns:

AudioInputStream an audio stream with the given number of channels

Throws:

java.lang.IllegalArgumentException - raised if method contract is violated or if the conversion is not supported by your audio system

convertBitsPerSample

public static javax.sound.sampled.AudioInputStream convertBitsPerSample(javax.sound.sampled.AudioInputStream in,
                                                                        int bitsPerSample)
                                                                 throws java.lang.IllegalArgumentException

Converts the number bits used to represent one sample within an AudioInputStream by returning a new a new stream using the given number of bits to represent one sample. It might be useful to convert the audio stream to PCM_SIGNED first, since your audio system might not support the direct conversion with other encodings. Another effect of the conversion to PCM_SIGNED is, that if the number of bits per sample is unknown (-1) the correct number of bits for the PCM_SIGNED stream will be used.

Parameters:

in - AudioInputStream the original audio stream, must not be a null value

bitsPerSample - int the number of bits per samples to convert to, must be either 8, 16, 24 or 32

Returns:

AudioInputStream an audio stream with the given number of bits per sample

Throws:

java.lang.IllegalArgumentException - raised if method contract is violated or if the conversion is not supported by your audio system

convertByteOrder

public static javax.sound.sampled.AudioInputStream convertByteOrder(javax.sound.sampled.AudioInputStream in,
                                                                    boolean isBigEndian)
                                                             throws java.lang.IllegalArgumentException

Converts the byte order of an AudioInputStream by returning a new a new stream using the given byte order (big/little Endian). It might be useful to convert the audio stream to PCM_SIGNED first, since your audio system meight not support the direct conversion with other encodings.

Parameters:

in - AudioInputStream the original audio stream, must not be a null value

isBigEndian - boolean true if the byte order in the resulting stream should be big-Endian, false otherwise (little-Endian)

Returns:

AudioInputStream an audio stream with the given byte order

Throws:

java.lang.IllegalArgumentException - raised if method contract is violated or if the conversion is not supported by your audio system