| 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 |