include/FLAC/all.h

   1 /* libFLAC - Free Lossless Audio Codec library
   2  * Copyright (C) 2000,2001,2002,2003,2004,2005,2006 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  * There is also a libOggFLAC library which wraps around libFLAC
  84  * to provide routines for encoding to and decoding from FLAC streams
  85  * inside an Ogg container.  The interfaces are very similar or identical
  86  * to their counterparts in libFLAC.  libOggFLAC is also licensed under
  87  * <A HREF="../license.html">Xiph's BSD license</A>.
  88  *
  89  * \section cpp_api FLAC C++ API
  90  *
  91  * The FLAC C++ API is a set of classes that encapsulate the
  92  * structures and functions in libFLAC.  They provide slightly more
  93  * functionality with respect to metadata but are otherwise
  94  * equivalent.  For the most part, they share the same usage as
  95  * their counterparts in libFLAC, and the FLAC C API documentation
  96  * can be used as a supplement.  The public include files
  97  * for the C++ API will be installed in your include area (for
  98  * example /usr/include/FLAC++/...).
  99  *
 100  * There is also a libOggFLAC++ library, which provides classes
 101  * for encoding to and decoding from FLAC streams in an Ogg container.
 102  * The classes are very similar to their counterparts in libFLAC++.
 103  *
 104  * Both libFLAC++ libOggFLAC++ are also licensed under
 105  * <A HREF="../license.html">Xiph's BSD license</A>.
 106  *
 107  * \section getting_started Getting Started
 108  *
 109  * A good starting point for learning the API is to browse through
 110  * the <A HREF="modules.html">modules</A>.  Modules are logical
 111  * groupings of related functions or classes, which correspond roughly
 112  * to header files or sections of header files.  Each module includes a
 113  * detailed description of the general usage of its functions or
 114  * classes.
 115  *
 116  * From there you can go on to look at the documentation of
 117  * individual functions.  You can see different views of the individual
 118  * functions through the links in top bar across this page.
 119  *
 120  * \section porting_guide Porting Guide
 121  *
 122  * Starting with FLAC 1.1.3 a \link porting Porting Guide \endlink
 123  * has been introduced which gives detailed instructions on how to
 124  * port your code to newer versions of FLAC.
 125  *
 126  * \section embedded_developers Embedded Developers
 127  *
 128  * libFLAC has grown larger over time as more functionality has been
 129  * included, but much of it may be unnecessary for a particular embedded
 130  * implementation.  Unused parts may be pruned by some simple editing of
 131  * src/libFLAC/Makefile.am.  In general, the decoders, encoders, and
 132  * metadata interface are all independent from each other.
 133  *
 134  * It is easiest to just describe the dependencies:
 135  *
 136  * - All modules depend on the \link flac_format Format \endlink module.
 137  * - The decoders and encoders depend on the bitbuffer.
 138  * - The decoder is independent of the encoder.  The encoder uses the
 139  *   decoder because of the verify feature, but this can be removed if
 140  *   not needed.
 141  * - The metadata interface requires the stream decoder.
 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
 149 /** \defgroup porting Porting Guide for New Versions
 150  *
 151  * This module describes differences in the library interfaces from
 152  * version to version.  It assists in the porting of code that uses
 153  * the libraries to newer versions of FLAC.
 154  *
 155  * One simple facility for making porting easier that has been added
 156  * in FLAC 1.1.3 is a set of \c #defines in \c export.h of each
 157  * library's includes (e.g. \c include/FLAC/export.h).  The
 158  * \c #defines mirror the libraries'
 159  * <A HREF="http://www.gnu.org/software/libtool/manual.html#Libtool-versioning">libtool version numbers</A>,
 160  * e.g. in libFLAC there are \c FLAC_API_VERSION_CURRENT,
 161  * \c FLAC_API_VERSION_REVISION, and \c FLAC_API_VERSION_AGE.
 162  * These can be used to support multiple versions of an API during the
 163  * transition phase, e.g.
 164  *
 165  * \code
 166  * #if !defined(FLAC_API_VERSION_CURRENT) || FLAC_API_VERSION_CURRENT <= 7
 167  *   legacy code
 168  * #else
 169  *   new code
 170  * #endif
 171  * \endcode
 172  *
 173  * The the source will work for multiple versions and the legacy code can
 174  * easily be removed when the transition is complete.
 175  */
 176
 177 /** \defgroup porting_1_1_2_to_1_1_3 Porting from FLAC 1.1.2 to 1.1.3
 178  *  \ingroup porting
 179  *
 180  *  \brief
 181  *  This module describes porting from FLAC 1.1.2 to FLAC 1.1.3.
 182  *
 183  * The main change between the APIs in 1.1.2 and 1.1.3 is that the three
 184  * decoding layers and three encoding layers have been merged into a
 185  * single stream decoder and stream encoder.  That is, the functionality
 186  * of FLAC__SeekableStreamDecoder and FLAC__FileDecoder has been merged
 187  * into FLAC__StreamDecoder, and FLAC__SeekableStreamEncoder and
 188  * FLAC__FileEncoder into FLAC__StreamEncoder.  Only the
 189  * FLAC__StreamDecoder and FLAC__StreamEncoder remain.  This can
 190  * simplify code that needs to process both seekable and non-seekable
 191  * streams.
 192  *
 193  * Instead of creating an encoder or decoder of a certain layer, now the
 194  * client will always create a FLAC__StreamEncoder or
 195  * FLAC__StreamDecoder.  The different layers are differentiated by the
 196  * initialization function.  For example, for the decoder,
 197  * FLAC__stream_decoder_init() has been replaced by
 198  * FLAC__stream_decoder_init_stream().  This init function takes
 199  * callbacks for the I/O, and the seeking callbacks are optional.  This
 200  * allows the client to use the same object for seekable and
 201  * non-seekable streams.  For decoding a FLAC file directly, the client
 202  * can use FLAC__stream_decoder_init_file() and pass just a filename
 203  * and fewer callbacks; most of the other callbacks are supplied
 204  * internally.  For situations where fopen()ing by filename is not
 205  * possible (e.g. Unicode filenames on Windows) the client can instead
 206  * open the file itself and supply the FILE* to
 207  * FLAC__stream_decoder_init_FILE().  The init functions now returns a
 208  * FLAC__StreamDecoderInitStatus instead of FLAC__StreamDecoderState.
 209  * Since the callbacks and client data are now passed to the init
 210  * function, the FLAC__stream_decoder_set_*_callback() functions and
 211  * FLAC__stream_decoder_set_client_data() are no longer needed.  The
 212  * rest of the calls to the decoder are the same as before.
 213  *
 214  * As an example, in FLAC 1.1.2 a seekable stream decoder would have
 215  * been set up like so:
 216  *
 217  * \code
 218  * FLAC__SeekableStreamDecoder *decoder = FLAC__seekable_stream_decoder_new();
 219  * if(decoder == NULL) do_something;
 220  * FLAC__seekable_stream_decoder_set_md5_checking(decoder, true);
 221  * [... other settings ...]
 222  * FLAC__seekable_stream_decoder_set_read_callback(decoder, my_read_callback);
 223  * FLAC__seekable_stream_decoder_set_seek_callback(decoder, my_seek_callback);
 224  * FLAC__seekable_stream_decoder_set_tell_callback(decoder, my_tell_callback);
 225  * FLAC__seekable_stream_decoder_set_length_callback(decoder, my_length_callback);
 226  * FLAC__seekable_stream_decoder_set_eof_callback(decoder, my_eof_callback);
 227  * FLAC__seekable_stream_decoder_set_write_callback(decoder, my_write_callback);
 228  * FLAC__seekable_stream_decoder_set_metadata_callback(decoder, my_metadata_callback);
 229  * FLAC__seekable_stream_decoder_set_error_callback(decoder, my_error_callback);
 230  * FLAC__seekable_stream_decoder_set_client_data(decoder, my_client_data);
 231  * if(FLAC__seekable_stream_decoder_init(decoder) != FLAC__SEEKABLE_STREAM_DECODER_OK) do_something;
 232  * \endcode
 233  *
 234  * In FLAC 1.1.3 it is like this:
 235  *
 236  * \code
 237  * FLAC__StreamDecoder *decoder = FLAC__stream_decoder_new();
 238  * if(decoder == NULL) do_something;
 239  * FLAC__stream_decoder_set_md5_checking(decoder, true);
 240  * [... other settings ...]
 241  * if(FLAC__stream_decoder_init_stream(
 242  *   decoder,
 243  *   my_read_callback,
 244  *   my_seek_callback,      // or NULL
 245  *   my_tell_callback,      // or NULL
 246  *   my_length_callback,    // or NULL
 247  *   my_eof_callback,       // or NULL
 248  *   my_write_callback,
 249  *   my_metadata_callback,  // or NULL
 250  *   my_error_callback,
 251  *   my_client_data
 252  * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
 253  * \endcode
 254  *
 255  * or you could do;
 256  *
 257  * \code
 258  * [...]
 259  * FILE *file = fopen("somefile.flac","rb");
 260  * if(file == NULL) do_somthing;
 261  * if(FLAC__stream_decoder_init_FILE(
 262  *   decoder,
 263  *   file,
 264  *   my_write_callback,
 265  *   my_metadata_callback,  // or NULL
 266  *   my_error_callback,
 267  *   my_client_data
 268  * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
 269  * \endcode
 270  *
 271  * or just:
 272  *
 273  * \code
 274  * [...]
 275  * if(FLAC__stream_decoder_init_file(
 276  *   decoder,
 277  *   "somefile.flac",
 278  *   my_write_callback,
 279  *   my_metadata_callback,  // or NULL
 280  *   my_error_callback,
 281  *   my_client_data
 282  * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
 283  * \endcode
 284  *
 285  * Another small change to the decoder is in how it handles unparseable
 286  * streams.  Before, when the decoder found an unparseable stream
 287  * (reserved for when the decoder encounters a stream from a future
 288  * encoder that it can't parse), it changed the state to
 289  * \c FLAC__STREAM_DECODER_UNPARSEABLE_STREAM.  Now the decoder instead
 290  * drops sync and calls the error callback with a new error code
 291  * \c FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM.  This is
 292  * more robust.  If your error callback does not discriminate on the the
 293  * error state, your code does not need to be changed.
 294  *
 295  * The encoder now has a new setting:
 296  * FLAC__stream_encoder_set_apodization().  This is for setting the
 297  * method used to window the data before LPC analysis.  You only need to
 298  * add a call to this function if the default is not   There are also
 299  * two new convenience functions that may be useful:
 300  * FLAC__metadata_object_cuesheet_calculate_cddb_id() and
 301  * FLAC__metadata_get_cuesheet().
 302  *
 303  * In libOggFLAC++, OggFLAC::Decoder::Stream now inherits from
 304  * FLAC::Decoder::Stream and OggFLAC::Encoder::Stream now inherits from
 305  * FLAC::Encoder::Stream, which means both OggFLAC and FLAC can be
 306  * supported by using common code for everything after initialization.
 307  */
 308
 309 /** \defgroup flac FLAC C API
 310  *
 311  * The FLAC C API is the interface to libFLAC, a set of structures
 312  * describing the components of FLAC streams, and functions for
 313  * encoding and decoding streams, as well as manipulating FLAC
 314  * metadata in files.
 315  *
 316  * You should start with the format components as all other modules
 317  * are dependent on it.
 318  */
 319
 320 #endif