libst.txt

linux下录音程序

ST(3)							    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 read-
       ers/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 pro-
       cessed, 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  for-
       mat 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  mono-
       phonic  channel, because the resulting samples would over-
       flow 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 sam-
       ple 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  struc-
       ture, and a private structure.




			 October 15 1996			1





ST(3)							    ST(3)


       The format structure contains a list of control parameters
       for the sample: sampling rate, data  size  (bytes,  words,
       floats, etc.), style (unsigned, signed, logarithmic), num-
       ber 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 struc-
       ture 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 num-
			   ber 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, con-
			   vert 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 routines.

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




			 October 15 1996			2





ST(3)							    ST(3)


       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 sizes.  It processes
			   the	input  buffer  into  the   output
			   buffer, and sets the size variables to
			   the numbers of samples  actually  pro-
			   cessed.   It is under no obligation to
			   fill the output buffer.

       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  sampling  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



			 October 15 1996			3





ST(3)							    ST(3)


       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			4