ce188d4d |
1 | /* libFLAC - Free Lossless Audio Codec library |
2 | * Copyright (C) 2000-2009 Josh Coalson |
3 | * Copyright (C) 2011-2016 Xiph.Org Foundation |
4 | * |
5 | * Redistribution and use in source and binary forms, with or without |
6 | * modification, are permitted provided that the following conditions |
7 | * are met: |
8 | * |
9 | * - Redistributions of source code must retain the above copyright |
10 | * notice, this list of conditions and the following disclaimer. |
11 | * |
12 | * - Redistributions in binary form must reproduce the above copyright |
13 | * notice, this list of conditions and the following disclaimer in the |
14 | * documentation and/or other materials provided with the distribution. |
15 | * |
16 | * - Neither the name of the Xiph.org Foundation nor the names of its |
17 | * contributors may be used to endorse or promote products derived from |
18 | * this software without specific prior written permission. |
19 | * |
20 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
21 | * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
22 | * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
23 | * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR |
24 | * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, |
25 | * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, |
26 | * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR |
27 | * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF |
28 | * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING |
29 | * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS |
30 | * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
31 | */ |
32 | |
33 | #ifndef FLAC__ALL_H |
34 | #define FLAC__ALL_H |
35 | |
36 | #include "export.h" |
37 | |
38 | #include "assert.h" |
39 | #include "callback.h" |
40 | #include "format.h" |
41 | #include "metadata.h" |
42 | #include "ordinals.h" |
43 | #include "stream_decoder.h" |
44 | #include "stream_encoder.h" |
45 | |
46 | /** \mainpage |
47 | * |
48 | * \section intro Introduction |
49 | * |
50 | * This is the documentation for the FLAC C and C++ APIs. It is |
51 | * highly interconnected; this introduction should give you a top |
52 | * level idea of the structure and how to find the information you |
53 | * need. As a prerequisite you should have at least a basic |
54 | * knowledge of the FLAC format, documented |
55 | * <A HREF="../format.html">here</A>. |
56 | * |
57 | * \section c_api FLAC C API |
58 | * |
59 | * The FLAC C API is the interface to libFLAC, a set of structures |
60 | * describing the components of FLAC streams, and functions for |
61 | * encoding and decoding streams, as well as manipulating FLAC |
62 | * metadata in files. The public include files will be installed |
63 | * in your include area (for example /usr/include/FLAC/...). |
64 | * |
65 | * By writing a little code and linking against libFLAC, it is |
66 | * relatively easy to add FLAC support to another program. The |
67 | * library is licensed under <A HREF="../license.html">Xiph's BSD license</A>. |
68 | * Complete source code of libFLAC as well as the command-line |
69 | * encoder and plugins is available and is a useful source of |
70 | * examples. |
71 | * |
72 | * Aside from encoders and decoders, libFLAC provides a powerful |
73 | * metadata interface for manipulating metadata in FLAC files. It |
74 | * allows the user to add, delete, and modify FLAC metadata blocks |
75 | * and it can automatically take advantage of PADDING blocks to avoid |
76 | * rewriting the entire FLAC file when changing the size of the |
77 | * metadata. |
78 | * |
79 | * libFLAC usually only requires the standard C library and C math |
80 | * library. In particular, threading is not used so there is no |
81 | * dependency on a thread library. However, libFLAC does not use |
82 | * global variables and should be thread-safe. |
83 | * |
84 | * libFLAC also supports encoding to and decoding from Ogg FLAC. |
85 | * However the metadata editing interfaces currently have limited |
86 | * read-only support for Ogg FLAC files. |
87 | * |
88 | * \section cpp_api FLAC C++ API |
89 | * |
90 | * The FLAC C++ API is a set of classes that encapsulate the |
91 | * structures and functions in libFLAC. They provide slightly more |
92 | * functionality with respect to metadata but are otherwise |
93 | * equivalent. For the most part, they share the same usage as |
94 | * their counterparts in libFLAC, and the FLAC C API documentation |
95 | * can be used as a supplement. The public include files |
96 | * for the C++ API will be installed in your include area (for |
97 | * example /usr/include/FLAC++/...). |
98 | * |
99 | * libFLAC++ is also licensed under |
100 | * <A HREF="../license.html">Xiph's BSD license</A>. |
101 | * |
102 | * \section getting_started Getting Started |
103 | * |
104 | * A good starting point for learning the API is to browse through |
105 | * the <A HREF="modules.html">modules</A>. Modules are logical |
106 | * groupings of related functions or classes, which correspond roughly |
107 | * to header files or sections of header files. Each module includes a |
108 | * detailed description of the general usage of its functions or |
109 | * classes. |
110 | * |
111 | * From there you can go on to look at the documentation of |
112 | * individual functions. You can see different views of the individual |
113 | * functions through the links in top bar across this page. |
114 | * |
115 | * If you prefer a more hands-on approach, you can jump right to some |
116 | * <A HREF="../documentation_example_code.html">example code</A>. |
117 | * |
118 | * \section porting_guide Porting Guide |
119 | * |
120 | * Starting with FLAC 1.1.3 a \link porting Porting Guide \endlink |
121 | * has been introduced which gives detailed instructions on how to |
122 | * port your code to newer versions of FLAC. |
123 | * |
124 | * \section embedded_developers Embedded Developers |
125 | * |
126 | * libFLAC has grown larger over time as more functionality has been |
127 | * included, but much of it may be unnecessary for a particular embedded |
128 | * implementation. Unused parts may be pruned by some simple editing of |
129 | * src/libFLAC/Makefile.am. In general, the decoders, encoders, and |
130 | * metadata interface are all independent from each other. |
131 | * |
132 | * It is easiest to just describe the dependencies: |
133 | * |
134 | * - All modules depend on the \link flac_format Format \endlink module. |
135 | * - The decoders and encoders depend on the bitbuffer. |
136 | * - The decoder is independent of the encoder. The encoder uses the |
137 | * decoder because of the verify feature, but this can be removed if |
138 | * not needed. |
139 | * - Parts of the metadata interface require the stream decoder (but not |
140 | * the encoder). |
141 | * - Ogg support is selectable through the compile time macro |
142 | * \c FLAC__HAS_OGG. |
143 | * |
144 | * For example, if your application only requires the stream decoder, no |
145 | * encoder, and no metadata interface, you can remove the stream encoder |
146 | * and the metadata interface, which will greatly reduce the size of the |
147 | * library. |
148 | * |
149 | * Also, there are several places in the libFLAC code with comments marked |
150 | * with "OPT:" where a #define can be changed to enable code that might be |
151 | * faster on a specific platform. Experimenting with these can yield faster |
152 | * binaries. |
153 | */ |
154 | |
155 | /** \defgroup porting Porting Guide for New Versions |
156 | * |
157 | * This module describes differences in the library interfaces from |
158 | * version to version. It assists in the porting of code that uses |
159 | * the libraries to newer versions of FLAC. |
160 | * |
161 | * One simple facility for making porting easier that has been added |
162 | * in FLAC 1.1.3 is a set of \c #defines in \c export.h of each |
163 | * library's includes (e.g. \c include/FLAC/export.h). The |
164 | * \c #defines mirror the libraries' |
165 | * <A HREF="http://www.gnu.org/software/libtool/manual/libtool.html#Libtool-versioning">libtool version numbers</A>, |
166 | * e.g. in libFLAC there are \c FLAC_API_VERSION_CURRENT, |
167 | * \c FLAC_API_VERSION_REVISION, and \c FLAC_API_VERSION_AGE. |
168 | * These can be used to support multiple versions of an API during the |
169 | * transition phase, e.g. |
170 | * |
171 | * \code |
172 | * #if !defined(FLAC_API_VERSION_CURRENT) || FLAC_API_VERSION_CURRENT <= 7 |
173 | * legacy code |
174 | * #else |
175 | * new code |
176 | * #endif |
177 | * \endcode |
178 | * |
179 | * The source will work for multiple versions and the legacy code can |
180 | * easily be removed when the transition is complete. |
181 | * |
182 | * Another available symbol is FLAC_API_SUPPORTS_OGG_FLAC (defined in |
183 | * include/FLAC/export.h), which can be used to determine whether or not |
184 | * the library has been compiled with support for Ogg FLAC. This is |
185 | * simpler than trying to call an Ogg init function and catching the |
186 | * error. |
187 | */ |
188 | |
189 | /** \defgroup porting_1_1_2_to_1_1_3 Porting from FLAC 1.1.2 to 1.1.3 |
190 | * \ingroup porting |
191 | * |
192 | * \brief |
193 | * This module describes porting from FLAC 1.1.2 to FLAC 1.1.3. |
194 | * |
195 | * The main change between the APIs in 1.1.2 and 1.1.3 is that they have |
196 | * been simplified. First, libOggFLAC has been merged into libFLAC and |
197 | * libOggFLAC++ has been merged into libFLAC++. Second, both the three |
198 | * decoding layers and three encoding layers have been merged into a |
199 | * single stream decoder and stream encoder. That is, the functionality |
200 | * of FLAC__SeekableStreamDecoder and FLAC__FileDecoder has been merged |
201 | * into FLAC__StreamDecoder, and FLAC__SeekableStreamEncoder and |
202 | * FLAC__FileEncoder into FLAC__StreamEncoder. Only the |
203 | * FLAC__StreamDecoder and FLAC__StreamEncoder remain. What this means |
204 | * is there is now a single API that can be used to encode or decode |
205 | * streams to/from native FLAC or Ogg FLAC and the single API can work |
206 | * on both seekable and non-seekable streams. |
207 | * |
208 | * Instead of creating an encoder or decoder of a certain layer, now the |
209 | * client will always create a FLAC__StreamEncoder or |
210 | * FLAC__StreamDecoder. The old layers are now differentiated by the |
211 | * initialization function. For example, for the decoder, |
212 | * FLAC__stream_decoder_init() has been replaced by |
213 | * FLAC__stream_decoder_init_stream(). This init function takes |
214 | * callbacks for the I/O, and the seeking callbacks are optional. This |
215 | * allows the client to use the same object for seekable and |
216 | * non-seekable streams. For decoding a FLAC file directly, the client |
217 | * can use FLAC__stream_decoder_init_file() and pass just a filename |
218 | * and fewer callbacks; most of the other callbacks are supplied |
219 | * internally. For situations where fopen()ing by filename is not |
220 | * possible (e.g. Unicode filenames on Windows) the client can instead |
221 | * open the file itself and supply the FILE* to |
222 | * FLAC__stream_decoder_init_FILE(). The init functions now returns a |
223 | * FLAC__StreamDecoderInitStatus instead of FLAC__StreamDecoderState. |
224 | * Since the callbacks and client data are now passed to the init |
225 | * function, the FLAC__stream_decoder_set_*_callback() functions and |
226 | * FLAC__stream_decoder_set_client_data() are no longer needed. The |
227 | * rest of the calls to the decoder are the same as before. |
228 | * |
229 | * There are counterpart init functions for Ogg FLAC, e.g. |
230 | * FLAC__stream_decoder_init_ogg_stream(). All the rest of the calls |
231 | * and callbacks are the same as for native FLAC. |
232 | * |
233 | * As an example, in FLAC 1.1.2 a seekable stream decoder would have |
234 | * been set up like so: |
235 | * |
236 | * \code |
237 | * FLAC__SeekableStreamDecoder *decoder = FLAC__seekable_stream_decoder_new(); |
238 | * if(decoder == NULL) do_something; |
239 | * FLAC__seekable_stream_decoder_set_md5_checking(decoder, true); |
240 | * [... other settings ...] |
241 | * FLAC__seekable_stream_decoder_set_read_callback(decoder, my_read_callback); |
242 | * FLAC__seekable_stream_decoder_set_seek_callback(decoder, my_seek_callback); |
243 | * FLAC__seekable_stream_decoder_set_tell_callback(decoder, my_tell_callback); |
244 | * FLAC__seekable_stream_decoder_set_length_callback(decoder, my_length_callback); |
245 | * FLAC__seekable_stream_decoder_set_eof_callback(decoder, my_eof_callback); |
246 | * FLAC__seekable_stream_decoder_set_write_callback(decoder, my_write_callback); |
247 | * FLAC__seekable_stream_decoder_set_metadata_callback(decoder, my_metadata_callback); |
248 | * FLAC__seekable_stream_decoder_set_error_callback(decoder, my_error_callback); |
249 | * FLAC__seekable_stream_decoder_set_client_data(decoder, my_client_data); |
250 | * if(FLAC__seekable_stream_decoder_init(decoder) != FLAC__SEEKABLE_STREAM_DECODER_OK) do_something; |
251 | * \endcode |
252 | * |
253 | * In FLAC 1.1.3 it is like this: |
254 | * |
255 | * \code |
256 | * FLAC__StreamDecoder *decoder = FLAC__stream_decoder_new(); |
257 | * if(decoder == NULL) do_something; |
258 | * FLAC__stream_decoder_set_md5_checking(decoder, true); |
259 | * [... other settings ...] |
260 | * if(FLAC__stream_decoder_init_stream( |
261 | * decoder, |
262 | * my_read_callback, |
263 | * my_seek_callback, // or NULL |
264 | * my_tell_callback, // or NULL |
265 | * my_length_callback, // or NULL |
266 | * my_eof_callback, // or NULL |
267 | * my_write_callback, |
268 | * my_metadata_callback, // or NULL |
269 | * my_error_callback, |
270 | * my_client_data |
271 | * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something; |
272 | * \endcode |
273 | * |
274 | * or you could do; |
275 | * |
276 | * \code |
277 | * [...] |
278 | * FILE *file = fopen("somefile.flac","rb"); |
279 | * if(file == NULL) do_somthing; |
280 | * if(FLAC__stream_decoder_init_FILE( |
281 | * decoder, |
282 | * file, |
283 | * my_write_callback, |
284 | * my_metadata_callback, // or NULL |
285 | * my_error_callback, |
286 | * my_client_data |
287 | * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something; |
288 | * \endcode |
289 | * |
290 | * or just: |
291 | * |
292 | * \code |
293 | * [...] |
294 | * if(FLAC__stream_decoder_init_file( |
295 | * decoder, |
296 | * "somefile.flac", |
297 | * my_write_callback, |
298 | * my_metadata_callback, // or NULL |
299 | * my_error_callback, |
300 | * my_client_data |
301 | * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something; |
302 | * \endcode |
303 | * |
304 | * Another small change to the decoder is in how it handles unparseable |
305 | * streams. Before, when the decoder found an unparseable stream |
306 | * (reserved for when the decoder encounters a stream from a future |
307 | * encoder that it can't parse), it changed the state to |
308 | * \c FLAC__STREAM_DECODER_UNPARSEABLE_STREAM. Now the decoder instead |
309 | * drops sync and calls the error callback with a new error code |
310 | * \c FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM. This is |
311 | * more robust. If your error callback does not discriminate on the the |
312 | * error state, your code does not need to be changed. |
313 | * |
314 | * The encoder now has a new setting: |
315 | * FLAC__stream_encoder_set_apodization(). This is for setting the |
316 | * method used to window the data before LPC analysis. You only need to |
317 | * add a call to this function if the default is not suitable. There |
318 | * are also two new convenience functions that may be useful: |
319 | * FLAC__metadata_object_cuesheet_calculate_cddb_id() and |
320 | * FLAC__metadata_get_cuesheet(). |
321 | * |
322 | * The \a bytes parameter to FLAC__StreamDecoderReadCallback, |
323 | * FLAC__StreamEncoderReadCallback, and FLAC__StreamEncoderWriteCallback |
324 | * is now \c size_t instead of \c unsigned. |
325 | */ |
326 | |
327 | /** \defgroup porting_1_1_3_to_1_1_4 Porting from FLAC 1.1.3 to 1.1.4 |
328 | * \ingroup porting |
329 | * |
330 | * \brief |
331 | * This module describes porting from FLAC 1.1.3 to FLAC 1.1.4. |
332 | * |
333 | * There were no changes to any of the interfaces from 1.1.3 to 1.1.4. |
334 | * There was a slight change in the implementation of |
335 | * FLAC__stream_encoder_set_metadata(); the function now makes a copy |
336 | * of the \a metadata array of pointers so the client no longer needs |
337 | * to maintain it after the call. The objects themselves that are |
338 | * pointed to by the array are still not copied though and must be |
339 | * maintained until the call to FLAC__stream_encoder_finish(). |
340 | */ |
341 | |
342 | /** \defgroup porting_1_1_4_to_1_2_0 Porting from FLAC 1.1.4 to 1.2.0 |
343 | * \ingroup porting |
344 | * |
345 | * \brief |
346 | * This module describes porting from FLAC 1.1.4 to FLAC 1.2.0. |
347 | * |
348 | * There were only very minor changes to the interfaces from 1.1.4 to 1.2.0. |
349 | * In libFLAC, \c FLAC__format_sample_rate_is_subset() was added. |
350 | * In libFLAC++, \c FLAC::Decoder::Stream::get_decode_position() was added. |
351 | * |
352 | * Finally, value of the constant \c FLAC__FRAME_HEADER_RESERVED_LEN |
353 | * has changed to reflect the conversion of one of the reserved bits |
354 | * into active use. It used to be \c 2 and now is \c 1. However the |
355 | * FLAC frame header length has not changed, so to skip the proper |
356 | * number of bits, use \c FLAC__FRAME_HEADER_RESERVED_LEN + |
357 | * \c FLAC__FRAME_HEADER_BLOCKING_STRATEGY_LEN |
358 | */ |
359 | |
360 | /** \defgroup flac FLAC C API |
361 | * |
362 | * The FLAC C API is the interface to libFLAC, a set of structures |
363 | * describing the components of FLAC streams, and functions for |
364 | * encoding and decoding streams, as well as manipulating FLAC |
365 | * metadata in files. |
366 | * |
367 | * You should start with the format components as all other modules |
368 | * are dependent on it. |
369 | */ |
370 | |
371 | #endif |