lava.riff.wave
Class WaveStreamReader

java.lang.Object
  |
  +--lava.riff.wave.WaveStreamReader

Direct Known Subclasses:

PcmWaveStreamReader

public abstract class WaveStreamReader

extends java.lang.Object

Base class for all .wav stream decoders.

Details: A WaveStreamReader reads and returns information, including format data and wave samples, from a RIFF-wave file. WaveStreamReader is the abstract superclass of all wave decoders, such as PcmWaveFileReader.

Field Summary

protected WaveFormatChunk	fmt Parsed format chunk.
protected RiffStreamReader	riff Parses RIFF stream.

Constructor Summary

protected

WaveStreamReader(IRiffInput rais) Sets wave stream source.

Method Summary

void	close() Closes wave stream.
int	countChannels() Returns number of channels.
abstract long	countSamples() Returns number of samples.
protected int	findChunk(int from, int tag) Returns chunk reader by tag.
abstract void	freeSamples(long when, int duration) Releases samples from buffer.
WaveAdtlChunkReader	getAdtlChunkReader() Returns ADTL chunk parser.
abstract int	getBitsPerChannelSample() Returns number of bits per channel sample.
abstract int	getChannelSampleSize() Returns size of individual channel sample.
protected RiffChunkReader	getChunkReader(int n) Returns chunk reader by index.
WaveCuePointList	getCuePoints() Parses cue points chunk.
WaveFormatChunk	getFormatChunk() Returns format chunk.
abstract java.lang.Object	readSamples(long when, java.lang.Object dest, int dest_from, int duration) Reads and decodes samples.

Methods inherited from class java.lang.Object

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

Field Detail

riff

protected final RiffStreamReader riff

Parses RIFF stream.

Details: This member is the RiffStreamReader used by this WaveStreamReader uses to parse the wave stream, which is a special type of RIFF stream.

fmt

protected WaveFormatChunk fmt

Parsed format chunk.

Details: fmt represents the parsed format chunk from this wave stream. This member must be set by the subclass, or some methods in this superclass which require access to the chunk will throw an exception.

Constructor Detail

WaveStreamReader

protected WaveStreamReader(IRiffInput rais)
                    throws java.io.IOException

Sets wave stream source.

Details: This constructor sets the stream that this WaveStreamReader will decode.

Parameters:

raise - the stream

Method Detail

getChunkReader

protected RiffChunkReader getChunkReader(int n)
                                  throws java.io.IOException

Returns chunk reader by index.

Details: This method returns a RiffChunkReader for the n^th chunk in this wave stream (where the first chunk has index 0). Beware that if the requested chunk hasn't been reached yet, the RIFF source may be read until the chunk is found or until the EOS is reached. This may place a strain on the buffering mechanism of the underlying IRiffInput. null is returned if the chunk doesn't exist.

Parameters:

n - the chunk number

Returns:

the chunk reader

findChunk

protected int findChunk(int from,
                        int tag)
                 throws java.io.IOException

Returns chunk reader by tag.

Details: This method searchs, starting with the from^th chunk, for a chunk whose tag (chunk type identifier) is equal to tag. Beware that if the chunk being sought hasn't been reached yet, the RIFF source may be read until the chunk is found, or until the RIFF source has been exhausted, possibly placing a strain on the buffering mechanism of the underlying IRiffInput. null is returned if the chunk can't be found.

Parameters:

from - the starting chunk

tag - the chunk type identifier

Returns:

the chunk reader

getCuePoints

public WaveCuePointList getCuePoints()
                              throws java.io.IOException

Parses cue points chunk.

Details: This method (partially) parses the wave stream's cue point list, if there is one, and returns an object which can be used to query specific details from the list. If this wave stream has no cue point list, this method returns null.

Returns:

the cue points list

getAdtlChunkReader

public WaveAdtlChunkReader getAdtlChunkReader()
                                       throws java.io.IOException

Returns ADTL chunk parser.

Details: This method returns a WaveAdtlChunkReader, or an object capable of parsing this stream's ADTL (associated data list) chunk. The ADTL chunk can contain a wealth of information abou this stream's cue points. If this wave stream has no ADTL chunk, this method returns null.

Returns:

the WaveAdtlChunkReader

getFormatChunk

public WaveFormatChunk getFormatChunk()

Returns format chunk.

Details: This method returns an object representing the parsed format chunk. The returned object is a mutable clone of the original.

Returns:

the format chunk

countChannels

public int countChannels()

Returns number of channels.

Details: This method returns the number of audio channels represented by this wave stream. Typically, 1 indicates monoaural sound and 2 indicates stereo sound.

Returns:

channel count

getBitsPerChannelSample

public abstract int getBitsPerChannelSample()

Returns number of bits per channel sample.

Details: This method returns the number of bits per sample per channel.

Returns:

number of bits per sample channel sample.

countSamples

public abstract long countSamples()
                           throws java.io.IOException

Returns number of samples.

Details: This method returns the number of samples contained in this wave stream. This value devided by the sample rate is the duration of the sound.

Returns:

number of samples

readSamples

public abstract java.lang.Object readSamples(long when,
                                             java.lang.Object dest,
                                             int dest_from,
                                             int duration)
                                      throws java.io.IOException

Reads and decodes samples.

Details: This method reads sample data from the source file and returns the samples in a sample array. Exactly amount samples are read, beginning with the when^th sample in the sample stream (where 0 is the index of the first sample). The samples are copied into the given array (dest). If that array is not the correct type for the sample resolution of this wave stream, the samples are automatically converted to the resolution required by the array. (See the package header for more details.)

If dest is null, an array of the most natural type for this stream is automatically created, and its length is set just large enough to accomodate the request. The new sample array is then treated exactly as if it had been provided as the original dest parameter.

The first sample written into dest is written into dest [dest_from]. Exactly duration * wChannels values are decoded and written into the array, where wChannels is the number of channels as set in the format chunk.

Parameters:

when - sample position

dest - destination array

dest_from - starting index in destination array

duration - number of samples to read

Returns:

the samples

Throws:

java.io.IOException - if an I/O error occurs

freeSamples

public abstract void freeSamples(long when,
                                 int duration)
                          throws java.io.IOException

Releases samples from buffer.

Details: This method informs this wave stream reader that the client will no longer requires access to the given range of samples. Calling this method allows this implementation to send buffering hints to the underlying .wav file input source, which may be buffering the data stream.

Parameters:

when - beginning sample index

duration - number of samples to release

Throws:

if - an I/O error occurs

See Also:

IRiffInput.free(long, long)

close

public void close()
           throws java.io.IOException

Closes wave stream.

Details: This method closes the RIFF source that this WaveStreamReader was processing. Calls to other methods in the class may fail after calling close.

getChannelSampleSize

public abstract int getChannelSampleSize()
                                  throws java.io.IOException

Returns size of individual channel sample.

Details: getChannelSampleSize returns the size of the data type used by readSamples to store a single channel sample. The value returned by this method indicates the type of array most naturally preferred by this instance in calls to readSamples.

channel sample size	value returned	array type
1-8 bits	1	byte
9-16 bits	2	short
17-32 bits	4	int

Returns:

size of array type

Since:

2000.09.28