WAVE Audio -- C API

Header Files

#include <dvmwave.h>

Type Definitions

WaveHeader

This structure stores information decoded from the header of a WAVE file.

        typedef struct WaveHdr {
            int format;
            int numOfChan;
            int samplesPerSec;
            int bytesPerSec;
            int blockAlign;
            int bitsPerSample;
            int dataLen;
            unsigned char *extra;
            int extralen;
        } WaveHdr;

format

format code of wave file. See constants below.

numOfChan

number of channels; 1 = mono, 2 = stereo

samplesPerSec

sampling rate of audio in Hz

bytesPerSec

Streaming rate of the data (samplesPerSec * blockAlign)

blockAlign

Block Alignment in bytes = (numOfChan * bitsPerSample / 8)
1 for 8-bit mono, 2 for 16-bit mono, 2 for 8-bit stereo, 4 for 16-bit stereo

bitsPerSample

resolution (in bits); 8 or 16

dataLen

number of bytes of audio data

extra

dynamically allocated space for extra information which is not anticipated in the primitive implementation. This field meant to enable future addition support of other wave formats

extralen

length of extra

Constants

WAVE Format

These constants are among the possible values of the format fields in the WAVE header. Only PCM, A-Law, and Mu-Law are supported.

         #define WAVE_FORMAT_PCM    (0x0001)
         #define WAVE_FORMAT_ALAW   (0x0006)
         #define WAVE_FORMAT_MULAW  (0x0007)

Return Codes

These constants are returned by some of the Wave package primitives to indicate status of the function.

	 #define DVM_WAVE_OK                     (0)
	 #define DVM_WAVE_ERROR                  (1)
	 #define DVM_WAVE_ALREADY_OPEN           (2)
	 #define DVM_WAVE_NOT_OPEN               (3)

Operators

Allocation

WaveHdr *WaveHdrNew();

Allocates a new WaveHdr and return a handle to it.

void WaveHdrFree(WaveHdr *hdr)

Deallocate the WaveHdr hdr.

Slot Access

int WaveHdrGetFormat (WaveHdr *hdr) int WaveHdrGetNumOfChan(WaveHdr *hdr) int WaveHdrGetSamplesPerSec(WaveHdr *hdr) int WaveHdrGetBlockAlign(WaveHdr *hdr) int WaveHdrGetBitsPerSample(WaveHdr *hdr) int WaveHdrGetBytesPerSec(WaveHdr *hdr) int WaveHdrGetDataLen(WaveHdr *hdr)

These functions or macros return the value of the corresponding slot in the WaveHdr data structure.

Format should be either 1 (PCM), 6 (A-law), or 7 (μ-law)
Number of channels is 1 for mono, 2 for stereo.
Sampling rate is in sample/sec (Hz)
block Alignment = numOfChan * bitsPerSample / 8
1 for 8-bit mono, 2 for 16-bit mono, 2 for 8-bit stereo, 4 for 16-bit stereo
Bits per sample is the sample resolution in bits (8 or 16).
Streaming rate of the data (samplesPerSec * blockAlign)
Data length is the length of audio data in bytes.

void WaveHdrSetFormat (WaveHdr *hdr, int format) void WaveHdrSetNumOfChan(WaveHdr *hdr, int numOfChan) void WaveHdrSetSamplesPerSec(WaveHdr *hdr, int rate) void WaveHdrSetBlockAlign(WaveHdr *hdr, int blockAlign) void WaveHdrSetBitsPerSample(WaveHdr *hdr, int resolution) void WaveHdrSetBytesPerSec(WaveHdr *hdr, int resolution) void WaveHdrSetDataLen(WaveHdr *hdr, int len)

These functions or macros set the corresponding slot in the WaveHdr data structure.

Format should be either 1 (PCM), 6 (A-law), or 7 (μ-law)
Number of channels is 1 for mono, 2 for stereo.
Sampling rate is in sample/sec (Hz)
Sets the blockAlign field in the header.
block Alignment = numOfChan * bitsPerSample / 8
Bits per sample is the sample resolution in bits (8 or 16).
Streaming rate of the data (samplesPerSec * blockAlign)
Data length is the length of audio data in bytes.

Decoding and Encoding

int WaveHdrParse(BitParser *bp, WaveHeader *hdr)

Parses the header chunk from the wave file in bp and stores it into WaveHeader hdr. Returns the number of bytes advanced in bp, or 0 if the file being read is an invalid wave file

int WaveHdrEncode(WaveHeader *hdr, BitParser *bp)

Encodes the WaveHdr hdr into the BitParser bp, and returns the number of bytes written into the BitStream.

Wave Output Device Functions

The following functions are used to control output to Wave compatible audio devices (e.g., SoundBlaster cards). They are supported only on Win32 platforms.
A typical calling sequence for this library is:
                // Assume hdr is an initialized WaveHdr, and
                // audio is an AudioBuffer with 8000 16-bit samples
                // (16000 bytes)
                WaveOutOpen(hdr);        //open the output device
                WaveOutPrepPlay(audio);  // Get setup
                WaveOutPlay(16000);      // Play a segment
                
                while (!WaveOutDone()) {
                    sleep(10);           // Wait for play to finish
                }
                WaveOutClose();          // clean up
            
int WaveOutOpen(WaveHdr *hdr)

Opens a wave audio output device for the wave format specified by hdr. Only one device can be open at a time.
This function returns DVM_WAVE_ALREADY_OPEN if the device is already open, DVM_WAVE_ERROR for other errors (e.g., unsupported format), or DVM_WAVE_OK otherwise.

int WaveOutClose()

Closes the current opened Wave Output Device. This function returns DVM_WAVE_NOT_OPEN if the device is not open, DVM_WAVE_OK otherwise.

int WaveAudioPrepPlay(Audio *audio)

This function does any preparation needed before sending audio to the output device. This allows for the lowest latency possible when calling WaveAudioPlay(). The implementation makes a copy of the pointer to the audio buffer, so this pointer should not be free'd if WaveAudioPlay will be called later (the contents of the buffer can be modified, but not the buffer itself). This function returns DVM_WAVE_NOT_OPEN if the device is not open, DVM_WAVE_OK otherwise.

int WaveAudioPlay(int length)

Plays length bytes of the audio data previously specified via WaveAudioPrepPlay This function returns DVM_WAVE_NOT_OPEN if the device is not open, DVM_WAVE_OK otherwise.

int WaveOutDone()

Determine whether the audio data currently playing (via a previous call to WaveAudioPlay) is finished. Returns 1 if and only if the previously played wave audio is finished. Note it returns 0 if nothing has been played before. (i.e., initially right after the device is opened).