1SoX(3) Sound eXchange SoX(3)
2
6 libsox - SoX, an audio file-format and effect library
7
9 #include <sox.h>
10 int sox_format_init(void);
12 void sox_format_quit(void);
14 sox_format_t sox_open_read(const char *path, const sox_signalinfo_t *info, const char *filetype);
16 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);
18 sox_size_t sox_read(sox_format_t ft, sox_ssample_t *buf, sox_size_t len);
20 sox_size_t sox_write(sox_format_t ft, sox_ssample_t *buf, sox_size_t len);
22 int sox_close(sox_format_t ft);
24 int sox_seek(sox_format_t ft, sox_size_t offset, int whence);
26 sox_effect_handler_t const *sox_find_effect(char const *name);
28 sox_effect_t *sox_create_effect(sox_effect_handler_t const *eh);
30 int sox_effect_options(sox_effect_t *effp, int argc, char * const argv[]);
32 sox_effects_chain_t *sox_create_effects_chain(sox_encodinginfo_t const *in_enc, sox_encodinginfo_t const *out_enc);
34 void sox_delete_effects_chain(sox_effects_chain_t *ecp);
36 int sox_add_effect(sox_effects_chaint_t *chain, sox_effect_t*effp, sox_signalinfo_t *in, sox_signalinfo_t const *out);
38 cc file.c -o file -lsox
40
42 libsox is a library of sound sample file format readers/writers and
43 sound effects processors. It is mainly developed for use by SoX but is
44 useful for any sound application.
45 sox_format_init function performs some required initialization related
47 to all file format handlers. If compiled with dynamic library support
48 then this will detect and initialize all external libraries. This
49 should be called before any other file operations are performed.
50 sox_format_quit function performs some required cleanup related to all
52 file format handlers.
53 sox_open_input function opens the file for reading whose name is the
55 string pointed to by path and associates an sox_format_t with it. If
56 info is non-NULL then it will be used to specify the data format of the
57 input file. This is normally only needed for headerless audio files
58 since the information is not stored in the file. If filetype is non-
59 NULL then it will be used to specify the file type. If this is not
60 specified then the file type is attempted to be derived by looking at
61 the file header and/or the filename extension. A special name of "-"
62 can be used to read data from stdin.
63 sox_open_output function opens the file for writing whose name is the
65 string pointed to by path and associates an sox_format_t with it. If
66 info is non-NULL then it will be used to specify the data format of the
67 output file. Since most file formats can write data in different data
68 formats, this generally has to be specified. The info structure from
69 the input format handler can be specified to copy data over in the same
70 format. If comment is non-NULL, it will be written in the file header
71 for formats that support comments. If filetype is non-NULL then it will
72 be used to specify the file type. If this is not specified then the
73 file type is attempted to be derived by looking at the filename exten‐
74 sion. A special name of "-" can be used to write data to stdout.
75 The function sox_read reads len samples in to buf using the format han‐
77 dler specified by ft. All data read is converted to 32-bit signed sam‐
78 ples before being placed in to buf. The value of len is specified in
79 total samples. If its value is not evenly divisable by the number of
80 channels, undefined behavior will occur.
81 The function sox_write writes len samples from buf using the format
83 handler specified by ft. Data in buf must be 32-bit signed samples and
84 will be converted during the write process. The value of len is speci‐
85 fied in total samples. If its value is not evenly divisable by the num‐
86 ber of channels, undefined behavior will occur.
87 The sox_close function dissociates the named sox_format_t from its
89 underlying file or set of functions. If the format handler was being
90 used for output, any buffered data is written first.
91 The function sox_find_effect finds effect name, returning a pointer to
93 its sox_effect_handler_t if it exists, and NULL otherwise.
94 The function sox_create_effect instantiates an effect into a
96 sox_effect_t given a sox_effect_handler_t *. Any missing methods are
97 automatically set to the corresponding nothing method.
98 The function sox_effect_options allows passing options into the effect
100 to control its behavior. It will return SOX_EOF if there were any
101 invalid options passed in. On success, the effp->in_signal will
102 optional contain the rate and channel count it requires input data from
103 and effp->out_signal will optionally contain the rate and channel count
104 it outputs in. When present, this information should be used to make
105 sure appropriate effects are placed in the effects chain to handle any
106 needed conversions.
107 Passing in options is currently only supported when they are passed in
109 before the effect is ever started. The behavior is undefined if its
110 called once the effect is started.
111 sox_create_effects_chain will instantiate an effects chain that effects
113 can be added to. in_enc and out_enc are the signal encoding of the
114 input and output of the chain respectively. The pointers to in_enc and
115 out_enc are stored internally and so their memory should not be freed.
116 Also, it is OK if their values change over time to reflect new input or
117 output encodings as they are referenced only as effects start up or are
118 restarted.
119 sox_delete_effects_chain will release any resources reserved during the
121 creation of the chain. This will also call sox_delete_effects if any
122 effects are still in the chain.
123 sox_add_effect adds an effect to the chain. in specifies the input
125 signal info for this effect. out is a suggestion as to what the output
126 signal should be but depending on the effects given options and on in
127 the effect can choose to do differently. Whatever output rate and
128 channels the effect does produce are written back to in. It is meant
129 that in be stored and passed to each new call to sox_add_effect so that
130 changes will be propagated to each new effect.
131 SoX includes skeleton C files to assist you in writing new formats
133 (skelform.c) and effects (skeleff.c). Note that new formats can often
134 just deal with the header and then use raw.c's routines for reading and
135 writing.
136 example0.c and example1.c are a good starting point to see how to write
138 applications using libsox. sox.c itself is also a good reference.
139
142 Upon successful completion sox_open_input and sox_open_output return an
143 sox_format_t (which is a pointer). Otherwise, NULL is returned. TODO:
144 Need a way to return reason for failures. Currently, relies on sox_warn
145 to print information.
146 sox_read and sox_write return the number of samples successfully read
148 or written. If an error occurs, or the end-of-file is reached, the
149 return value is a short item count or SOX_EOF. TODO: sox_read does not
150 distiguish between end-of-file and error. Need an feof() and ferror()
151 concept to determine which occured.
152 Upon successful completion sox_close returns 0. Otherwise, SOX_EOF is
154 returned. In either case, any further access (including another call to
155 sox_close()) to the handler results in undefined behavior. TODO: Need a
156 way to return reason for failures. Currently, relies on sox_warn to
157 print information.
158 Upon successful completion sox_seek returns 0. Otherwise, SOX_EOF is
160 returned. TODO Need to set a global error and implement sox_tell.
161
163 TODO
164
166 SoX's formats and effects operate with an internal sample format of
167 signed 32-bit integer. The data processing routines are called with
168 buffers of these samples, and buffer sizes which refer to the number of
169 samples processed, not the number of bytes. File readers translate the
170 input samples to signed 32-bit integers and return the number of sam‐
171 ples read. For example, data in linear signed byte format is left-
172 shifted 24 bits.
173 Representing samples as integers can cause problems when processing the
175 audio. For example, if an effect to mix down left and right channels
176 into one monophonic channel were to use the line
177 *obuf++ = (*ibuf++ + *ibuf++)/2;
178 distortion might occur since the intermediate addition can overflow 32
179 bits. The line
180 *obuf++ = *ibuf++/2 + *ibuf++/2;
181 would get round the overflow problem (at the expense of the least sig‐
182 nificant bit).
183 Stereo data is stored with the left and right speaker data in succes‐
185 sive samples. Quadraphonic data is stored in this order: left front,
186 right front, left rear, right rear.
187
189 A format is responsible for translating between sound sample files and
190 an internal buffer. The internal buffer is store in signed longs with
191 a fixed sampling rate. The format operates from two data structures: a
192 format structure, and a private structure.
193 The format structure contains a list of control parameters for the sam‐
195 ple: sampling rate, data size (8, 16, or 32 bits), encoding (unsigned,
196 signed, floating point, etc.), number of sound channels. It also con‐
197 tains other state information: whether the sample file needs to be
198 byte-swapped, whether sox_seek() will work, its suffix, its file stream
199 pointer, its format pointer, and the private structure for the format .
200 The private area is just a preallocated data array for the format to
202 use however it wishes. It should have a defined data structure and
203 cast the array to that structure. See voc.c for the use of a private
204 data area. Voc.c has to track the number of samples it writes and when
205 finishing, seek back to the beginning of the file and write it out.
206 The private area is not very large. The ``echo'' effect has to mal‐
207 loc() a much larger area for its delay line buffers.
208 A format has 6 routines:
210 startread Set up the format parameters, or read in a data
212 header, or do what needs to be done.
213 read Given a buffer and a length: read up to that many
215 samples, transform them into signed long integers,
216 and copy them into the buffer. Return the number
217 of samples actually read.
218 stopread Do what needs to be done.
220 startwrite Set up the format parameters, or write out a data
222 header, or do what needs to be done.
223 write Given a buffer and a length: copy that many samples
225 out of the buffer, convert them from signed longs
226 to the appropriate data, and write them to the
227 file. If it can't write out all the samples, fail.
228 stopwrite Fix up any file header, or do what needs to be
230 done.
231
233 Each effect runs with one input and one output stream. An effect's
234 implementation comprises six functions that may be called to the follow
235 flow diagram:
236 LOOP (invocations with different parameters)
237 getopts
238 LOOP (invocations with the same parameters)
239 LOOP (channels)
240 start
241 LOOP (whilst there is input audio to process)
242 LOOP (channels)
243 flow
244 LOOP (whilst there is output audio to generate)
245 LOOP (channels)
246 drain
247 LOOP (channels)
248 stop
249 kill
250 Notes: For some effects, some of the functions may not be needed and
251 can be NULL. An effect that is marked `MCHAN' does not use the LOOP
252 (channels) lines and must therefore perform multiple channel processing
253 inside the affected functions. Multiple effect instances may be pro‐
254 cessed (according to the above flow diagram) in parallel.
255 getopts is called with a character string argument list for
257 the effect.
258 start is called with the signal parameters for the input
260 and output streams.
261 flow is called with input and output data buffers, and
263 (by reference) the input and output data buffer
264 sizes. It processes the input buffer into the out‐
265 put buffer, and sets the size variables to the num‐
266 bers of samples actually processed. It is under no
267 obligation to read from the input buffer or write
268 to the output buffer during the same call. If the
269 call returns SOX_EOF then this should be used as an
270 indication that this effect will no longer read any
271 data and can be used to switch to drain mode
272 sooner.
273 drain is called after there are no more input data sam‐
275 ples. If the effect wishes to generate more data
276 samples it copies the generated data into a given
277 buffer and returns the number of samples generated.
278 If it fills the buffer, it will be called again,
279 etc. The echo effect uses this to fade away.
280 stop is called when there are no more input samples and
282 no more output samples to process. It is typically
283 used to release or close resources (e.g. allocated
284 memory or temporary files) that were set-up in
285 start. See echo.c for an example.
286 kill is called to allow resources allocated by getopts
288 to be released. See pad.c for an example.
289
291 The method of linking against libsox depends on how SoX was built on
292 your system. For a static build, just link against the libraries as
293 normal. For a dynamic build, you should use libtool to link with the
294 correct linker flags. See the libtool manual for details; basically,
295 you use it as:
296 libtool --mode=link gcc -o prog /path/to/libsox.la
297
299 This manual page is both incomplete and out of date.
300
302 sox(1), soxformat(7)
303 example*.c in the SoX source distribution.
305
307 Copyright 1998-2011 by Chris Bagwell and SoX Contributors.
308 Copyright 1991 Lance Norskog and Sundry Contributors.
309 This library is free software; you can redistribute it and/or modify it
311 under the terms of the GNU Lesser General Public License as published
312 by the Free Software Foundation; either version 2.1, or (at your
313 option) any later version.
314 This library is distributed in the hope that it will be useful, but
316 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
317 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
318 General Public License for more details.
319
321 Chris Bagwell (cbagwell@users.sourceforge.net). Other authors and con‐
322 tributors are listed in the ChangeLog file that is distributed with the
323 source code.
324libsox February 19, 2011 SoX(3)