comirva.audio.util
Class AudioPreProcessor

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

public class AudioPreProcessor
extends 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
protected  int frameSize
           
protected  AudioInputStream in
           
protected  boolean isBigEndian
           
protected  float sampleRate
           
 
Constructor Summary
AudioPreProcessor(AudioInputStream in)
          An AudioPreProcessor encapsulates an AudioInputStream object permitting an easy access to the audio data.
AudioPreProcessor(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 AudioInputStream convertBitsPerSample(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 AudioInputStream convertByteOrder(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 AudioInputStream convertChannels(AudioInputStream in, int channels)
          Converts the number of channels of an AudioInputStream by returning a new stream with the given number of channels.
static AudioInputStream convertSampleRate(AudioInputStream in, float sampleRate)
          Converts the sample rate of an AudioInputStream by returning a new stream with the given sample rate.
static AudioInputStream convertToPCM(AudioInputStream in)
          Converts an AudioInputStream with arbitrary encoding into an AudioInputStream with signed pulse code modulation (PCM_SIGNED).
protected  void convertToSample(byte[] in, int len, double[] out, int start)
          This method is internally used to convert the bytes of the input byte stream to a steam of float pointing samples.
 int fastSkip(int len)
          This method only skips on frame basis.
protected  void finalize()
           
 double[] get(int len)
          Returns a specified number of samples.
static AudioPreProcessor getAudioPreProcessor(File input, float sampleRate)
           
 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
clone, 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

in

protected AudioInputStream in

sampleRate

protected float sampleRate

frameSize

protected int frameSize

isBigEndian

protected boolean isBigEndian
Constructor Detail

AudioPreProcessor

public AudioPreProcessor(AudioInputStream in,
                         float sampleRate)
                  throws 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:
IllegalArgumentException - raised if method contract is violated

AudioPreProcessor

public AudioPreProcessor(AudioInputStream in)
                  throws 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:
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 IllegalArgumentException,
                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:
IllegalArgumentException - raised if method contract is violated
IOException - if there are any problems regarding the inputstream
See Also:
fastSkip(int)

fastSkip

public int fastSkip(int len)
             throws IllegalArgumentException,
                    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:
IllegalArgumentException - raised if method contract is violated
IOException - if there are any problems regarding the inputstream

get

public double[] get(int len)
             throws IllegalArgumentException,
                    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:
IllegalArgumentException - raised if method contract is violated
IOException - if there are any problems regarding the inputstream

append

public int append(double[] buffer,
                  int start,
                  int len)
           throws IllegalArgumentException,
                  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:
IllegalArgumentException - raised if method contract is violated
IOException - if there are any problems regarding the inputstream

convertToSample

protected void convertToSample(byte[] in,
                               int len,
                               double[] out,
                               int start)
This method is internally used to convert the bytes of the input byte stream to a steam of float pointing samples. The samples are in the range of [-1, 1]. It is assumed that bitsPerSample / 8 == frameSize. No checks for correct parameter values are performed, since this method is of internal use only. All calling methods within this class must ensure the preconditions.

Parameters:
in - byte[] input date, bytes of the audio input stream
len - int number of valid bytes in the input buffer
out - double[] output buffer for the db-SPL values
start - int start index within the output buffer

convertToPCM

public static AudioInputStream convertToPCM(AudioInputStream in)
                                     throws 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:
IllegalArgumentException - raised if method contract is violated or if the conversion is not supported by your audio system

convertSampleRate

public static AudioInputStream convertSampleRate(AudioInputStream in,
                                                 float sampleRate)
                                          throws 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:
IllegalArgumentException - raised if method contract is violated or if the conversion is not supported by your audio system

convertChannels

public static AudioInputStream convertChannels(AudioInputStream in,
                                               int channels)
                                        throws 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:
IllegalArgumentException - raised if method contract is violated or if the conversion is not supported by your audio system

convertBitsPerSample

public static AudioInputStream convertBitsPerSample(AudioInputStream in,
                                                    int bitsPerSample)
                                             throws 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:
IllegalArgumentException - raised if method contract is violated or if the conversion is not supported by your audio system

convertByteOrder

public static AudioInputStream convertByteOrder(AudioInputStream in,
                                                boolean isBigEndian)
                                         throws 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:
IllegalArgumentException - raised if method contract is violated or if the conversion is not supported by your audio system

getAudioPreProcessor

public static AudioPreProcessor getAudioPreProcessor(File input,
                                                     float sampleRate)
                                              throws UnsupportedAudioFileException,
                                                     IOException
Throws:
UnsupportedAudioFileException
IOException

finalize

protected void finalize()
                 throws Throwable
Overrides:
finalize in class Object
Throws:
Throwable