You are on page 1of 23

WaveIO Reference Manual

Generated by Doxygen 1.2.8.1


Thu Jun 10 14:01:20 2004

Contents
1 WaveIO 1.1 1.2 1.3 1.4 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What do I nd in WaveIO? . . . . . . . . . . . . . . . . . . . . . How do I use it? . . . . . . . . . . . . . . . . . . . . . . . . . . . Typical usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1 1 1 2 3 3 5 5 7 7 9 11 13 13

2 WaveIO Data Structure Index 2.1 WaveIO Data Structures . . . . . . . . . . . . . . . . . . . . . . .

3 WaveIO File Index 3.1 WaveIO File List . . . . . . . . . . . . . . . . . . . . . . . . . . .

4 WaveIO Class Documentation 4.1 4.2 4.3 WAV FILE Struct Reference . . . . . . . . . . . . . . . . . . . . wav fmt Struct Reference . . . . . . . . . . . . . . . . . . . . . . wav samples Struct Reference . . . . . . . . . . . . . . . . . . . .

5 WaveIO File Documentation 5.1 waveio.h File Reference . . . . . . . . . . . . . . . . . . . . . . .

Chapter 1

WaveIO
1.1 Introduction

WaveIO is a simple C library which allows for reading/writing WAV les. The le must be PCM coded, 8 or 16 bits/sample and with 1 or 2 channels. I wrote this library for my students, in order to allow them to do experiments with audio signals. I needed a simple interface and I did not want to rely on any external libraries => I decided to write this software by myself. Although I tested and debugged this library, I would keep it, by now, in a beta state. Please, let me no if you discover/correct any bugs.

1.2

What do I nd in WaveIO?

WaveIO gives you Functions for opening WAV les in input/output open input wav() (p. 16) open output wav() (p. 16) Functions for reading/writing samples from/to WAV les read wav samples() (p. 16) write wav samples() (p. 17) You can also slurp a whole WAV le in memory with slurp wav le() (p. 16)

1.3

How do I use it?

1. Put waveio.c and waveio.h in a directory searched by your C compiler

2 2. Make waveio.o from waveio.c (e.g. with cc -c waveio.c) 3. Link waveio.o with your program (e.g. myprogram.o waveio.o)

WaveIO

with cc -o myprogram

1.4

Typical usage

#include <errno.h> #include "waveio.h" // In case of error, print a suitable message and exit. void handle_error(char *msg) { waveio_perror(msg); exit(1); }

int main(int argc, char **argv) { WAV_FILE *Output; wav_samples *buf; int16 data[N]; // Read the samples of pippo.wav buf = slurp_wav_file("/tmp/pippo.wav"); if (buf==NULL) handle_error("Could not read pippo.wav"); // Process the first channel of pippo.wav to obtain some other // audio data (which goes in data[]) process_audio(data, buf->chan0); // Write the result to pluto.wav Output = open_output_wav("/tmp/pluto.wav", // Output file 1, // mono // use the same bit/sample and sampling frequency // of the input file buf->bit_per_samples, buf->freq); if (Output==NULL) handle_error("Could not open pluto.wav"); if (write_wav_samples(Output, data, buf->nsamples) < buf->nsamples) handle_error("Error while writing to pluto.wav"); close_wav_file(Output); return 0; }

Generated at Thu Jun 10 14:01:21 2004 for WaveIO by Doxygen written by Dimitri van Heesch c 1997-2001

Chapter 2

WaveIO Data Structure Index


2.1 WaveIO Data Structures
7 9 11

Here are the data structures with brief descriptions: WAV FILE (WAV le descriptor, it plays the role of FILE in stdio) . wav fmt (Format descriptor) . . . . . . . . . . . . . . . . . . . . . . . wav samples (Returned by slurp wav le, contains the samples in the WAV le) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

WaveIO Data Structure Index

Generated at Thu Jun 10 14:01:21 2004 for WaveIO by Doxygen written by Dimitri van Heesch c 1997-2001

Chapter 3

WaveIO File Index


3.1 WaveIO File List
. . . . . . . . . . . 13

Here is a list of all documented les with brief descriptions: waveio.h (Simple functions for I/O on WAV le)

WaveIO File Index

Generated at Thu Jun 10 14:01:21 2004 for WaveIO by Doxygen written by Dimitri van Heesch c 1997-2001

Chapter 4

WaveIO Class Documentation


4.1 WAV FILE Struct Reference

WAV le descriptor, it plays the role of FILE in stdio. #include <waveio.h>

Data Fields
FILE stream wav fmt fmt info
Format information.

int nsamples
# of samples in the WAV le.

int idx char mode

4.1.1

Detailed Description

WAV le descriptor, it plays the role of FILE in stdio.

4.1.2
4.1.2.1

Field Documentation
wav fmt WAV FILE::fmt info

Format information.

8 4.1.2.2 int WAV FILE::nsamples

WaveIO Class Documentation

# of samples in the WAV le. The documentation for this struct was generated from the following le: waveio.h

Generated at Thu Jun 10 14:01:21 2004 for WaveIO by Doxygen written by Dimitri van Heesch c 1997-2001

4.2 wav fmt Struct Reference

4.2

wav fmt Struct Reference

Format descriptor. #include <waveio.h>

Data Fields
char fmt [4] int32 chunk length int16 format type int16 channels
# of channels.

int32 sampling freq


Sampling freq in Hz.

int32 byte per sec


# of byte/sec = samplingbyte by capture.

int16 byte by capture


channels bit per sample/8.

int16 bit per sample


8 or 16.

4.2.1

Detailed Description

Format descriptor. This struct is the copy of the fmt chunk in the WAV le. It contains several informations such as number of channels, sampling frequency and so on...

4.2.2
4.2.2.1 8 or 16.

Field Documentation
int16 wav fmt::bit per sample

4.2.2.2

int16 wav fmt::byte by capture

channels bit per sample/8.


Generated at Thu Jun 10 14:01:21 2004 for WaveIO by Doxygen written by Dimitri van Heesch c 1997-2001

10 4.2.2.3 int32 wav fmt::byte per sec

WaveIO Class Documentation

# of byte/sec = samplingbyte by capture. 4.2.2.4 int16 wav fmt::channels

# of channels. 4.2.2.5 int32 wav fmt::sampling freq

Sampling freq in Hz. The documentation for this struct was generated from the following le: waveio.h

Generated at Thu Jun 10 14:01:21 2004 for WaveIO by Doxygen written by Dimitri van Heesch c 1997-2001

4.3 wav samples Struct Reference

11

4.3

wav samples Struct Reference

Returned by slurp wav le, contains the samples in the WAV le. #include <waveio.h>

Data Fields
int bit per sample
# of bit/samples (8 or 16).

int nsamples
# of samples per channel.

int nchannels
# of channels (1 or 2).

int freq
Sampling frequency (in Hz).

int16 chan0
Array of the samples in the rst channel.

int16 chan1
Array of the samples in the second channel.

4.3.1

Detailed Description

Returned by slurp wav le, contains the samples in the WAV le. This struct is lled by slurp wav le() (p. 16) with the samples contained in the WAV le. Note that slurp wav le() (p. 16) always returns 16 bit samples, even if the le is an 8 bit one.

4.3.2
4.3.2.1

Field Documentation
int wav samples::bit per sample

# of bit/samples (8 or 16). int16 wav samples::chan0

4.3.2.2

Array of the samples in the rst channel.


Generated at Thu Jun 10 14:01:21 2004 for WaveIO by Doxygen written by Dimitri van Heesch c 1997-2001

12 4.3.2.3 int16 wav samples::chan1

WaveIO Class Documentation

Array of the samples in the second channel. If the le is mono (and nchannels=1), then chan1=NULL, otherwise chan1=chan0+nsamples. 4.3.2.4 int wav samples::freq

Sampling frequency (in Hz). 4.3.2.5 int wav samples::nchannels

# of channels (1 or 2). 4.3.2.6 int wav samples::nsamples

# of samples per channel. The documentation for this struct was generated from the following le: waveio.h

Generated at Thu Jun 10 14:01:21 2004 for WaveIO by Doxygen written by Dimitri van Heesch c 1997-2001

Chapter 5

WaveIO File Documentation


5.1 waveio.h File Reference

Simple functions for I/O on WAV le.

Data Structures
struct WAV FILE
WAV le descriptor, it plays the role of FILE in stdio.

struct wav fmt


Format descriptor.

struct wav samples


Returned by slurp wav le, contains the samples in the WAV le.

Denes
#dene WAVEIO OK 0
No error or system error (see discussion about error reporting).

#dene WAVEIO EOF -1


End-of-le while reading.

#dene WAVEIO OUT OF ROOM -2


Too many open les.

#dene WAVEIO INV -3

14
Bad WAV le.

WaveIO File Documentation

#dene WAVEIO NO PCM -4


WAV le does not use PCM.

Typedefs
typedef short int16 typedef int int32

Functions
WAV FILE open input wav (char lename)
Open a WAV le in input.

WAV FILE open output wav (char lename, int nchan, int nbits, int freq) void close wav le (WAV FILE f)
Close a WAV le opened with open output wav() (p. 16) or open input wav() (p. 16).

int write wav samples (WAV FILE Output, void buf, int how many)
Write some samples to a WAV le.

int read wav samples (WAV FILE Input, void buf, int how many)
Read some samples from a WAV le.

wav samples slurp wav le (char lename)


Read a whole WAV le.

void destroy wav samples (wav samples w)


Free the memory used by a wav samples (p. 11) struct.

void waveio perror (char msg)


As perror(), but it handles also errors found by WaveIO.

Variables
int waveio errno
Waveio error code.

char waveio errmsg [ ]


Waveio error messages.

Generated at Thu Jun 10 14:01:21 2004 for WaveIO by Doxygen written by Dimitri van Heesch c 1997-2001

5.1 waveio.h File Reference

15

5.1.1

Detailed Description

Simple functions for I/O on WAV le. This modules contains functions for reading and writing simple WAV les (at most 2 channels, PCM coding, 8 or 16 bits/sample).

Error reporting
There are two dierent classes of errors: errors found by the library (e.g. a WAV le with a wrong format) errors returned by system functions (e.g. fopen returns NULL because it cannot open the le) In order to distinguish between the two classes we will use a global variable waveio errno as follows If the error was found by the library we put an error code in waveio errno and return If the error was reported by a system function such as fopen(), then we put waveio errno=WAVEIO OK and return. The code of returned by the system function will be in errno.

5.1.2
5.1.2.1

Dene Documentation
#dene WAVEIO EOF -1

End-of-le while reading.

5.1.2.2

#dene WAVEIO INV -3

Bad WAV le.

5.1.2.3

#dene WAVEIO NO PCM -4

WAV le does not use PCM.

5.1.2.4

#dene WAVEIO OK 0

No error or system error (see discussion about error reporting).


Generated at Thu Jun 10 14:01:21 2004 for WaveIO by Doxygen written by Dimitri van Heesch c 1997-2001

16 5.1.2.5

WaveIO File Documentation #dene WAVEIO OUT OF ROOM -2

Too many open les.

5.1.3
5.1.3.1

Function Documentation
void close wav le (WAV FILE f)

Close a WAV le opened with open output wav() (p. 16) or open input wav() (p. 16). 5.1.3.2 void destroy wav samples (wav samples w)

Free the memory used by a wav samples (p. 11) struct. 5.1.3.3 WAV FILE open input wav (char lename)

Open a WAV le in input. It returns a pointer to the newly opened le if everything is OK, otherwise returns NULL. 5.1.3.4 WAV FILE open output wav (char lename, int nchan, int nbits, int freq)

Open a WAV le in output. It returns a pointer to the newly opened le if everything is OK, otherwise returns NULL. Parameters: nchan # of channels (1 or 2). nbits # of bit/samples (8 or 16). freq Sampling frequency.

5.1.3.5

int read wav samples (WAV FILE Input, void buf, int how many)

Read some samples from a WAV le. Parameter buf points to a char array or to an int array, depending on the WAV le type (with 8 or 16 bits/sample). If succesful, it returns 0, otherwise it returns -1 and variables errno/waveio errno are setted. 5.1.3.6 wav samples slurp wav le (char lename)

Read a whole WAV le.


Generated at Thu Jun 10 14:01:21 2004 for WaveIO by Doxygen written by Dimitri van Heesch c 1997-2001

5.1 waveio.h File Reference The samples and other informations (such as # of channels, sampling frequency and so on) are returned in a wav samples (p. 11) structure. It returns NULL and sets variables errno/waveio errno if some error happens. 5.1.3.7 void waveio perror (char msg)

17

As perror(), but it handles also errors found by WaveIO. 5.1.3.8 int write wav samples (WAV FILE Output, void buf, int how many)

Write some samples to a WAV le. Parameter buf points to a char array or to an int array, depending on the WAV le type (with 8 or 16 bits/sample). If succesful, it returns 0, otherwise it returns -1 and variables errno/waveio errno are setted.

5.1.4
5.1.4.1

Variable Documentation
char waveio errmsg[ ]

Waveio error messages. 5.1.4.2 int waveio errno

Waveio error code.

Generated at Thu Jun 10 14:01:21 2004 for WaveIO by Doxygen written by Dimitri van Heesch c 1997-2001

Index
bit per sample wav fmt, 9 wav samples, 11 byte by capture wav fmt, 9 byte per sec wav fmt, 9 chan0 wav samples, 11 chan1 wav samples, 11 channels wav fmt, 10 chunk length wav fmt, 9 close wav le waveio.h, 16 destroy wav samples waveio.h, 16 fmt wav fmt, 9 fmt info WAV FILE, 7 format type wav fmt, 9 freq wav samples, 12 idx WAV FILE, 7 int16 waveio.h, 14 int32 waveio.h, 14 mode WAV FILE, 7 nchannels wav samples, 12 nsamples WAV FILE, 7 wav samples, 12 open input wav waveio.h, 16 open output wav waveio.h, 16 read wav samples waveio.h, 16 sampling freq wav fmt, 10 slurp wav le waveio.h, 16 stream WAV FILE, 7 WAV FILE, 7 fmt info, 7 idx, 7 mode, 7 nsamples, 7 stream, 7 wav fmt, 9 bit per sample, 9 byte by capture, 9 byte per sec, 9 channels, 10 chunk length, 9 fmt, 9 format type, 9 sampling freq, 10 wav samples, 11 bit per sample, 11 chan0, 11 chan1, 11 freq, 12 nchannels, 12

INDEX nsamples, 12 waveio.h, 13 close wav le, 16 destroy wav samples, 16 int16, 14 int32, 14 open input wav, 16 open output wav, 16 read wav samples, 16 slurp wav le, 16 WAVEIO EOF, 15 waveio errmsg, 17 waveio errno, 17 WAVEIO INV, 15 WAVEIO NO PCM, 15 WAVEIO OK, 15 WAVEIO OUT OF ROOM, 15 waveio perror, 17 write wav samples, 17 WAVEIO EOF waveio.h, 15 waveio errmsg waveio.h, 17 waveio errno waveio.h, 17 WAVEIO INV waveio.h, 15 WAVEIO NO PCM waveio.h, 15 WAVEIO OK waveio.h, 15 WAVEIO OUT OF ROOM waveio.h, 15 waveio perror waveio.h, 17 write wav samples waveio.h, 17

19

Generated at Thu Jun 10 14:01:21 2004 for WaveIO by Doxygen written by Dimitri van Heesch c 1997-2001

You might also like