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 on an internal buffer format of
167 signed 32-bit longs. The data processing routines are called with buf‐
168 fers 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 This does cause problems in processing the data. For example:
175 *obuf++ = (*ibuf++ + *ibuf++)/2;
176 would not mix down left and right channels into one monophonic channel,
177 because the resulting samples would overflow 32 bits. Instead, the
178 ``avg'' effects must use:
179 *obuf++ = *ibuf++/2 + *ibuf++/2;
180 Stereo data is stored with the left and right speaker data in succes‐
182 sive samples. Quadraphonic data is stored in this order: left front,
183 right front, left rear, right rear.
184
186 A format is responsible for translating between sound sample files and
187 an internal buffer. The internal buffer is store in signed longs with
188 a fixed sampling rate. The format operates from two data structures: a
189 format structure, and a private structure.
190 The format structure contains a list of control parameters for the sam‐
192 ple: sampling rate, data size (8, 16, or 32 bits), encoding (unsigned,
193 signed, floating point, etc.), number of sound channels. It also con‐
194 tains other state information: whether the sample file needs to be
195 byte-swapped, whether sox_seek() will work, its suffix, its file stream
196 pointer, its format pointer, and the private structure for the format .
197 The private area is just a preallocated data array for the format to
199 use however it wishes. It should have a defined data structure and
200 cast the array to that structure. See voc.c for the use of a private
201 data area. Voc.c has to track the number of samples it writes and when
202 finishing, seek back to the beginning of the file and write it out.
203 The private area is not very large. The ``echo'' effect has to mal‐
204 loc() a much larger area for its delay line buffers.
205 A format has 6 routines:
207 startread Set up the format parameters, or read in a data
209 header, or do what needs to be done.
210 read Given a buffer and a length: read up to that many
212 samples, transform them into signed long integers,
213 and copy them into the buffer. Return the number
214 of samples actually read.
215 stopread Do what needs to be done.
217 startwrite Set up the format parameters, or write out a data
219 header, or do what needs to be done.
220 write Given a buffer and a length: copy that many samples
222 out of the buffer, convert them from signed longs
223 to the appropriate data, and write them to the
224 file. If it can't write out all the samples, fail.
225 stopwrite Fix up any file header, or do what needs to be
227 done.
228
230 An effects loop has one input and one output stream. It has 5 rou‐
231 tines.
232 getopts is called with a character string argument list for
234 the effect.
235 start is called with the signal parameters for the input
237 and output streams.
238 flow is called with input and output data buffers, and
240 (by reference) the input and output data buffer
241 sizes. It processes the input buffer into the out‐
242 put buffer, and sets the size variables to the num‐
243 bers of samples actually processed. It is under no
244 obligation to read from the input buffer or write
245 to the output buffer during the same call. If the
246 call returns SOX_EOF then this should be used as an
247 indication that this effect will no longer read any
248 data and can be used to switch to drain mode
249 sooner.
250 drain is called after there are no more input data sam‐
252 ples. If the effect wishes to generate more data
253 samples it copies the generated data into a given
254 buffer and returns the number of samples generated.
255 If it fills the buffer, it will be called again,
256 etc. The echo effect uses this to fade away.
257 stop is called when there are no more input samples to
259 process. stop may generate output samples on its
260 own. See echo.c for how to do this, and see that
261 what it does is absolutely bogus.
262
264 The method of linking against libsox and libsfx depends on how SoX was
265 built on your system. For a static build, just link against the
266 libraries as normal. For a dynamic build, you should use libtool to
267 link with the correct linker flags. See the libtool manual for details;
268 basically, you use it as:
269 libtool --mode=link gcc -o prog /path/to/libsox.la /path/to/lib‐
271 sfx.la
272
275 This manual page is both incomplete and out of date.
276
278 sox(1), soxformat(7)
279 example*.c in the SoX source distribution.
281
283 Copyright 1991 Lance Norskog and Sundry Contributors. Copyright
284 1998-2007 by Chris Bagwell and SoX Contributors.
285 This library is free software; you can redistribute it and/or modify it
287 under the terms of the GNU Lesser General Public License as published
288 by the Free Software Foundation; either version 2.1, or (at your
289 option) any later version.
290 This library is distributed in the hope that it will be useful, but
292 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
293 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
294 General Public License for more details.
295
297 Chris Bagwell (cbagwell@users.sourceforge.net). Other authors and con‐
298 tributors are listed in the AUTHORS file that is distributed with the
299 source code.
300libsox July 27, 2008 SoX(3)