1ST(3) Library Functions Manual ST(3)
2
6 libst - Sound Tools - Audio file-format and effect library
7
9 #include <st.h>
10 ft_t st_open_input(const char *path, const st_signalinfo_t *info, const char *filetype);
12 ft_t st_open_output(const char *path, const st_signalinfo_t *info, const char *filetype, const char *comment);
14 st_ssize_t st_read(ft_t ft, st_sample_t *buf, st_ssize_t len);
16 st_ssize_t st_write(ft_t ft, st_sample_t *buf, st_ssize_t len);
18 int st_close(ft_t ft);
20 int st_seek(ft_t ft, st_size_t offset, int whence);
22 cc file.c -o file libst.a
24
26 Sound Tools is a library of sound sample file format readers/writers
27 and sound effects processors. It is mainly developed for use by SoX but
28 is useful for any sound application.
29 st_open_input function opens the file for reading whose name is the
31 string pointed to by path and associates an ft_t with it. If info is
32 non-NULL then it will be used to specify the data format of the input
33 file. This is normally only needed for headerless audio files since the
34 information is not stored in the file. If filetype is non-NULL then it
35 will be used to specify the file type. If this is not specified then
36 the file type is attempted to be derived by looking at the file header
37 and/or the filename extension. A special name of "-" can be used to
38 read data from stdin.
39 st_open_output function opens the file for writing whose name is the
41 string pointed to by path and associates an ft_t with it. If info is
42 non-NULL then it will be used to specify the data format of the output
43 file. Since most file formats can write data in different data formats,
44 this generally has to be specified. The info structure from the input
45 format handler can be specified to copy data over in the same format.
46 If comment is non-NULL, it will be written in the file header for for‐
47 mats that support comments. If filetype is non-NULL then it will be
48 used to specify the file type. If this is not specified then the file
49 type is attempted to be derived by looking at the filename extension. A
50 special name of "-" can be used to write data to stdout.
51 The function st_read reads len samples in to buf using the format han‐
53 dler specified by ft. All data read is converted to 32-bit signed sam‐
54 ples before being placed in to buf. The value of len is specified in
55 total samples. If its value is not evenly divisable by the number of
56 channels, undefined behavior will occur.
57 The function st_write writes len samples from buf using the format han‐
59 dler specified by ft. Data in buf must be 32-bit signed samples and
60 will be converted during the write process. The value of len is speci‐
61 fied in total samples. If its value is not evenly divisable by the num‐
62 ber of channels, undefined behavior will occur.
63 The st_close function dissociates the named ft_t from its underlying
65 file or set of functions. If the format handler was being used for out‐
66 put, any buffered data is written first.
67 SoX includes skeleton C files to assist you in writing new formats
69 (skelform.c) and effects (skeleff.c). sox.c itself is a good starting
70 point for new programs. Note that new formats can often just deal with
71 the header and then use raw.c's routines for reading and writing.
72
74 Upon successful completion st_open_input and st_open_output return a
75 ft_t (which is a pointer). Otherwise, NULL is returned. TODO: Need a
76 what to return reason for failures. Currently, relies on st_warn to
77 print information.
78 st_read and st_write return the number of samples successfully read or
80 written. If an error occurs, or the end-of-file is reached, the return
81 value is a short item count or ST_EOF. TODO: st_read does not distigu‐
82 ish between end-of-ifle and error. Need an feof() and ferror() concept
83 to determine which occured.
84 Upon successful completion st_close returns 0. Otherwise, ST_EOF is
86 returned. In either case, any further access (including another call to
87 st_close()) to the handler results in undefined behavior. TODO: Need a
88 way to return reason for failures. Currently, relies on st_warn to
89 print information.
90 Upon successful completion st_seek returns 0. Otherwise, ST_EOF is
92 returned. TODO Need to set a global error and implement st_tell.
93
95 TODO
96
98 SoX's formats and effects operate on an internal buffer format of
99 signed 32-bit longs. The data processing routines are called with buf‐
100 fers of these samples, and buffer sizes which refer to the number of
101 samples processed, not the number of bytes. File readers translate the
102 input samples to signed 32-bit integers and return the number of sam‐
103 ples read. For example, data in linear signed byte format is left-
104 shifted 24 bits.
105 This does cause problems in processing the data. For example:
107 *obuf++ = (*ibuf++ + *ibuf++)/2;
108 would not mix down left and right channels into one monophonic channel,
109 because the resulting samples would overflow 32 bits. Instead, the
110 ``avg'' effects must use:
111 *obuf++ = *ibuf++/2 + *ibuf++/2;
112 Stereo data is stored with the left and right speaker data in succes‐
114 sive samples. Quadraphonic data is stored in this order: left front,
115 right front, left rear, right rear.
116
118 A format is responsible for translating between sound sample files and
119 an internal buffer. The internal buffer is store in signed longs with
120 a fixed sampling rate. The format operates from two data structures: a
121 format structure, and a private structure.
122 The format structure contains a list of control parameters for the sam‐
124 ple: sampling rate, data size (8, 16, or 32 bits), encoding (unsigned,
125 signed, floating point, etc.), number of sound channels. It also con‐
126 tains other state information: whether the sample file needs to be
127 byte-swapped, whether st_seek() will work, its suffix, its file stream
128 pointer, its format pointer, and the private structure for the format .
129 The private area is just a preallocated data array for the format to
131 use however it wishes. It should have a defined data structure and
132 cast the array to that structure. See voc.c for the use of a private
133 data area. Voc.c has to track the number of samples it writes and when
134 finishing, seek back to the beginning of the file and write it out.
135 The private area is not very large. The ``echo'' effect has to mal‐
136 loc() a much larger area for its delay line buffers.
137 A format has 6 routines:
139 startread Set up the format parameters, or read in a data
141 header, or do what needs to be done.
142 read Given a buffer and a length: read up to that many
144 samples, transform them into signed long integers,
145 and copy them into the buffer. Return the number
146 of samples actually read.
147 stopread Do what needs to be done.
149 startwrite Set up the format parameters, or write out a data
151 header, or do what needs to be done.
152 write Given a buffer and a length: copy that many samples
154 out of the buffer, convert them from signed longs
155 to the appropriate data, and write them to the
156 file. If it can't write out all the samples, fail.
157 stopwrite Fix up any file header, or do what needs to be
159 done.
160
162 An effects loop has one input and one output stream. It has 5 rou‐
163 tines.
164 getopts is called with a character string argument list for
166 the effect.
167 start is called with the signal parameters for the input
169 and output streams.
170 flow is called with input and output data buffers, and
172 (by reference) the input and output data buffer
173 sizes. It processes the input buffer into the out‐
174 put buffer, and sets the size variables to the num‐
175 bers of samples actually processed. It is under no
176 obligation to read from the input buffer or write
177 to the output buffer during the same call. If the
178 call returns ST_EOF then this should be used as an
179 indication that this effect will no longer read any
180 data and can be used to switch to drain mode
181 sooner.
182 drain is called after there are no more input data sam‐
184 ples. If the effect wishes to generate more data
185 samples it copies the generated data into a given
186 buffer and returns the number of samples generated.
187 If it fills the buffer, it will be called again,
188 etc. The echo effect uses this to fade away.
189 stop is called when there are no more input samples to
191 process. stop may generate output samples on its
192 own. See echo.c for how to do this, and see that
193 what it does is absolutely bogus.
194
196 This manual page is both incomplete and out of date.
197
199 sox(1), soxexam(7)
200
202 Copyright 1991 Lance Norskog and Sundry Contributors. Copyright
203 1998-2007 by Chris Bagwell and SoX Contributors.
204 This library is free software; you can redistribute it and/or modify it
206 under the terms of the GNU Lesser General Public License as published
207 by the Free Software Foundation; either version 2.1, or (at your
208 option) any later version.
209 This library is distributed in the hope that it will be useful, but
211 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
212 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
213 General Public License for more details.
214
216 Chris Bagwell (cbagwell@users.sourceforge.net). Other authors and con‐
217 tributors are listed in the AUTHORS file that is distributed with the
218 source code.
219 January 31, 2007 ST(3)