libsox(3)


NAME

   libsox - SoX, an audio file-format and effect library

SYNOPSIS

   #include <sox.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, const char *filetype);

   sox_format_t sox_open_write(sox_bool (*overwrite_permitted)(const char *filename), const char *path, const sox_signalinfo_t *info, const char *filetype, const char *comment, sox_size_t length, const sox_instrinfo_t *instr, const sox_loopinfo_t *loops);

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

   sox_size_t sox_write(sox_format_t ft, sox_ssample_t *buf, sox_size_t len);

   int sox_close(sox_format_t ft);

   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);

   void sox_delete_effects_chain(sox_effects_chain_t *ecp);

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

   cc file.c -o file -lsox

DESCRIPTION

   libsox  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.

   sox_format_init  function performs some required initialization related
   to all file format handlers.  If compiled with dynamic library  support
   then  this  will  detect  and  initialize all external libraries.  This
   should be called before any other file operations are performed.

   sox_format_quit function performs some required cleanup related to  all
   file format handlers.

   sox_open_input  function  opens  the file for reading whose name is the
   string pointed to by path and associates an sox_format_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
   specified  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.

   sox_open_output  function  opens the file for writing whose name is the
   string pointed to by path and associates an sox_format_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
   formats,  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
   extension. A special name of "-" can be used to write data to stdout.

   The  function  sox_read  reads  len  samples in to buf using the format
   handler specified by ft. All data read is converted  to  32-bit  signed
   samples 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  sox_write  writes  len samples from buf using the format
   handler 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
   specified in total samples. If its value is not evenly divisable by the
   number of channels, undefined behavior will occur.

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

   The  function sox_find_effect finds effect name, returning a pointer to
   its sox_effect_handler_t if it exists, and NULL otherwise.

   The  function  sox_create_effect  instantiates   an   effect   into   a
   sox_effect_t  given  a  sox_effect_handler_t *. Any missing methods are
   automatically set to the corresponding nothing method.

   The function sox_effect_options allows passing options into the  effect
   to  control  its  behavior.   It  will return SOX_EOF if there were any
   invalid options  passed  in.   On  success,  the  effp->in_signal  will
   optional contain the rate and channel count it requires input data from
   and effp->out_signal will optionally contain the rate and channel count
   it  outputs  in.  When present, this information should be used to make
   sure appropriate effects are placed in the effects chain to handle  any
   needed conversions.

   Passing  in options is currently only supported when they are passed in
   before the effect is ever started.  The behavior is  undefined  if  its
   called once the effect is started.

   sox_create_effects_chain will instantiate an effects chain that effects
   can be added to.  in_enc and out_enc are the  signal  encoding  of  the
   input and output of the chain respectively.  The pointers to in_enc and
   out_enc are stored internally and so their memory should not be  freed.
   Also, it is OK if their values change over time to reflect new input or
   output encodings as they are referenced only as effects start up or are
   restarted.

   sox_delete_effects_chain will release any resources reserved during the
   creation of the chain.  This will also call sox_delete_effects  if  any
   effects are still in the chain.

   sox_add_effect  adds  an  effect  to the chain.  in specifies the input
   signal info for this effect.  out is a suggestion as to what the output
   signal  should  be but depending on the effects given options and on in
   the effect can choose to do  differently.   Whatever  output  rate  and
   channels  the  effect does produce are written back to in.  It is meant
   that in be stored and passed to each new call to sox_add_effect so that
   changes will be propagated to each new effect.

   SoX  includes  skeleton  C  files  to assist you in writing new formats
   (skelform.c) and effects (skeleff.c). Note that 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.  sox.c itself is also a good reference.

RETURN VALUE

   Upon successful completion sox_open_input and sox_open_output return an
   sox_format_t (which is a pointer).  Otherwise, NULL is returned.  TODO:
   Need a way to return reason for failures. Currently, relies on sox_warn
   to print information.

   sox_read and sox_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 SOX_EOF. TODO: sox_read does  not
   distiguish  between  end-of-file and error. Need an feof() and ferror()
   concept to determine which occured.

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

   Upon successful completion sox_seek returns 0.  Otherwise,  SOX_EOF  is
   returned. TODO Need to set a global error and implement sox_tell.

ERRORS

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

   Representing samples as integers can cause problems when processing the
   audio.  For example, if an effect to mix down left and  right  channels
   into one monophonic channel were to use the line
      *obuf++ = (*ibuf++ + *ibuf++)/2;
   distortion  might occur since the intermediate addition can overflow 32
   bits.  The line
      *obuf++ = *ibuf++/2 + *ibuf++/2;
   would get round the overflow problem  (at  the  expense  of  the  least
   significant bit).

   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  (8,  16,  or  32  bits), encoding
   (unsigned, signed, floating point, etc.), number of sound channels.  It
   also 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 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  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

   Each  effect  runs  with  one input and one output stream.  An effect's
   implementation comprises six functions that may be called to the follow
   flow diagram:
   LOOP (invocations with different parameters)
     getopts
     LOOP (invocations with the same parameters)
       LOOP (channels)
         start
       LOOP (whilst there is input audio to process)
         LOOP (channels)
           flow
       LOOP (whilst there is output audio to generate)
         LOOP (channels)
           drain
       LOOP (channels)
         stop
     kill
   Notes:  For  some  effects, some of the functions may not be needed and
   can be NULL.  An effect that is marked `MCHAN' does not  use  the  LOOP
   (channels) lines and must therefore perform multiple channel processing
   inside the  affected  functions.   Multiple  effect  instances  may  be
   processed (according to the above flow diagram) 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
                       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 SOX_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 and
                       no more output samples to process.  It is typically
                       used  to release or close resources (e.g. allocated
                       memory or temporary  files)  that  were  set-up  in
                       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

   The method of linking against libsox depends on how SoX  was  built  on
   your  system.  For  a  static build, just link against the libraries as
   normal. For a dynamic build, you should use libtool to  link  with  the
   correct  linker  flags.  See the libtool manual for details; basically,
   you use it as:
      libtool --mode=link gcc -o prog /path/to/libsox.la

BUGS

   This manual page is both incomplete and out of date.

SEE ALSO

   sox(1), soxformat(7)

   example*.c in the SoX source distribution.

LICENSE

   Copyright 1998-2011 by Chris Bagwell and SoX Contributors.
   Copyright 1991 Lance Norskog and Sundry Contributors.

   This library is free software; you can redistribute it and/or modify it
   under  the  terms of the GNU Lesser General Public License as published
   by the Free Software  Foundation;  either  version  2.1,  or  (at  your
   option) any later version.

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

AUTHORS

   Chris  Bagwell  (cbagwell@users.sourceforge.net).   Other  authors  and
   contributors  are listed in the ChangeLog file that is distributed with
   the source code.





Opportunity


Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.

Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.





Free Software


Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.


Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.





Free Books


The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.


Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.





Education


Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.


Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.