ref: cabb81cf67378540e1a4ba81f39e25f3e843d026
dir: /libsox.3/
'\" 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 .ds d \v'-.15m'.\v'+.15m' '\" .TH SoX 3 "January 31, 2007" .SH NAME libsox \- SoX, an audio file-format and effect library .SH SYNOPSIS .nf .B #include <sox.h> .P .B int sox_format_init(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 void sox_create_effect(sox_effect_t \fIeffp\fB, sox_effect_handler_t const *\fIe\fB); .P .B cc \fIfile.c\fB -o \fIfile \f-lsox .fi .SH DESCRIPTION .I 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. .P \fBsox_format_init\fR 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. .P \fBsox_open_input\fR function opens the file for reading whose name is the 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 format of the input file. This is normally only needed for headerless audio files since the information is not stored in the file. If \fIfiletype\fR 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. .P \fBsox_open_output\fR function opens the file for writing whose name is the 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 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 \fIcomment\fR is non-NULL, it will be written in the file header for formats that support comments. If \fIfiletype\fR 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. .P The function \fBsox_read\fR reads \fIlen\fR samples in to \fIbuf\fR using the format handler specified by \fIft\fR. All data read is converted to 32-bit signed samples before being placed in to \fIbuf\fR. The value of \fIlen\fR is specified in total samples. If its value is not evenly divisable by the number of channels, undefined behavior will occur. .P The function \fBsox_write\fR writes \fIlen\fR samples from \fIbuf\fR using the format handler specified by \fIft\fR. Data in \fIbuf\fR must be 32-bit signed samples and will be converted during the write process. The value of \fIlen\fR is specified in total samples. If its value is not evenly divisable by the number of channels, undefined behavior will occur. .P The \fBsox_close\fR function dissociates the named \fIsox_format_t\fR from its underlying file or set of functions. If the format handler was being used for output, any buffered data is written first. .P \fBsox_format_quite\fR function performs some required cleanup related to all file format handlers. .P The function \fBsox_find_effect\fR finds effect \fIname\fR, returning a pointer to its \fIsox_effect_handler_t\fR if it exists, and NULL otherwise. .P The function \fBsox_create_effect\fR instantiates an effect into a \fIsox_effect_t\fR given a \fIsox_effect_handler_t *\fR. Any missing methods are automatically set to the corresponding \fBnothing\fR method. .P The \fBsox_update_effect\fR function copies input and output signal info into effect structures. The \fIeffect_mask\fR parameter is the return value of the previous call to this function; for the first call, pass 0. The function returns the updated effect mask. .P SoX includes skeleton C files to assist you in writing new formats (skelform.c) and effects (skeleff.c). sox.c itself is a good starting point for new programs. Note that new formats can often just deal with the header and then use raw.c's routines for reading and writing. .SH RETURN VALUE Upon successful completion \fBsox_open_input\fR and \fBsox_open_output\fR return an \fIsox_format_t\fR (which is a pointer). Otherwise, NULL is returned. TODO: Need a way to return reason for failures. Currently, relies on \fBsox_warn\fR to print information. .P \fBsox_read\fR and \fBsox_write\fR 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: \fBsox_read\fR does not distiguish between end-of-file and error. Need an feof() and ferror() concept to determine which occured. .P Upon successful completion \fBsox_close\fR returns 0. Otherwise, SOX_EOF is returned. In either case, any further access (including another call to \fBsox_close\fR()) to the handler results in undefined behavior. TODO: Need a way to return reason for failures. Currently, relies on sox_warn to print information. .P Upon successful completion \fBsox_seek\fR returns 0. Otherwise, SOX_EOF is returned. TODO Need to set a global error and implement sox_tell. .SH ERRORS TODO .SH INTERNALS SoX's 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 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. .P This does cause problems in processing the data. For example: .br *obuf++ = (*ibuf++ + *ibuf++)/2; .br would .I not mix down left and right channels into one monophonic channel, because the resulting samples would overflow 32 bits. Instead, the ``avg'' effects must use: .br *obuf++ = *ibuf++/2 + *ibuf++/2; .br .P 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. .SH FORMATS A .I 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 .I format operates from two data structures: a format structure, and a private structure. .P 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 .I format pointer, and the .I private structure for the .I format . .P The .I private area is just a preallocated data array for the .I 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. .P A .I format has 6 routines: .TP 20 startread Set up the format parameters, or read in a data header, or do what needs to be done. .TP 20 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. .TP 20 stopread Do what needs to be done. .TP 20 startwrite Set up the format parameters, or write out a data header, or do what needs to be done. .TP 20 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. .TP 20 stopwrite Fix up any file header, or do what needs to be done. .SH EFFECTS An effects loop has one input and one output stream. It has 5 routines. .TP 20 getopts is called with a character string argument list for the effect. .TP 20 start is called with the signal parameters for the input and output streams. .TP 20 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. .TP 20 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. .TP 20 stop is called when there are no more input samples to process. .I 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. .SH LINKING The method of linking against libsox and libsfx 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: .SP libtool --mode=link gcc -o prog /path/to/libsox.la /path/to/libsfx.la .SP .SH BUGS This manual page is both incomplete and out of date. .SH SEE ALSO .BR sox (1), .BR soxexam (7) .SH LICENSE Copyright 1991 Lance Norskog and Sundry Contributors. Copyright 1998\-2007 by Chris Bagwell and SoX Contributors. .SP 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. .SP 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. .SH AUTHORS Chris Bagwell (cbagwell@users.sourceforge.net). Other authors and contributors are listed in the AUTHORS file that is distributed with the source code.