SoX(3)                         Sound eXchange_ng                        SoX(3)

NAME
       libsox_ng, another audio file format and effect library

SYNOPSIS
       #include <sox_ng.h>

       int sox_format_init(void);

       void sox_format_quit(void);

       sox_format_t *sox_open_read(const char *path, const sox_signalinfo_t *info, sox_encodinginfo_t const *encoding, const char *filetype);

       sox_format_t *sox_open_write(char const *filename, sox_signalinfo_t const *info, sox_encodinginfo_t const *encoding, char const *filetype, sox_oob_t const *oob, sox_bool (*overwrite_permitted)(char const *filename));

       sox_size_t sox_read(sox_format_t *ft, sox_sample_t *buf, sox_size_t len);

       sox_size_t sox_write(sox_format_t *ft, sox_sample_t const *buf, sox_size_t len);

       int sox_close(sox_format_t Ift);

       int sox_seek(sox_format_t *ft, sox_size_t offset, int whence);

       sox_effect_handler_t const *sox_find_effect(char const *name);

       sox_effect_t *sox_create_effect(sox_effect_handler_t const *eh);

       int sox_effect_options(sox_effect_t *effp, int argc, char * const argv[]);

       sox_effects_chain_t *sox_create_effects_chain(sox_encodinginfo_t const *in_enc, sox_encodinginfo_t const *out_enc);

       int sox_add_effect(sox_effects_chaint_t *chain, sox_effect_t*effp, sox_signalinfo_t *in, sox_signalinfo_t const *out);

       void sox_delete_effects_chain(sox_effects_chain_t *ecp);

       cc file.c ‐o file ‐lsox_ng

DESCRIPTION
       libsox_ng  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.

       This is not really a manual for the libsox_ng API; it is a quick intro‐
       duction to the basic operations for reading and writing audio files and
       to use effect chains, followed by notes on how to write new format han‐
       dlers  and effects.  For an exhaustive description of the libsox_ng API
       see http://martinwguy.net/test/soxygen/sox_8h.html

       sox_format_init() performs initialization required by all  file  format
       handlers.   If  compiled with dynamic library support, this will detect
       and initialize all external libraries.  It should be called before  any
       file operations are performed.

       void sox_format_quit(void)
              sox_format_quit()  performs  cleanup  related to all file format
              handlers and should be called after all file operations are com‐
              pleted.

       sox_format_t *sox_open_read(char const *path,
       sox_signalinfo_t const *signal, sox_encodinginfo_t const *encoding,
       char const *filetype)
              sox_open_read() opens a file for reading.  A special name of ‘-’
              reads data from stdin.  If signal is not NULL, it specifies  the
              properties  of  the  audio signal such as the sample rate or the
              number of channels.  If encoding is not NULL  it  specifies  the
              sample  encoding.   Both  signal  and encoding are normally only
              needed for headerless audio files where that information is  not
              stored  in  the file.  If filetype is not NULL, it specifies the
              file type as the short strings listed in soxformat_ng(7); other‐
              wise, the file’s type is guessed  from  the  filename  extension
              and/or the file’s contents.

              Upon successful completion, sox_open_read() returns a pointer to
              a  filled  sox_format_t,  which should eventually be closed with
              sox_close(), or NULL otherwise.  Currently there is  no  way  to
              determine  the  reason  for failure except for the error message
              printed on the standard error output (stderr).

       sox_format_t *sox_open_write(char const *filename,
       sox_signalinfo_t const *signal, sox_encodinginfo_t const *encoding,
       char const *filetype, sox_oob_t const *oob,
       sox_bool (*overwrite_permitted)(char const *filename))
              sox_open_write() opens the named file for  writing.   A  special
              name  of  ‘-’  writes data to stdout.  If signal is not NULL, it
              specifies the data format of the output file; the signal  struc‐
              ture  filled  in  by sox_open_read() can be used to copy data in
              the same format.  If encoding is not NULL, it specifies the  de‐
              sired  sample  encoding.  Since most file formats can write data
              in different data formats, this usually has to be specified;  if
              NULL,  a default is used.  If filetype is non‐NULL, it specifies
              the file type.  If it is NULL, SoX derives the  file  type  from
              the  filename  extension.  If oob is not NULL, it specifies out‐
              of‐band data to add to the file such as comments, instrument in‐
              formation and loop  points  if  the  file  type  supports  them.
              sox_open_write() returns a handle to the new session, which must
              be closed with sox_close(), or NULL on failure.

       sox_read() reads len samples into buf using the format handler ft.  All
       data  is converted to 32‐bit signed samples before being placed in buf.
       The value of len is in total samples and if its value is not  divisable
       by the number of channels, anything might happen.

       It returns the number of samples read, which may be less tha the number
       requested,  or  zero  at  the  end of the file or if an error occurred.
       sox_read()’s return value does not distinguish between  the  end  of  a
       file and an error but you can inspect ft‐>sox_errno to tell the differ‐
       ence.   It should be SOX_SUCCESS or SOX_EOF unless some other error has
       occurred previously; you can clear ft‐>sox_errno to 0 beforehand to  be
       sure.

       sox_read()  and  sox_write()  return the number of samples successfully
       read or written. If an error occurs or the end of the file is  reached,
       the  return  value  is  a short item count or SOX_EOF, depending on the
       function.

       sox_write() writes len samples from buf to the file described by format
       and the 32‐bit signed data in buf are converted according to  the  for‐
       mat.   The  value  of len is the total samples and must be divisible by
       the number of channels, otherwise unexpected things will occur.  It re‐
       turns the actual number of samples encoded, zero if an error occurred.

       sox_close() dissociates a sox_format_t from its underlying file and set
       of functions.  If the format handler was used for output, any  buffered
       data  is written first.  It returns SOX_SUCCESS if everything went well
       or the return value from the format’s stopread or  stopwrite  (probably
       SOX_EOF)  otherwise  and  the  precise  reason for failure is passed to
       sox_warn() or sox_fail() to print the information.  In either case,  no
       further  use  should  be  made  to the handle, not even another call to
       sox_close().

       sox_find_effect() finds the effect called name, returning a pointer  to
       its sox_effect_handler_t if it exists, NULL otherwise.

       sox_create_effect()  instantiates  an  effect into a sox_effect_t given
       the address of a sox_effect_handler_t Any missing methods are automati‐
       cally set to the appropriate nothing method.  It returns a  pointer  to
       the new effect or NULL if it was not found or had problems starting up.

       sox_effect_options()  passes  options into an effect to control its be‐
       havior.  If it succeeds, effp‐>in_signal may[1] contain  the  rate  and
       channel  count at which it requires input data and effp‐>out_signal may
       contain the rate and channel count it outputs.   When  it  is  present,
       this  information  is  used[2]  to  ensure that appropriate effects are
       placed in the effects chain to handle any needed conversions.   It  re‐
       turns  the  number  of arguments consumed or SOX_EOF if any invalid op‐
       tions were passed.

       [1] Does the effect have the option of setting these or can you option‐
       ally set them?

       [2] Does it do this automatically or do you have to add the  right  ef‐
       fects?

       Setting  options  is  only supported before the effect is started.  The
       behavior is undefined if its called when the effect has already  start‐
       ed.

       sox_create_effects_chain()  creates  an  effects chain to which effects
       can be added.  in_enc and  out_enc  are  the  signal  encoding  of  the
       chain’s  input  and  output.   The  pointers  to in_enc and out_enc are
       stored internally, so their memory should not be freed until the effect
       chain has been deleted.  Their values may change to reflect  new  input
       or output encodings when effects start up or are restarted.  It returns
       a pointer to the new chain or NULL if something went wrong.

       sox_add_effect  adds an effect to a chain.  in specifies the input sig‐
       nal info for the effect, out is a suggestion as to what the output sig‐
       nal should be but, depending on the effect options given and on in, the
       effect can choose to do differently.  Whatever output rate and channels
       the effect produces are written back to in.  in should  be  stored  and
       passed to each call to sox_add_effect so that changes propagate to each
       new effect.  It returns SOX_SUCCESS if it was successful.

       sox_delete_effects_chain() closes an effects chain and releases any re‐
       sources   reserved   during  the  creation  of  the  chain.   It  calls
       sox_delete_effects() if any effects are still in the chain.

       SoX includes skeleton C files to assist  you  in  writing  new  formats
       (skelform.c)  and effects (skeleff.c).  New formats can often just deal
       with the header and then use raw.c’s routines for reading and writing.

       example0.c and example1.c are a good starting point to see how to write
       applications using libsox_ng and sox_ng.c itself is also a good  refer‐
       ence.

RETURN VALUE
       sox_seek returns 0 if it succeeds, SOX_EOF otherwise

       [6] TODO Need to set a global error and implement sox_tell.

ERRORS
       [7] TODO

INTERNALS
       SoX’s  formats  and  effects  operate with an internal sample format of
       signed 32‐bit integer.  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 in‐
       put 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.

       Representing samples as integers can cause problems when processing au‐
       dio.  For example, if an effect to mix down left and right channels in‐
       to one monophonic channel were to use the line

          *obuf++ = (*ibuf++ + *ibuf++)/2;

       distortion may occur since the intermediate addition  can  overflow  32
       bits.

          *obuf++ = *ibuf++/2 + *ibuf++/2;

       would  get  round the overflow but at the expense of the least signifi‐
       cant bit.

       Stereo data is stored with the left and right speaker data  in  succes‐
       sive  samples  and quadraphonic data is stored 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 stored 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 au‐
       dio: sampling rate, data size (8, 16 or 32 bits),  encoding  (unsigned,
       signed, floating point etc.), and the number of sound channels.  It al‐
       so  contains  other state information: whether the sample file needs to
       be byte‐swapped, whether sox_seek() will work,  its  suffix,  its  file
       stream pointer, its format pointer and the format’s private structure.

       The  private  area  is  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 an example of 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 into the header.  The private area is usually  not  very  large  and
       some  effects,  such as echo, lsx_malloc() larger areas for delay lines
       and such.

       A format has 6 routines:

       startread           Set up the format parameters, read in a data header
                           or do anything else that 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.  it returns the num‐
                           ber of samples actually read.

       stopread            Do what needs to be done when it has finished read‐
                           ing.

       startwrite          Set up the format parameters, maybe write out a da‐
                           ta header and any any other preliminaries for writ‐
                           ing the format.

       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, it will re‐
                           turn [7].

       [7] What? SOX_EOF or a short‐or‐0 number of samples?

       stopwrite           Typically, fix up the file header or whatever  else
                           needs to be done.

EFFECTS
       Each effect runs with one input and one output stream.  An effect’s im‐
       plementation  comprises  six  functions that may be called according to
       the following flow diagram:

       LOOP (invocations with different parameters)
         getopts
         LOOP (invocations with the same parameters)
           LOOP (channels)
             start
           LOOP (while there is input audio to process)
             LOOP (channels)
               flow
           LOOP (while there is output audio to generate)
             LOOP (channels)
               drain
           LOOP (channels)
             stop
         kill

       Functions that an effect does not need can be NULL.  An effect that  is
       marked  ‘MCHAN’ does not use the LOOP (channels) lines and must perform
       multiple channel processing inside the  affected  functions.   Multiple
       effect instances may be processed in parallel.

       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 SOX_EOF, this means  that  the  effect
                           will  not  read  any  more  data and can be used to
                           switch to drain mode sooner.

       drain               is called when there are no more  input  data  sam‐
                           ples.   If  the effect wishes to generate more data
                           samples, it copies the generated data into the giv‐
                           en buffer and returns the number of samples  gener‐
                           ated.   If  it  fills the buffer, it will be called
                           again; The echo effect uses this to fade away.

       stop                is called when there are no more input samples  and
                           no more output samples to process.  It is typically
                           used  to close or free resources such as memory and
                           temporary files that were allocated  during  start.
                           See echo.c for an example.

       kill                is  called  to allow resources allocated by getopts
                           to be released.  See pad.c for an example.

LINKING
       How you link against libsox_ng depends on how SoX  was  built  on  your
       system. For a static build, just link against the library. For a dynam‐
       ic  build,  use  libtool to link with the correct linker flags. See the
       libtool manual for details; basically, you use it like this:

          libtool --mode=link gcc -o prog /path/to/libsox_ng.la


LICENSE
       Copyright 1991-2015 Lance Norskog, Chris Bagwell and  sundry  contribu‐
       tors.

       This library is free software; you can redistribute it and/or modify it
       under  the  terms of the GNU General Public License version 2.1 as pub‐
       lished by the Free Software Foundation.

       This library is distributed in the hope that it  will  be  useful,  but
       WITHOUT  ANY  WARRANTY;  without  even  the  implied  warranty  of MER‐
       CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU  General
       Public License for more details.

AUTHORS
       The many authors and contributors are listed in the README file that is
       distributed with the source code.

SEE ALSO
       sox_ng(1), soxformat_ng(7), example*.c in the SoX source distribution.

libsox_ng                      February 19, 2011                        SoX(3)
