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