1 /* libFLAC - Free Lossless Audio Codec library
2 * Copyright (C) 2000,2001,2002 Josh Coalson
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Library General Public License for more details.
14 * You should have received a copy of the GNU Library General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
24 #include "file_decoder.h"
25 #include "file_encoder.h"
29 #include "seekable_stream_decoder.h"
30 #include "seekable_stream_encoder.h"
31 #include "stream_decoder.h"
32 #include "stream_encoder.h"
36 * \section intro Introduction
38 * This is the documentation for the FLAC C and C++ APIs. It is
39 * highly interconnected; this introduction should give you a top
40 * level idea of the structure and how to find the information you
41 * need. As a prerequisite you should have at least a basic
42 * knowledge of the FLAC format, documented
43 * <A HREF="../format.html">here</A>.
45 * \section c_api FLAC C API
47 * The FLAC C API is the interface to libFLAC, a set of structures
48 * describing the components of FLAC streams, and functions for
49 * encoding and decoding streams, as well as manipulating FLAC
50 * metadata in files. The public include files will be installed
51 * in your include area as <include>/FLAC/...
53 * By writing a little code and linking against libFLAC, it is
54 * relatively easy to add FLAC support to another program. The
55 * library is licensed under the
56 * <A HREF="http://www.gnu.org/copyleft/lesser.html">LGPL</A>.
57 * Complete source code of libFLAC as well as the command-line
58 * encoder and plugins is available and is a useful source of
61 * Aside from encoders and decoders, libFLAC provides a powerful
62 * metadata interface for manipulating metadata in FLAC files. It
63 * allows the user to add, delete, and modify FLAC metadata blocks
64 * and it can automatically take advantage of PADDING blocks to avoid
65 * rewriting the entire FLAC file when changing the size of the
68 * libFLAC usually only requires the standard C library and C math
69 * library. In particular, threading is not used so there is no
70 * dependency on a thread library. However, libFLAC does not use
71 * global variables and should be thread-safe.
73 * There is also a new libOggFLAC library which wraps around libFLAC
74 * to provide routines for encoding to and decoding from FLAC streams
75 * inside an Ogg container. The interfaces are very similar or identical
76 * to their counterparts in libFLAC. libOggFLAC is also licensed under
79 * \section cpp_api FLAC C API
81 * The FLAC C++ API is a set of classes that encapsulate the
82 * structures and functions in libFLAC. They provide slightly more
83 * functionality with respect to metadata but are otherwise
84 * equivalent. For the most part, they share the same usage as
85 * their counterparts in libFLAC, and the FLAC C API documentation
86 * can be used as a supplement. The public include files
87 * for the C++ API will be installed in your include area as
88 * <include>/FLAC++/...
90 * There is also a new libOggFLAC++ library, which provides classes
91 * for encoding to and decoding from FLAC streams in an Ogg container.
92 * The classes are very similar to their counterparts in libFLAC++.
94 * Both libFLAC++ libOggFLAC++ are also licensed under the
95 * <A HREF="http://www.gnu.org/copyleft/lesser.html">LGPL</A>.
97 * \section getting_started Getting Started
99 * A good starting point for learning the API is to browse through
100 * the <A HREF="modules.html">modules</A>. Modules are logical
101 * groupings of related functions or classes, which correspond roughly
102 * to header files or sections of header files. Each module includes a
103 * detailed description of the general usage of its functions or
106 * From there you can go on to look at the documentation of
107 * individual functions. You can see different views of the individual
108 * functions through the links in top bar across this page.
110 * \section embedded_developers Embedded Developers
112 * libFLAC has grown larger over time as more functionality has been
113 * included, but much of it may be unnecessary for a particular embedded
114 * implementation. Unused parts may be pruned by some simple editing of
115 * src/libFLAC/Makefile.am. In general, the decoders, encoders, and
116 * metadata interface are all independent from each other.
118 * It is easiest to just describe the dependencies:
120 * - All modules depend on the \link flac_format Format \endlink module.
121 * - The decoders and encoders are independent of each other.
122 * - The metadata interface requires the file decoder.
123 * - The decoder and encoder layers depend on the layers below them, but
124 * not above them; e.g. the seekable stream decoder depends on the stream
125 * decoder but not the file decoder
127 * For example, if your application only requires the stream decoder, no
128 * encoders, and no metadata interface, you can remove the seekable stream
129 * decoder, file decoder, all encoders, and the metadata interface, which
130 * will greatly reduce the size of the library.
133 /** \defgroup flac FLAC C API
135 * The FLAC C API is the interface to libFLAC, a set of structures
136 * describing the components of FLAC streams, and functions for
137 * encoding and decoding streams, as well as manipulating FLAC
140 * You should start with the format components as all other modules
141 * are dependent on it.