LIBCWAV - Waveform I/O Library


libcwav is a library of functions for reading, writing, and organizing waveform data from speech and other signals. This library is used by most of the speech processing software developed by the ASEL Speech Research group. The main features of the library are: Presently library versions are available for Fortran 77 and C compilers on Unix, MSDOS, and Windows 3.1 platforms.

Waveform Filename Specifications

Some of the most useful features of the libcwav routines are represented as extensions to normal file naming conventions which allow specification of named regions of a file and/or specification of individual channels in multi-channel files. Specifically, a fully qualified waveform file name has the syntax:
where only the basename of the file is required, but the name can optionally contain an extension (.wav by default), a segment name up to 6 characters in length indicating a waveform region that is defined within the file (see edw (1) on how segments are defined), and a channel number ranging from 0 to N-1 where N is the number of channels of data represented in each record of the waveform file. More information on using this syntax is available under the topic Specifying waveform segments and channels.

Waveform Data Structures

Waveforms are sampled functions of time, described in terms of their sampling rate (in samples per second or equivalently Hz) and sample resolution (in bits per sample). For digitized speech signals values typically range from an 8000 Hz sample rate with 8-bit samples (roughly telphone quality) to a 44100 Hz sample rate with 16-bit samples (CD quality). For multi-channel data like stereo sound, or physiological data (e.g., EEG data), each sample period consists of a record containing one sample for each channel, thus 'sample rate' for multi-channel data refers to the number of multi-sample records per second. libcwav provides a data structure for describing the various waveform properties called a Waveform Data Block and defined as:

     typedef struct {
         short           format;
         short           file_type;
         short           smplbits;
         unsigned short  sample_rate;
         short           ref_level;
         short           n_segments;
         short           n_per_rec;
         float           scale;
         float           bias;
         short           error;
     } WDB;

The WDB structure is set by the open waveform function opnwav when existing files are opened, or initialized by an application program and passed to opnwav when a new file is to be created. The elements of a WDB are:

Binary format of data in file. Possible values:
8 bit Offset Binary
12 bit Offset Binary
16 bit Twos Complement
12 bit Twos Complement
Generic Twos Complement (bits per sample in WDB.smplbits)
Generic Offset Binary (bits per sample in WDB.smplbits)

Storage format of the waveform in file. Possible values:
A waveform file format using the standard IBM/Microsoft Resource Interchange File Format (RIFF).
A waveform file using the ASEL internal storage format

Number of bits per sample. (1-16) Only needed for formats GT_format and GO_format.

The sample rate in Hz.

Number of segments defined in file, (only applicable for existing waveforms.) See wavgst for a description of segment tables.

Total channels of data (i.e. samples) per record.

Together with WDB.bias allows linear scaling from integer sample values to real-world coordinates. Sample values are intended to be transformed as:
real_value = WDB.scale * sample_value + WDB.bias;

The intercept for linear transformation of sample values to real-world values.

One of the following constants will be returned by opnwav if an error occurs in opening a file:
File could not be found or created
Format not one of those defined
Segment not found in file
Channel number > total channels per record
Memory allocation failure
Predefined buffer too small for record.
File neither RIFF nor ASEL format.


Libcwav functions


Shirley Peters, H.T.Bunnell