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 372
