minor comments
[flac.git] / 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 as <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 as
98  * <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 are independent of each other.
138  * - The metadata interface requires the file decoder.
139  * - The decoder and encoder layers depend on the layers below them, but
140  *   not above them; e.g. the seekable stream decoder depends on the stream
141  *   decoder but not the file decoder
142  *
143  * For example, if your application only requires the stream decoder, no
144  * encoders, and no metadata interface, you can remove the seekable stream
145  * decoder, file decoder, all encoders, and the metadata interface, which
146  * will greatly reduce the size of the 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
156 /** \defgroup porting_1_1_2_to_1_1_3 Porting from FLAC 1.1.2 to 1.1.3
157  *  \ingroup porting
158  *
159  *  \brief
160  *  This module describes porting from FLAC 1.1.2 to FLAC 1.1.3.
161  *
162  * The main change between the APIs in 1.1.2 and 1.1.3 is that the three
163  * decoding layers and three encoding layers have been merged into a
164  * single stream decoder and stream encoder.  That is, the functionality
165  * of FLAC__SeekableStreamDecoder and FLAC__FileDecoder has been merged
166  * into FLAC__StreamDecoder, and FLAC__SeekableStreamEncoder and
167  * FLAC__FileEncoder into FLAC__StreamEncoder.  Only the
168  * FLAC__StreamDecoder and FLAC__StreamEncoder remain.  This can
169  * simplify code that needs to process both seekable and non-seekable
170  * streams.
171  *
172  * Instead of creating an encoder or decoder of a certain layer, now the
173  * client will always create a FLAC__StreamEncoder or
174  * FLAC__StreamDecoder.  The different layers are differentiated by the
175  * initialization function.  For example, for the decoder,
176  * FLAC__stream_decoder_init() has been replaced by
177  * FLAC__stream_decoder_init_stream().  This init function takes
178  * callbacks for the I/O, and the seeking callbacks are optional.  This
179  * allows the client to use the same object for seekable and
180  * non-seekable streams.  For decoding a FLAC file directly, the client
181  * can use FLAC__stream_decoder_init_file() and pass just a filename
182  * and fewer callbacks; most of the other callbacks are supplied
183  * internally.  For situations where fopen()ing by filename is not
184  * possible (e.g. Unicode filenames on Windows) the client can instead
185  * open the file itself and supply the FILE* to
186  * FLAC__stream_decoder_init_FILE().  The init functions now returns a
187  * FLAC__StreamDecoderInitStatus instead of FLAC__StreamDecoderState.
188  * Since the callbacks and client data are now passed to the init
189  * function, the FLAC__stream_decoder_set_*_callback() functions and
190  * FLAC__stream_decoder_set_client_data() are no longer needed.  The
191  * rest of the calls to the decoder are the same as before.
192  *
193  * As an example, in FLAC 1.1.2 a seekable stream decoder would have
194  * been set up like so:
195  *
196  * \code
197  * FLAC__SeekableStreamDecoder *decoder = FLAC__seekable_stream_decoder_new();
198  * if(decoder == NULL) do_something;
199  * FLAC__seekable_stream_decoder_set_md5_checking(decoder, true);
200  * [... other settings ...]
201  * FLAC__seekable_stream_decoder_set_read_callback(decoder, my_read_callback);
202  * FLAC__seekable_stream_decoder_set_seek_callback(decoder, my_seek_callback);
203  * FLAC__seekable_stream_decoder_set_tell_callback(decoder, my_tell_callback);
204  * FLAC__seekable_stream_decoder_set_length_callback(decoder, my_length_callback);
205  * FLAC__seekable_stream_decoder_set_eof_callback(decoder, my_eof_callback);
206  * FLAC__seekable_stream_decoder_set_write_callback(decoder, my_write_callback);
207  * FLAC__seekable_stream_decoder_set_metadata_callback(decoder, my_metadata_callback);
208  * FLAC__seekable_stream_decoder_set_error_callback(decoder, my_error_callback);
209  * FLAC__seekable_stream_decoder_set_client_data(decoder, my_client_data);
210  * if(FLAC__seekable_stream_decoder_init(decoder) != FLAC__SEEKABLE_STREAM_DECODER_OK) do_something;
211  * \endcode
212  *
213  * In FLAC 1.1.3 it is like this:
214  *
215  * \code
216  * FLAC__StreamDecoder *decoder = FLAC__stream_decoder_new();
217  * if(decoder == NULL) do_something;
218  * FLAC__stream_decoder_set_md5_checking(decoder, true);
219  * [... other settings ...]
220  * if(FLAC__stream_decoder_init_stream(
221  *   decoder,
222  *   my_read_callback,
223  *   my_seek_callback,      // or NULL
224  *   my_tell_callback,      // or NULL
225  *   my_length_callback,    // or NULL
226  *   my_eof_callback,       // or NULL
227  *   my_write_callback,
228  *   my_metadata_callback,  // or NULL
229  *   my_error_callback,
230  *   my_client_data
231  * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
232  * \endcode
233  *
234  * or you could do;
235  *
236  * \code
237  * [...]
238  * FILE *file = fopen("somefile.flac","rb");
239  * if(file == NULL) do_somthing;
240  * if(FLAC__stream_decoder_init_FILE(
241  *   decoder,
242  *   file,
243  *   my_write_callback,
244  *   my_metadata_callback,  // or NULL
245  *   my_error_callback,
246  *   my_client_data
247  * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
248  * \endcode
249  *
250  * or just:
251  *
252  * \code
253  * [...]
254  * if(FLAC__stream_decoder_init_file(
255  *   decoder,
256  *   "somefile.flac",
257  *   my_write_callback,
258  *   my_metadata_callback,  // or NULL
259  *   my_error_callback,
260  *   my_client_data
261  * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
262  * \endcode
263  *
264  * Another small change to the decoder is in how it handles unparseable
265  * streams.  Before, when the decoder found an unparseable stream
266  * (reserved for when the decoder encounters a stream from a future
267  * encoder that it can't parse), it changed the state to
268  * \c FLAC__STREAM_DECODER_UNPARSEABLE_STREAM.  Now the decoder instead
269  * drops sync and calls the error callback with a new error code
270  * \c FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM.  This is
271  * more robust.  If your error callback does not discriminate on the the
272  * error state, your code does not need to be changed.
273  *
274  * The encoder now has a new setting:
275  * FLAC__stream_encoder_set_apodization().  This is for setting the
276  * method used to window the data before LPC analysis.  You only need to
277  * add a call to this function if the default is not   There are also
278  * two new convenience functions that may be useful:
279  * FLAC__metadata_object_cuesheet_calculate_cddb_id() and
280  * FLAC__metadata_get_cuesheet().
281  *
282  * In libOggFLAC++, OggFLAC::Decoder::Stream now inherits from
283  * FLAC::Decoder::Stream and OggFLAC::Encoder::Stream now inherits from
284  * FLAC::Encoder::Stream, which means both OggFLAC and FLAC can be
285  * supported by using common code for everything after initialization.
286  */
287
288 /** \defgroup flac FLAC C API
289  *
290  * The FLAC C API is the interface to libFLAC, a set of structures
291  * describing the components of FLAC streams, and functions for
292  * encoding and decoding streams, as well as manipulating FLAC
293  * metadata in files.
294  *
295  * You should start with the format components as all other modules
296  * are dependent on it.
297  */
298
299 #endif