libwavstream

A C++ library for accessing RIFF/PCM audio files

libwavstream is a C++ library that contains the definition of the wavstream class. It provides public methods for read, write and create 16-bit audio files in Microsoft RIFF/PCM format. No compression is supported and no 8-bit files handling is implemented. This class reads, writes and updates file headers, implementing optional strong checking of header consistency. Header generated by a wavstream object are fully standard compliant.

libwavstream manages file searching in a set of default directories (like many unix shells do). You can specify the desired set of (colon separated) directory in the WAVSTREAMPATH environment variable. When, during a file opening, wavstream can not find the specified file name, it checks all default directories. At the time this feature can't be disabled.

Mixed access (R/W) opening mode are supported as well as mixed read/write operations. wavstream uses a distinct file pointer for each kind of operation.

wavstream class has no public member variables. All manipulations take place via these public member functions.

• wavstream(void) is the default constructor;
• wavstream(String, String, int), wavstream(String, String, int, long, short, short) and wavstream(String, String, int, class wavstream &) are extended constructors which allow file opening while creating an object. See the Open overload with the same formal parameters set.
• void Open(String filename, String mode, int check) opens the filename file "for reading" (actually mode can be ``r'', ``r+'', ``a'', ``a+'' respectively for read, read & write, append and append & read) . Strong header integrity checking is performed if check is the boolean true (wavstream::check and wavstream::nocheck can be used for correctly setting this flag). Strong checking can be frustrating if you have to deal often with good RIFF files with headers not fully compliant.
• void Open(String filename, String mode, int rwhd, long r, short c, short d) opens a file "for writing" (actually mode can be ``w'', ``w+'', ``a'', ``a+'' respectively for write, read & write, append and append & read). Non-appending modes ("w" and "w+") implies overwriting of an existing file with the same name and automatic header generation with sampling frequency r, channels number c and sampling resolution (depth) d. In appending modes parameters must agree with existing header (not yet implemented). If rwhd is the boolean true, wavstream will perform automatic header updating after each writing operation (this is useful when two process access the same file, e.g. a player can read a file while a processor can write on it).
• void Open(String filename, String mode, int rwhead, class wavstream &s) acts like the previous overload but copies sampling parameters (rate, channels and depth) from the header of the wavstream s.
• long Read(void *b, long n) reads n blocks from the file into the buffer pointed by b.
• long Write(void *b, long n) writes n blocks from the buffer pointed by b into the file and eventually updates file header.
• long WSeek(long n) and long RSeek(long n) respectively move write and read file pointer to the n-th sampling block. Return old pointer position in block units.
• int eof(void) returns the booleand true if the file stream associated with the wavstream reached the end of file.
• void *newBuffer(long n) allocates (using new) a memory area large enough to contain n sampling blocks and returns its address. The area must be freed using the delete[] operator.
• void Close(void) closes the wavstream. If it was opened in write or read/write mode without automatic header rewriting, updates the header. Resets all flags and pointers and closes the associated file stream.

On error, all methods print a panic message on standard error stream and terminate unsuccessfully returning -1.

Once opened a wavstream, one can obtain informations on it by calling these methods:

• long rate(void) returns the sampling frequency in Hz.
• short channels(void) returns the channels number.
• short depth(void) returns the sampling resolution (depth) in bits.
• long bps(void) returns processing load for real time playing in bits per second.
• long nBlocks(void) returns total sample length in sampling blocks.
• long nBytes(void) returns total sample length in bytes.
• double nSeconds(void) returns total sample length in seconds.
• longblockLength(void) returns sampling block length in bytes.
• long totalLength(void) returns total file length in bytes.
• long remaining(void) returns the number of blocks from the reading pointer position to the end of file.

All these methods returns wavstream::ERRNOHDR if the wavstream object has no defined header at call time.

NOTE: This library is no longer useful to me, so there will be no updates.

Here you can find gzipped libwavstream source code and binaries.

Home