ST(3)							     Library Functions Manual							     ST(3)

NAME

       libst - Sound Tools : sound sample file and effects libraries.

SYNOPSIS

       cc file.c -o file libst.a

DESCRIPTION

       Sound Tools is a library of sound sample file format readers/writers and sound effects processors.

       Sound  Tools includes skeleton C files to assist you in writing new formats and effects.  The full skeleton driver, skel.c, helps you write
       drivers for a new format which has data structures.  The simple skeleton drivers help you write a new driver for raw (headerless)  formats,
       or for formats which just have a simple header followed by raw data.

       Most  sound sample formats are fairly simple: they are just a string of bytes or words and are presumed to be sampled at a known data rate.
       Most of them have a short data structure at the beginning of the file.

INTERNALS

       The Sound Tools formats and effects operate on an internal buffer format of signed 32-bit longs.  The data processing routines  are  called
       with  buffers  of  these  samples,  and buffer sizes which refer to the number of samples processed, not the number of bytes.  File readers
       translate the input samples to signed longs and return the number of longs read.  For example, data in linear signed byte format  is  left-
       shifted 24 bits.

       This does cause problems in processing the data.  For example:
	    *obuf++ = (*ibuf++ + *ibuf++)/2;
       would not mix down left and right channels into one monophonic channel, because the resulting samples would overflow 32 bits.  Instead, the
       ``avg'' effects must use:
	    *obuf++ = *ibuf++/2 + *ibuf++/2;

       Stereo data is stored with the left and right speaker data in successive samples.  Quadraphonic data is stored in this order:  left  front,
       right front, left rear, right rear.

FORMATS

       A  format  is  responsible for translating between sound sample files and an internal buffer.  The internal buffer is store in signed longs
       with a fixed sampling rate.  The format operates from two data structures: a format structure, and a private structure.

       The format structure contains a list of control parameters for the sample: sampling rate, data size (bytes, words, floats, etc.),  encoding
       (unsigned,  signed,  logarithmic), number of sound channels.  It also contains other state information: whether the sample file needs to be
       byte-swapped, whether fseek() will work, its suffix, its file stream pointer, its format pointer, and the private structure for the  format
       .

       The  private  area  is just a preallocated data array for the format to use however it wishes.  It should have a defined data structure and
       cast the array to that structure.  See voc.c for the use of a private data area.  Voc.c has to track the number of samples  it  writes  and
       when  finishing,  seek back to the beginning of the file and write it out.  The private area is not very large.	The ``echo'' effect has to
       malloc() a much larger area for its delay line buffers.

       A format has 6 routines:

       startread	   Set up the format parameters, or read in a data header, or do what needs to be done.

       read		   Given a buffer and a length: read up to that many samples, transform them into signed long integers, and copy them into
			   the buffer.	Return the number of samples actually read.

       stopread 	   Do what needs to be done.

       startwrite	   Set up the format parameters, or write out a data header, or do what needs to be done.

       write		   Given  a buffer and a length: copy that many samples out of the buffer, convert them from signed longs to the appropri-
			   ate data, and write them to the file.  If it can't write out all the samples, fail.

       stopwrite	   Fix up any file header, or do what needs to be done.

EFFECTS

       An effects loop has one input and one output stream.  It has 5 routines.

       getopts		   is called with a character string argument list for the effect.

       start		   is called with the signal parameters for the input and output streams.

       flow		   is called with input and output data buffers, and (by reference) the input and output data buffer sizes.  It  processes
			   the	input buffer into the output buffer, and sets the size variables to the numbers of samples actually processed.	It
			   is under no obligation to read from the input buffer or write to the output buffer during the same call.  If  the  call
			   returns  ST_EOF then this should be used as an indication that this effect will no longer read any data and can be used
			   to switch to drain mode sooner.

       drain		   is called after there are no more input data samples.  If the effect wishes to generate more data samples it copies the
			   generated  data  into  a  given buffer and returns the number of samples generated.	If it fills the buffer, it will be
			   called again, etc.  The echo effect uses this to fade away.

       stop		   is called when there are no more input samples to process.  stop may generate output samples on its	own.   See  echo.c
			   for how to do this, and see that what it does is absolutely bogus.

COMMENTS

       Theoretically, formats can be used to manipulate several files inside one program.  Multi-sample files, for example the download for a sam-
       pling keyboard, can be handled cleanly with this feature.

PORTABILITY PROBLEMS

       Many computers don't supply arithmetic shifting, so do multiplies and divides instead of << and >>.  The compiler will do the  right  thing
       if the CPU supplies arithmetic shifting.

       Do all arithmetic conversions one stage at a time.  I've had too many problems with "obviously clean" combinations.

       In  general, don't worry about "efficiency".  The sox.c base translator is disk-bound on any machine (other than a 8088 PC with an SMD disk
       controller).  Just comment your code and make sure it's clean and simple.  You'll find that DSP code is extremely painful to  write  as	it
       is.

BUGS

       The HCOM format is not re-entrant; it can only be used once in a program.

       The  program/library  interface is pretty weak.	There's too much ad-hoc information which a program is supposed to gather up.  Sound Tools
       wants to be an object-oriented dataflow architecture.

								  October 15 1996							     ST(3)