ST(3)									 ST(3)



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

SYNOPSIS
       #include <st.h>

       ft_t st_open_input(const char *path, const st_signalinfo_t *info, const
       char *filetype);

       ft_t st_open_output(const  char	*path,	const  st_signalinfo_t	*info,
       const char *filetype, const char *comment);

       st_ssize_t st_read(ft_t ft, st_sample_t *buf, st_ssize_t len);

       st_ssize_t st_write(ft_t ft, st_sample_t *buf, st_ssize_t len);

       int st_close(ft_t ft);

       int st_seek(ft_t ft, st_size_t offset, int whence);

       cc file.c -o file libst.a

DESCRIPTION
       Sound Tools  is	a  library of sound sample file format readers/writers
       and sound effects processors.  It is mainly developed for  use  by  SoX
       but is useful for any sound application.

       st_open_input  function	opens  the  file for reading whose name is the
       string pointed to by path and associates an ft_t with it.  If  info  is
       non-NULL	 then  it will be used to specify the data format of the input
       file.  This is normally only needed for headerless  audio  files	 since
       the  information	 is  not  stored in the file.  If filetype is non-NULL
       then it will be used to specify the file type.  If this is  not	speci-
       fied  then  the	file type is attempted to be derived by looking at the
       file header and/or the filename extension.  A special name of  "-"  can
       be used to read data from stdin.

       st_open_output  function	 opens	the file for writing whose name is the
       string pointed to by path and associates an ft_t with it.  If  info  is
       non-NULL	 then it will be used to specify the data format of the output
       file.  Since most file formats can write data in	 different  data  for-
       mats,  this generally has to be specified.  The info structure from the
       input format handler can be specified to copy data  over	 in  the  same
       format.	 If comment is non-NULL, it will be written in the file header
       for formats that support comments. If filetype is non-NULL then it will
       be  used	 to  specify the file type.  If this is not specified then the
       file type is attempted to be derived by looking at the filename	exten-
       sion.  A special name of "-" can be used to write data to stdout.

       The  function st_read reads len samples in to buf using the format han-
       dler specified by ft.  All data read is converted to 32-bit signed sam-
       ples  before  being placed in to buf.  The value of len is specified in
       total samples.  If its value is not evenly divisable by the  number  of
       channels, undefined behavior will occur.

       The function st_write writes len samples from buf using the format han-
       dler specified by ft.  Data in buf must be 32-bit  signed  samples  and
       will be converted during the write process.  The value of len is speci-
       fied in total samples.  If its value is not  evenly  divisable  by  the
       number of channels, undefined behavior will occur.

       The  st_close  function	dissociates the named ft_t from its underlying
       file or set of functions.  If the format handler	 was  being  used  for
       output, any buffered data is written first.

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

RETURN VALUE
       Upon  successful	 completion  st_open_input and st_open_output return a
       ft_t (which is a pointer).  Otherwise, NULL is returned.	 TODO: Need  a
       what  to	 return	 reason for failures.  Currently, relies on st_warn to
       print information.

       st_read and st_write return the number of samples successfully read  or
       written.	 If an error occurs, or the end-of-file is reached, the return
       value is a short item count or ST_EOF. TODO: st_read does not  distigu-
       ish between end-of-ifle and error.  Need an feof() and ferror() concept
       to determine which occured.

       Upon successful completion st_close returns 0.	Otherwise,  ST_EOF  is
       returned.   In  either case, any further access (including another call
       to st_close()) to the handler results in undefined behavior. TODO: Need
       a  way  to return reason for failures.  Currently, relies on st_warn to
       print information.

       Upon successful completion st_seek returns  0.	Otherwise,  ST_EOF  is
       returned.  TODO Need to set a global error and implement st_tell.

ERRORS
       TODO

INTERNALS
       The  Sound Tools formats and effects operate on an internal buffer for-
       mat of signed 32-bit longs.  The data processing	 routines  are	called
       with buffers of these samples, and buffer sizes which refer to the num-
       ber of samples processed, not the number of bytes.  File readers trans-
       late  the input samples to signed 32-bit integers and return the number
       of samples 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 succes-
       sive 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 sam-
       ple:  sampling rate, data size (8, 16, or 32 bits), encoding (unsigned,
       signed, floating point, etc.), number of sound channels.	 It also  con-
       tains  other  state  information:  whether  the sample file needs to be
       byte-swapped, whether st_seek() 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 mal-
       loc() 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  appropriate	 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  rou-
       tines.

       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 out-
			   put buffer, and sets the size variables to the num-
			   bers 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 sam-
			   ples.  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.

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

       On errors, the effects currently invoke st_fail and rely on that	 call-
       ing exit().  They do not currently gracefully fail.

       The program/library interface is pretty weak.




			       September 26 2005			 ST(3)
