Home   Information   Classes   Download   Usage   Mail List   Requirements   Links   Tutorial


WvIn Class Reference

#include <WvIn.h>

Inheritance diagram for WvIn:

Stk RtWvIn TcpWvIn WaveLoop List of all members.

Detailed Description

STK audio data input base class.

This class provides input support for various audio file formats. It also serves as a base class for "realtime" streaming subclasses.

WvIn loads the contents of an audio file for subsequent output. Linear interpolation is used for fractional "read rates".

WvIn supports multi-channel data in interleaved format. It is important to distinguish the tick() methods, which return samples produced by averaging across sample frames, from the tickFrame() methods, which return pointers to multi-channel sample frames. For single-channel data, these methods return equivalent values.

Small files are completely read into local memory during instantiation. Large files are read incrementally from disk. The file size threshold and the increment size values are defined in WvIn.h.

When the end of a file is reached, subsequent calls to the tick() functions return the data values at the end of the file.

WvIn currently supports WAV, AIFF, SND (AU), MAT-file (Matlab), and STK RAW file formats. Signed integer (8-, 16-, and 32-bit) and floating- point (32- and 64-bit) data types are supported. Compressed data types are not supported. If using MAT-files, data should be saved in an array with each data channel filling a matrix row. The sample rate for MAT-files is assumed to be 44100 Hz.

by Perry R. Cook and Gary P. Scavone, 1995 - 2004.

Definition at line 57 of file WvIn.h.

Public Member Functions

 WvIn ()
 Default constructor.

 WvIn (std::string fileName, bool raw=false, bool doNormalize=true)
 Overloaded constructor for file input.

virtual ~WvIn ()
 Class destructor.

void openFile (std::string fileName, bool raw=false, bool doNormalize=true)
 Open the specified file and load its data.

void closeFile (void)
 If a file is open, close it.

void reset (void)
 Clear outputs and reset time (file pointer) to zero.

void normalize (void)
 Normalize data to a maximum of +-1.0.

void normalize (StkFloat peak)
 Normalize data to a maximum of +-peak.

unsigned long getSize (void) const
 Return the file size in sample frames.

unsigned int getChannels (void) const
 Return the number of audio channels in the file.

StkFloat getFileRate (void) const
 Return the input file sample rate in Hz (not the data read rate).

bool isFinished (void) const
 Query whether reading is complete.

void setRate (StkFloat aRate)
 Set the data read rate in samples. The rate can be negative.

virtual void addTime (StkFloat aTime)
 Increment the read pointer by aTime samples.

void setInterpolate (bool doInterpolate)
 Turn linear interpolation on/off.

virtual StkFloat lastOut (void) const
 Return the average across the last output sample frame.

virtual StkFloat tick (void)
 Read out the average across one sample frame of data.

virtual StkFloat * tick (StkFloat *vector, unsigned int vectorSize)
 Read out vectorSize averaged sample frames of data in vector.

virtual StkFramestick (StkFrames &frames, unsigned int channel=1)
 Fill a channel of the StkFrames object with averaged sample frames.

virtual const StkFloat * lastFrame (void) const
 Return a pointer to the last output sample frame.

virtual const StkFloat * tickFrame (void)
 Return a pointer to the next sample frame of data.

virtual StkFloat * tickFrame (StkFloat *frameVector, unsigned int frames)
 Read out sample frames of data to frameVector.

virtual StkFramestickFrame (StkFrames &frames)
 Fill the StkFrames object with sample frames of data and return the same reference.


Constructor & Destructor Documentation

WvIn::WvIn std::string  fileName,
bool  raw = false,
bool  doNormalize = true
 

Overloaded constructor for file input.

An StkError will be thrown if the file is not found, its format is unknown, or a read error occurs.


Member Function Documentation

void WvIn::openFile std::string  fileName,
bool  raw = false,
bool  doNormalize = true
 

Open the specified file and load its data.

An StkError will be thrown if the file is not found, its format is unknown, or a read error occurs.

void WvIn::normalize void   ) 
 

Normalize data to a maximum of +-1.0.

For large, incrementally loaded files with integer data types, normalization is computed relative to the data type maximum. No normalization is performed for incrementally loaded files with floating-point data types.

void WvIn::normalize StkFloat  peak  ) 
 

Normalize data to a maximum of +-peak.

For large, incrementally loaded files with integer data types, normalization is computed relative to the data type maximum (peak/maximum). For incrementally loaded files with floating- point data types, direct scaling by peak is performed.

StkFloat WvIn::getFileRate void   )  const
 

Return the input file sample rate in Hz (not the data read rate).

WAV, SND, and AIF formatted files specify a sample rate in their headers. STK RAW files have a sample rate of 22050 Hz by definition. MAT-files are assumed to have a rate of 44100 Hz.

void WvIn::setRate StkFloat  aRate  ) 
 

Set the data read rate in samples. The rate can be negative.

If the rate value is negative, the data is read in reverse order.

void WvIn::setInterpolate bool  doInterpolate  ) 
 

Turn linear interpolation on/off.

Interpolation is automatically off when the read rate is an integer value. If interpolation is turned off for a fractional rate, the time index is truncated to an integer value.

virtual StkFloat WvIn::tick void   )  [virtual]
 

Read out the average across one sample frame of data.

An StkError will be thrown if a file is read incrementally and a read error occurs.

Reimplemented in RtWvIn, and TcpWvIn.

virtual StkFloat* WvIn::tick StkFloat *  vector,
unsigned int  vectorSize
[virtual]
 

Read out vectorSize averaged sample frames of data in vector.

An StkError will be thrown if a file is read incrementally and a read error occurs.

Reimplemented in RtWvIn, and TcpWvIn.

virtual StkFrames& WvIn::tick StkFrames frames,
unsigned int  channel = 1
[virtual]
 

Fill a channel of the StkFrames object with averaged sample frames.

The channel argument should be one or greater (the first channel is specified by 1). An StkError will be thrown if a file is read incrementally and a read error occurs or the channel argument is zero or it is greater than the number of channels in the StkFrames object.

Reimplemented in RtWvIn, and TcpWvIn.

virtual const StkFloat* WvIn::tickFrame void   )  [virtual]
 

Return a pointer to the next sample frame of data.

An StkError will be thrown if a file is read incrementally and a read error occurs.

Reimplemented in RtWvIn, TcpWvIn, and WaveLoop.

virtual StkFloat* WvIn::tickFrame StkFloat *  frameVector,
unsigned int  frames
[virtual]
 

Read out sample frames of data to frameVector.

An StkError will be thrown if a file is read incrementally and a read error occurs.

Reimplemented in RtWvIn, TcpWvIn, and WaveLoop.

virtual StkFrames& WvIn::tickFrame StkFrames frames  )  [virtual]
 

Fill the StkFrames object with sample frames of data and return the same reference.

An StkError will be thrown if a file is read incrementally and a read error occurs or if there is an incompatability between the number of channels in the WvIn object and that in the StkFrames object.

Reimplemented in RtWvIn, TcpWvIn, and WaveLoop.


The documentation for this class was generated from the following file:
The Synthesis ToolKit in C++ (STK)
©1995-2004 Perry R. Cook and Gary P. Scavone. All Rights Reserved.