home *** CD-ROM | disk | FTP | other *** search
/ Enigma Amiga Life 106 / EnigmaAmiga106CD.iso / software / musica / sox-12.16 / doc / libst.txt < prev    next >
Text File  |  1999-07-18  |  7KB  |  265 lines
  1.  
  2.  
  3.  
  4. ST(3)                                ST(3)
  5.  
  6.  
  7. NAME
  8.        libst  -     Sound    Tools  :  sound     sample     file and effects
  9.        libraries.
  10.  
  11. SYNOPSIS
  12.        cc file.c -o file libst.a
  13.  
  14. DESCRIPTION
  15.        Sound Tools is a library of sound sample file format read-
  16.        ers/writers and sound effects processors.
  17.  
  18.        Sound  Tools  includes  skeleton     C files to assist you in
  19.        writing    new  formats  and  effects.   The  full     skeleton
  20.        driver,    skel.c,     helps you write drivers for a new format
  21.        which has data structures.  The    simple    skeleton  drivers
  22.        help  you write a new driver for raw (headerless) formats,
  23.        or for formats which just have a simple header followed by
  24.        raw data.
  25.  
  26.        Most sound sample formats are fairly simple: they are just
  27.        a string of bytes or words and are presumed to be  sampled
  28.        at  a  known  data  rate.   Most of them have a short data
  29.        structure at the beginning of the file.
  30.  
  31. INTERNALS
  32.        The Sound Tools formats and effects operate on an internal
  33.        buffer format of signed 32-bit longs.  The data processing
  34.        routines are called with buffers     of  these  samples,  and
  35.        buffer  sizes  which  refer  to the number of samples pro-
  36.        cessed, not the number of bytes.     File  readers    translate
  37.        the input samples to signed longs and return the number of
  38.        longs read.  For example, data in linear signed byte  for-
  39.        mat is left-shifted 24 bits.
  40.  
  41.        This  does  cause  problems  in    processing the data.  For
  42.        example:
  43.         *obuf++ = (*ibuf++ + *ibuf++)/2;
  44.        would not mix down left and right channels into one  mono-
  45.        phonic  channel, because the resulting samples would over-
  46.        flow 32 bits.  Instead, the ``avg'' effects must use:
  47.         *obuf++ = *ibuf++/2 + *ibuf++/2;
  48.  
  49.        Stereo data is stored with the left and right speaker data
  50.        in  successive  samples.      Quadraphonic    data is stored in
  51.        this order: left front,    right  front,  left  rear,  right
  52.        rear.
  53.  
  54. FORMATS
  55.        A format is responsible for translating between sound sam-
  56.        ple files and an internal buffer.  The internal buffer  is
  57.        store  in  signed  longs     with a fixed sampling rate.  The
  58.        format operates from two data structures: a format  struc-
  59.        ture, and a private structure.
  60.  
  61.  
  62.  
  63.  
  64.              October 15 1996            1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ST(3)                                ST(3)
  71.  
  72.  
  73.        The format structure contains a list of control parameters
  74.        for the sample: sampling rate, data  size  (bytes,  words,
  75.        floats, etc.), style (unsigned, signed, logarithmic), num-
  76.        ber of sound  channels.     It  also  contains  other  state
  77.        information:  whether  the  sample  file needs to be byte-
  78.        swapped, whether fseek() will work, its suffix,    its  file
  79.        stream pointer, its format pointer, and the private struc-
  80.        ture for the format .
  81.  
  82.        The private area is just a preallocated data array for the
  83.        format to use however it wishes.     It should have a defined
  84.        data structure and cast the array to that structure.   See
  85.        voc.c  for  the    use of a private data area.  Voc.c has to
  86.        track the number of samples it writes and when  finishing,
  87.        seek  back  to the beginning of the file and write it out.
  88.        The private area is not very large.  The     ``echo''  effect
  89.        has  to    malloc()  a  much  larger area for its delay line
  90.        buffers.
  91.  
  92.        A format has 6 routines:
  93.  
  94.        startread       Set up the format parameters, or  read
  95.                in  a data header, or do what needs to
  96.                be done.
  97.  
  98.        read           Given a buffer and a length:     read  up
  99.                to  that  many samples, transform them
  100.                into signed long  integers,    and  copy
  101.                them into the buffer.  Return the num-
  102.                ber of samples actually read.
  103.  
  104.        stopread           Do what needs to be done.
  105.  
  106.        startwrite       Set up the format parameters, or write
  107.                out a data header, or do what needs to
  108.                be done.
  109.  
  110.        write           Given a buffer and a length: copy that
  111.                many     samples  out of the buffer, con-
  112.                vert them from  signed  longs  to  the
  113.                appropriate    data,  and  write them to
  114.                the file.  If it can't write     out  all
  115.                the samples, fail.
  116.  
  117.        stopwrite       Fix    up  any     file  header, or do what
  118.                needs to be done.
  119.  
  120. EFFECTS
  121.        An effects loop has one input and one output  stream.   It
  122.        has 5 routines.
  123.  
  124.        getopts           is  called  with  a    character  string
  125.                argument list for the effect.
  126.  
  127.  
  128.  
  129.  
  130.              October 15 1996            2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ST(3)                                ST(3)
  137.  
  138.  
  139.        start           is called with the  signal  parameters
  140.                for the input and output streams.
  141.  
  142.        flow           is  called  with input and output data
  143.                buffers, and (by reference) the  input
  144.                and    output    data sizes.  It processes
  145.                the    input  buffer  into  the   output
  146.                buffer, and sets the size variables to
  147.                the numbers of samples  actually  pro-
  148.                cessed.   It is under no obligation to
  149.                fill the output buffer.
  150.  
  151.        drain           is called  after  there  are     no  more
  152.                input  data    samples.   If  the effect
  153.                wishes to generate more  data  samples
  154.                it  copies  the  generated data into a
  155.                given buffer and returns the number of
  156.                samples  generated.     If  it fills the
  157.                buffer, it will be called again,  etc.
  158.                The    echo  effect  uses  this  to fade
  159.                away.
  160.  
  161.        stop           is called when there are no more input
  162.                samples to process.    stop may generate
  163.                output samples on its own.  See echo.c
  164.                for    how to do this, and see that what
  165.                it does is absolutely bogus.
  166.  
  167. COMMENTS
  168.        Theoretically, formats can be used to  manipulate  several
  169.        files inside one program.  Multi-sample files, for example
  170.        the download for     a  sampling  keyboard,     can  be  handled
  171.        cleanly with this feature.
  172.  
  173. PORTABILITY PROBLEMS
  174.        Many  computers    don't  supply  arithmetic shifting, so do
  175.        multiplies and divides instead of << and >>.  The compiler
  176.        will  do     the  right  thing if the CPU supplies arithmetic
  177.        shifting.
  178.  
  179.        Do all arithmetic conversions one stage at a  time.   I've
  180.        had too many problems with "obviously clean" combinations.
  181.  
  182.        In general, don't worry    about  "efficiency".   The  sox.c
  183.        base translator is disk-bound on any machine (other than a
  184.        8088 PC with an SMD disk controller).  Just  comment  your
  185.        code  and  make    sure  it's clean and simple.  You'll find
  186.        that DSP code is extremely painful to write as it is.
  187.  
  188. BUGS
  189.        The HCOM format is not re-entrant; it  can  only     be  used
  190.        once in a program.
  191.  
  192.        The program/library interface is pretty weak.  There's too
  193.  
  194.  
  195.  
  196.              October 15 1996            3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. ST(3)                                ST(3)
  203.  
  204.  
  205.        much ad-hoc information which a    program     is  supposed  to
  206.        gather  up.   Sound  Tools  wants to be an object-oriented
  207.        dataflow architecture.
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.              October 15 1996            4
  263.  
  264.  
  265.