1 /* libFLAC - Free Lossless Audio Codec library
2 * Copyright (C) 2000,2001,2002,2003,2004,2005,2006 Josh Coalson
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
8 * - Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
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.
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.
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.
42 #include "stream_decoder.h"
43 #include "stream_encoder.h"
47 * \section intro Introduction
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>.
56 * \section c_api FLAC C API
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/...).
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
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
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.
83 * libFLAC also supports encoding to and decoding from Ogg FLAC.
84 * However the metadata editing interfaces currently work only for
87 * \section cpp_api FLAC C++ API
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++/...).
98 * libFLAC++ also supports encoding to and decoding from Ogg FLAC.
99 * However the metadata editing interfaces currently work only for
102 * libFLAC++ is also licensed under
103 * <A HREF="../license.html">Xiph's BSD license</A>.
105 * \section getting_started Getting Started
107 * A good starting point for learning the API is to browse through
108 * the <A HREF="modules.html">modules</A>. Modules are logical
109 * groupings of related functions or classes, which correspond roughly
110 * to header files or sections of header files. Each module includes a
111 * detailed description of the general usage of its functions or
114 * From there you can go on to look at the documentation of
115 * individual functions. You can see different views of the individual
116 * functions through the links in top bar across this page.
118 * \section porting_guide Porting Guide
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.
124 * \section embedded_developers Embedded Developers
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.
132 * It is easiest to just describe the dependencies:
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
139 * - The metadata interface requires the stream decoder.
140 * - Ogg support is selectable through the compile time macro
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
149 /** \defgroup porting Porting Guide for New Versions
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.
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.
166 * #if !defined(FLAC_API_VERSION_CURRENT) || FLAC_API_VERSION_CURRENT <= 7
173 * The the source will work for multiple versions and the legacy code can
174 * easily be removed when the transition is complete.
176 * Another available symbol is FLAC_API_SUPPORTS_OGG_FLAC (defined in
177 * include/FLAC/export.h), which can be used to determine whether or not
178 * the library has been compiled with support for Ogg FLAC. This is
179 * simpler than trying to call an Ogg init function and catching the
183 /** \defgroup porting_1_1_2_to_1_1_3 Porting from FLAC 1.1.2 to 1.1.3
187 * This module describes porting from FLAC 1.1.2 to FLAC 1.1.3.
189 * The main change between the APIs in 1.1.2 and 1.1.3 is that they have
190 * been simplified. First, libOggFLAC has been merged into libFLAC and
191 * libOggFLAC++ has been merged into libFLAC++. Second, both the three
192 * decoding layers and three encoding layers have been merged into a
193 * single stream decoder and stream encoder. That is, the functionality
194 * of FLAC__SeekableStreamDecoder and FLAC__FileDecoder has been merged
195 * into FLAC__StreamDecoder, and FLAC__SeekableStreamEncoder and
196 * FLAC__FileEncoder into FLAC__StreamEncoder. Only the
197 * FLAC__StreamDecoder and FLAC__StreamEncoder remain. What this means
198 * is there is now a single API that can be used to encode or decode
199 * streams to/from native FLAC or Ogg FLAC and the single API can work
200 * on both seekable and non-seekable streams.
202 * Instead of creating an encoder or decoder of a certain layer, now the
203 * client will always create a FLAC__StreamEncoder or
204 * FLAC__StreamDecoder. The different layers are differentiated by the
205 * initialization function. For example, for the decoder,
206 * FLAC__stream_decoder_init() has been replaced by
207 * FLAC__stream_decoder_init_stream(). This init function takes
208 * callbacks for the I/O, and the seeking callbacks are optional. This
209 * allows the client to use the same object for seekable and
210 * non-seekable streams. For decoding a FLAC file directly, the client
211 * can use FLAC__stream_decoder_init_file() and pass just a filename
212 * and fewer callbacks; most of the other callbacks are supplied
213 * internally. For situations where fopen()ing by filename is not
214 * possible (e.g. Unicode filenames on Windows) the client can instead
215 * open the file itself and supply the FILE* to
216 * FLAC__stream_decoder_init_FILE(). The init functions now returns a
217 * FLAC__StreamDecoderInitStatus instead of FLAC__StreamDecoderState.
218 * Since the callbacks and client data are now passed to the init
219 * function, the FLAC__stream_decoder_set_*_callback() functions and
220 * FLAC__stream_decoder_set_client_data() are no longer needed. The
221 * rest of the calls to the decoder are the same as before.
223 * There are counterpart init functions for Ogg FLAC, e.g.
224 * FLAC__stream_decoder_init_ogg_stream(). All the rest of the calls
225 * and callbacks are the same as for native FLAC.
227 * As an example, in FLAC 1.1.2 a seekable stream decoder would have
228 * been set up like so:
231 * FLAC__SeekableStreamDecoder *decoder = FLAC__seekable_stream_decoder_new();
232 * if(decoder == NULL) do_something;
233 * FLAC__seekable_stream_decoder_set_md5_checking(decoder, true);
234 * [... other settings ...]
235 * FLAC__seekable_stream_decoder_set_read_callback(decoder, my_read_callback);
236 * FLAC__seekable_stream_decoder_set_seek_callback(decoder, my_seek_callback);
237 * FLAC__seekable_stream_decoder_set_tell_callback(decoder, my_tell_callback);
238 * FLAC__seekable_stream_decoder_set_length_callback(decoder, my_length_callback);
239 * FLAC__seekable_stream_decoder_set_eof_callback(decoder, my_eof_callback);
240 * FLAC__seekable_stream_decoder_set_write_callback(decoder, my_write_callback);
241 * FLAC__seekable_stream_decoder_set_metadata_callback(decoder, my_metadata_callback);
242 * FLAC__seekable_stream_decoder_set_error_callback(decoder, my_error_callback);
243 * FLAC__seekable_stream_decoder_set_client_data(decoder, my_client_data);
244 * if(FLAC__seekable_stream_decoder_init(decoder) != FLAC__SEEKABLE_STREAM_DECODER_OK) do_something;
247 * In FLAC 1.1.3 it is like this:
250 * FLAC__StreamDecoder *decoder = FLAC__stream_decoder_new();
251 * if(decoder == NULL) do_something;
252 * FLAC__stream_decoder_set_md5_checking(decoder, true);
253 * [... other settings ...]
254 * if(FLAC__stream_decoder_init_stream(
257 * my_seek_callback, // or NULL
258 * my_tell_callback, // or NULL
259 * my_length_callback, // or NULL
260 * my_eof_callback, // or NULL
262 * my_metadata_callback, // or NULL
265 * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
272 * FILE *file = fopen("somefile.flac","rb");
273 * if(file == NULL) do_somthing;
274 * if(FLAC__stream_decoder_init_FILE(
278 * my_metadata_callback, // or NULL
281 * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
288 * if(FLAC__stream_decoder_init_file(
292 * my_metadata_callback, // or NULL
295 * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
298 * Another small change to the decoder is in how it handles unparseable
299 * streams. Before, when the decoder found an unparseable stream
300 * (reserved for when the decoder encounters a stream from a future
301 * encoder that it can't parse), it changed the state to
302 * \c FLAC__STREAM_DECODER_UNPARSEABLE_STREAM. Now the decoder instead
303 * drops sync and calls the error callback with a new error code
304 * \c FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM. This is
305 * more robust. If your error callback does not discriminate on the the
306 * error state, your code does not need to be changed.
308 * The encoder now has a new setting:
309 * FLAC__stream_encoder_set_apodization(). This is for setting the
310 * method used to window the data before LPC analysis. You only need to
311 * add a call to this function if the default is not There are also
312 * two new convenience functions that may be useful:
313 * FLAC__metadata_object_cuesheet_calculate_cddb_id() and
314 * FLAC__metadata_get_cuesheet().
317 /** \defgroup flac FLAC C API
319 * The FLAC C API is the interface to libFLAC, a set of structures
320 * describing the components of FLAC streams, and functions for
321 * encoding and decoding streams, as well as manipulating FLAC
324 * You should start with the format components as all other modules
325 * are dependent on it.