'\" t'\" The line above instructs most `man' programs to invoke tbl'\"'\" Separate paragraphs; not the same as PP which resets indent level..de SP.if t .sp .5.if n .sp..'\"'\" Replacement em-dash for nroff (default is too short)..ie n .ds m " - .el .ds m \(em'\"'\" Placeholder macro for if longer nroff arrow is needed..ds RA \(->'\"'\" Decimal point set slightly raised.if t .ds d \v'-.15m'.\v'+.15m'.if n .ds d .'\"'\" Enclosure macro for examples.de EX.SP.nf.ft CW...de EE.ft R.SP.fi...TH SoX 3 "February 19, 2011" "libsox" "Sound eXchange".SH NAMElibsox \- SoX, an audio file-format and effect library.SH SYNOPSIS.nf.B #include <sox.h>.P.B int sox_format_init(void);.P.B void sox_format_quit(void);.P.B sox_format_t sox_open_read(const char *\fIpath\fB, const sox_signalinfo_t *\fIinfo\fB, const char *\fIfiletype\fB);.P.B sox_format_t sox_open_write(sox_bool (*\fIoverwrite_permitted\fB)(const char *\fIfilename\fB), const char *\fIpath\fB, const sox_signalinfo_t *\fIinfo\fB, const char *\fIfiletype\fB, const char *\fIcomment\fB, sox_size_t \fIlength\fB, const sox_instrinfo_t *\fIinstr\fB, const sox_loopinfo_t *\fIloops\fB);.P.B sox_size_t sox_read(sox_format_t \fIft\fB, sox_ssample_t *\fIbuf\fB, sox_size_t \fIlen\fB);.P.B sox_size_t sox_write(sox_format_t \fIft\fB, sox_ssample_t *\fIbuf\fB, sox_size_t \fIlen\fB);.P.B int sox_close(sox_format_t \fIft\fB);.P.B int sox_seek(sox_format_t \fIft\fB, sox_size_t \fIoffset\fB, int \fIwhence\fB);.P.B sox_effect_handler_t const *sox_find_effect(char const *\fIname\fB);.P.B sox_effect_t *sox_create_effect(sox_effect_handler_t const *\fIeh\fB);.P.B int sox_effect_options(sox_effect_t *\fIeffp\fB, int \fIargc\fB, char * const \fIargv[]\fB);.P.B sox_effects_chain_t *sox_create_effects_chain(sox_encodinginfo_t const *\fIin_enc\fB, sox_encodinginfo_t const *\fIout_enc\fB);.P.B void sox_delete_effects_chain(sox_effects_chain_t *\fIecp\fB);.P.B int sox_add_effect(sox_effects_chaint_t *\fIchain\fB, sox_effect_t*\fIeffp\fB, sox_signalinfo_t *\fIin\fB, sox_signalinfo_t const *\fIout\fB);.P.B cc \fIfile.c\fB -o \fIfile \fB-lsox.fi.SH DESCRIPTION.I libsoxis a library of sound sample file format readers/writers and soundeffects processors. It is mainly developed for use by SoX but isuseful for any sound application..P\fBsox_format_init\fR function performs some required initializationrelated to all file format handlers.  If compiled with dynamiclibrary support then this will detect and initialize all externallibraries.  This should be called before any other file operationsare performed..P\fBsox_format_quit\fR function performs some required cleanuprelated to all file format handlers..P\fBsox_open_read\fR function opens the file for reading whose name isthe string pointed to by \fIpath\fR and associates an sox_format_t with it. If\fIinfo\fR is non-NULL then it will be used to specify the data formatof the input file. This is normally only needed for headerless audiofiles since the information is not stored in the file. If\fIfiletype\fR is non-NULL then it will be used to specify the filetype. If this is not specified then the file type is attempted to bederived by looking at the file header and/or the filename extension. Aspecial name of "-" can be used to read data from stdin..P\fBsox_open_write\fR function opens the file for writing whose name isthe string pointed to by \fIpath\fR and associates an sox_format_t with it. If\fIinfo\fR is non-NULL then it will be used to specify the data formatof the output file. Since most file formats can write data indifferent data formats, this generally has to be specified. The infostructure from the input format handler can be specified to copy dataover in the same format. If \fIcomment\fR is non-NULL, it will bewritten in the file header for formats that support comments. If\fIfiletype\fR is non-NULL then it will be used to specify the filetype. If this is not specified then the file type is attempted to bederived by looking at the filename extension. A special name of "-"can be used to write data to stdout..PThe function \fBsox_read\fR reads \fIlen\fR samples in to \fIbuf\fRusing the format handler specified by \fIft\fR. All data read isconverted to 32-bit signed samples before being placed in to\fIbuf\fR. The value of \fIlen\fR is specified in total samples. Ifits value is not evenly divisable by the number of channels, undefinedbehavior will occur..PThe function \fBsox_write\fR writes \fIlen\fR samples from \fIbuf\fRusing the format handler specified by \fIft\fR. Data in \fIbuf\fR mustbe 32-bit signed samples and will be converted during the writeprocess. The value of \fIlen\fR is specified in total samples. If itsvalue is not evenly divisable by the number of channels, undefinedbehavior will occur..PThe \fBsox_close\fR function dissociates the named \fIsox_format_t\fR from itsunderlying file or set of functions. If the format handler was beingused for output, any buffered data is written first..PThe function \fBsox_find_effect\fR finds effect \fIname\fR, returninga pointer to its \fIsox_effect_handler_t\fR if it exists, and NULLotherwise..PThe function \fBsox_create_effect\fR instantiates an effect into a\fIsox_effect_t\fR given a \fIsox_effect_handler_t *\fR. Any missingmethods are automatically set to the corresponding \fBnothing\fRmethod..PThe function \fBsox_effect_options\fR 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 \fIeffp->in_signal\fR will optional contain the rate and channel count it requires input data from and \fIeffp->out_signal\fR 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..PPassing 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..P\fBsox_create_effects_chain\fR will instantiate an effects chain thateffects can be added to.  \fIin_enc\fR and \fIout_enc\fR are the signal encoding of the input and output of the chain respectively.The pointers to \fIin_enc\fR and \fIout_enc\fRare stored internally and so their memory should not be freed.  Also,it is OK if their values change over time to reflect new input oroutput encodings as they are referenced only as effectsstart up or are restarted..P\fBsox_delete_effects_chain\fR will release any resources reserved duringthe creation of the chain.  This will also call \fBsox_delete_effects\fRif any effects are still in the chain..P\fBsox_add_effect\fR adds an effect to the chain.  \fIin\fR specifies the inputsignal info for this effect.  \fIout\fR is a suggestionas to what the output signal should be but depending on the effectsgiven options and on \fIin\fR the effect can choose to do differently.Whatever output rate and channels the effect does produce are writtenback to \fIin\fR.  It is meant that \fIin\fR be stored and passed to eachnew call to \fBsox_add_effect\fR so that changes will be propagated to each new effect..PSoX includes skeleton C files to assist you in writing newformats (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 howto write applications using libsox.  sox.c itself is also a goodreference. .SH RETURN VALUEUpon successful completion \fBsox_open_read\fR and\fBsox_open_write\fR return an \fIsox_format_t\fR (which is a pointer).Otherwise, NULL is returned. TODO: Need a way to return reason forfailures. Currently, relies on \fBsox_warn\fR to print information..P\fBsox_read\fR and \fBsox_write\fR return the number of samplessuccessfully read or written. If an error occurs, or the end-of-fileis reached, the return value is a short item count or SOX_EOF. TODO:\fBsox_read\fR does not distiguish between end-of-file and error. Needan feof() and ferror() concept to determine which occurred..PUpon successful completion \fBsox_close\fR returns 0. Otherwise, SOX_EOFis returned. In either case, any further access (including anothercall to \fBsox_close\fR()) to the handler results in undefinedbehavior. TODO: Need a way to return reason for failures. Currently,relies on sox_warn to print information..PUpon successful completion \fBsox_seek\fR returns 0. Otherwise, SOX_EOFis returned. TODO Need to set a global error and implement sox_tell..SH ERRORSTODO.SH INTERNALSSoX's formats and effects operate with an internal sample format ofsigned 32-bit integer.  The data processing routines are called withbuffers of these samples, and buffer sizes which refer to the numberof samples processed, not the number of bytes.  File readers translatethe input samples to signed 32-bit integers and return the number ofsamples read.  For example, data in linear signed byte format isleft-shifted 24 bits..PRepresenting samples as integers can cause problems when processing the audio.  For example, if an effect tomix down left and right channels into one monophonic channelwere to use the line.EX   *obuf++ = (*ibuf++ + *ibuf++)/2;.EEdistortion might occur sincethe intermediate addition can overflow 32 bits.The line.EX   *obuf++ = *ibuf++/2 + *ibuf++/2;.EEwould get round the overflow problem (at the expense of the least significantbit)..PStereo data is stored with the left and right speaker data insuccessive samples.Quadraphonic data is stored in this order: left front, right front, left rear, right rear..SH FORMATSA .I format is responsible for translating between sound sample filesand an internal buffer.  The internal buffer is store in signed longswith a fixed sampling rate.  The .I formatoperates from two data structures:a format structure, and a private structure..PThe format structure contains a list of control parameters forthe 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 fileneeds to be byte-swapped, whether sox_seek() will work, its suffix,its file stream pointer, its .I formatpointer, and the .I privatestructure for the .I format ..PThe .I private area is just a preallocated data array for the .I formatto use however it wishes.  It should have a defined data structureand 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 fileand write it out.The private area is not very large.The ``echo'' effect has to malloc() a much larger area for itsdelay line buffers..PA .I formathas 6 routines:.TP 20startreadSet up the format parameters, or read ina data header, or do what needs to be done..TP 20readGiven 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..TP 20stopreadDo what needs to be done..TP 20startwriteSet up the format parameters, or write out a data header, or do what needs to be done..TP 20writeGiven a buffer and a length: copy that many samples out of the buffer,convert them from signed longs to the appropriatedata, and write them to the file.If it can't write out all the samples,fail..TP 20stopwriteFix up any file header, or do what needs to be done..SH EFFECTSEach effect runs with one input and one output stream.An effect's implementation comprises six functions that may be calledto the follow flow diagram:.EXLOOP (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.EENotes: For some effects, some of the functions may not be needed and canbe NULL.  An effect that is marked `MCHAN' does not use the LOOP(channels) lines and must therefore perform multiple channel processinginside the affected functions.  Multiple effect instances may beprocessed (according to the above flow diagram) in parallel..TP 20getoptsis called with a character string argument list for the effect..TP 20startis called with the signal parameters for the input and outputstreams..TP 20 flowis 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 samplesactually processed.It is under no obligation to read from the input buffer orwrite to the output buffer during the same call.  If thecall returns SOX_EOF then this should be used as an indicationthat this effect will no longer read any data and can be usedto switch to drain mode sooner..TP 20 drainis called after there are no more input data samples.If the effect wishes to generate more data samplesit copies the generated data into a given bufferand 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..TP 20stopis called when there are no more input samples and no more outputsamples to process.It is typically used to release or close resources (e.g. allocatedmemory or temporary files) that were set-up in.IR start .See echo.c for an example..TP 20killis called to allow resources allocated by.I getoptsto be released.See pad.c for an example..SH LINKINGThe method of linking against libsox depends on how SoX wasbuilt on your system. For a static build, just link against thelibraries as normal. For a dynamic build, you should use libtool tolink with the correct linker flags. See the libtool manual fordetails; basically, you use it as:.EX   libtool \-\-mode=link gcc \-o prog /path/to/libsox.la.EE.SH BUGSThis manual page is both incomplete and out of date..SH SEE ALSO.BR sox (1),.BR soxformat (7).SPexample*.c in the SoX source distribution..SH LICENSECopyright 1998\-2011 by Chris Bagwell and SoX Contributors..brCopyright 1991 Lance Norskog and Sundry Contributors..SPThis library is free software; you can redistribute it and/or modifyit under the terms of the GNU Lesser General Public License as published bythe Free Software Foundation; either version 2.1, or (at your option)any later version..SPThis library is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty ofMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See theGNU Lesser General Public License for more details..SH AUTHORSChris Bagwell (cbagwell@users.sourceforge.net).Other authors and contributors are listed in the ChangeLog file thatis distributed with the source code.