diff options
author | Dave Chapman <dave@dchapman.com> | 2005-02-16 19:33:19 +0000 |
---|---|---|
committer | Dave Chapman <dave@dchapman.com> | 2005-02-16 19:33:19 +0000 |
commit | aa97e4d4981d61808a558c5ab36be6d3bcc2c4f6 (patch) | |
tree | a66b2fcd87f37b26e2d4f360e6c2a9db53eb1b5b /apps/codecs/libFLAC/include/FLAC | |
parent | 9b32a1988f848145d96ba2be8cba86e837196df3 (diff) | |
download | rockbox-aa97e4d4981d61808a558c5ab36be6d3bcc2c4f6.tar.gz rockbox-aa97e4d4981d61808a558c5ab36be6d3bcc2c4f6.zip |
Initial import of libFLAC from flac-1.1.2.tar.gz
git-svn-id: svn://svn.rockbox.org/rockbox/trunk@5983 a1c6a512-1295-4272-9138-f99709370657
Diffstat (limited to 'apps/codecs/libFLAC/include/FLAC')
-rw-r--r-- | apps/codecs/libFLAC/include/FLAC/all.h | 158 | ||||
-rw-r--r-- | apps/codecs/libFLAC/include/FLAC/assert.h | 45 | ||||
-rw-r--r-- | apps/codecs/libFLAC/include/FLAC/callback.h | 181 | ||||
-rw-r--r-- | apps/codecs/libFLAC/include/FLAC/export.h | 47 | ||||
-rw-r--r-- | apps/codecs/libFLAC/include/FLAC/file_decoder.h | 660 | ||||
-rw-r--r-- | apps/codecs/libFLAC/include/FLAC/file_encoder.h | 871 | ||||
-rw-r--r-- | apps/codecs/libFLAC/include/FLAC/format.h | 861 | ||||
-rw-r--r-- | apps/codecs/libFLAC/include/FLAC/metadata.h | 1858 | ||||
-rw-r--r-- | apps/codecs/libFLAC/include/FLAC/ordinals.h | 73 | ||||
-rw-r--r-- | apps/codecs/libFLAC/include/FLAC/seekable_stream_decoder.h | 931 | ||||
-rw-r--r-- | apps/codecs/libFLAC/include/FLAC/seekable_stream_encoder.h | 992 | ||||
-rw-r--r-- | apps/codecs/libFLAC/include/FLAC/stream_decoder.h | 873 | ||||
-rw-r--r-- | apps/codecs/libFLAC/include/FLAC/stream_encoder.h | 1064 |
13 files changed, 8614 insertions, 0 deletions
diff --git a/apps/codecs/libFLAC/include/FLAC/all.h b/apps/codecs/libFLAC/include/FLAC/all.h new file mode 100644 index 0000000000..0fd49af6e4 --- /dev/null +++ b/apps/codecs/libFLAC/include/FLAC/all.h | |||
@@ -0,0 +1,158 @@ | |||
1 | /* libFLAC - Free Lossless Audio Codec library | ||
2 | * Copyright (C) 2000,2001,2002,2003,2004,2005 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 "file_decoder.h" | ||
40 | #include "file_encoder.h" | ||
41 | #include "format.h" | ||
42 | #include "metadata.h" | ||
43 | #include "ordinals.h" | ||
44 | #include "seekable_stream_decoder.h" | ||
45 | #include "seekable_stream_encoder.h" | ||
46 | #include "stream_decoder.h" | ||
47 | #include "stream_encoder.h" | ||
48 | |||
49 | /** \mainpage | ||
50 | * | ||
51 | * \section intro Introduction | ||
52 | * | ||
53 | * This is the documentation for the FLAC C and C++ APIs. It is | ||
54 | * highly interconnected; this introduction should give you a top | ||
55 | * level idea of the structure and how to find the information you | ||
56 | * need. As a prerequisite you should have at least a basic | ||
57 | * knowledge of the FLAC format, documented | ||
58 | * <A HREF="../format.html">here</A>. | ||
59 | * | ||
60 | * \section c_api FLAC C API | ||
61 | * | ||
62 | * The FLAC C API is the interface to libFLAC, a set of structures | ||
63 | * describing the components of FLAC streams, and functions for | ||
64 | * encoding and decoding streams, as well as manipulating FLAC | ||
65 | * metadata in files. The public include files will be installed | ||
66 | * in your include area as <include>/FLAC/... | ||
67 | * | ||
68 | * By writing a little code and linking against libFLAC, it is | ||
69 | * relatively easy to add FLAC support to another program. The | ||
70 | * library is licensed under <A HREF="../license.html">Xiph's BSD license</A>. | ||
71 | * Complete source code of libFLAC as well as the command-line | ||
72 | * encoder and plugins is available and is a useful source of | ||
73 | * examples. | ||
74 | * | ||
75 | * Aside from encoders and decoders, libFLAC provides a powerful | ||
76 | * metadata interface for manipulating metadata in FLAC files. It | ||
77 | * allows the user to add, delete, and modify FLAC metadata blocks | ||
78 | * and it can automatically take advantage of PADDING blocks to avoid | ||
79 | * rewriting the entire FLAC file when changing the size of the | ||
80 | * metadata. | ||
81 | * | ||
82 | * libFLAC usually only requires the standard C library and C math | ||
83 | * library. In particular, threading is not used so there is no | ||
84 | * dependency on a thread library. However, libFLAC does not use | ||
85 | * global variables and should be thread-safe. | ||
86 | * | ||
87 | * There is also a new libOggFLAC library which wraps around libFLAC | ||
88 | * to provide routines for encoding to and decoding from FLAC streams | ||
89 | * inside an Ogg container. The interfaces are very similar or identical | ||
90 | * to their counterparts in libFLAC. libOggFLAC is also licensed under | ||
91 | * <A HREF="../license.html">Xiph's BSD license</A>. | ||
92 | * | ||
93 | * \section cpp_api FLAC C++ API | ||
94 | * | ||
95 | * The FLAC C++ API is a set of classes that encapsulate the | ||
96 | * structures and functions in libFLAC. They provide slightly more | ||
97 | * functionality with respect to metadata but are otherwise | ||
98 | * equivalent. For the most part, they share the same usage as | ||
99 | * their counterparts in libFLAC, and the FLAC C API documentation | ||
100 | * can be used as a supplement. The public include files | ||
101 | * for the C++ API will be installed in your include area as | ||
102 | * <include>/FLAC++/... | ||
103 | * | ||
104 | * There is also a new libOggFLAC++ library, which provides classes | ||
105 | * for encoding to and decoding from FLAC streams in an Ogg container. | ||
106 | * The classes are very similar to their counterparts in libFLAC++. | ||
107 | * | ||
108 | * Both libFLAC++ libOggFLAC++ are also licensed under | ||
109 | * <A HREF="../license.html">Xiph's BSD license</A>. | ||
110 | * | ||
111 | * \section getting_started Getting Started | ||
112 | * | ||
113 | * A good starting point for learning the API is to browse through | ||
114 | * the <A HREF="modules.html">modules</A>. Modules are logical | ||
115 | * groupings of related functions or classes, which correspond roughly | ||
116 | * to header files or sections of header files. Each module includes a | ||
117 | * detailed description of the general usage of its functions or | ||
118 | * classes. | ||
119 | * | ||
120 | * From there you can go on to look at the documentation of | ||
121 | * individual functions. You can see different views of the individual | ||
122 | * functions through the links in top bar across this page. | ||
123 | * | ||
124 | * \section embedded_developers Embedded Developers | ||
125 | * | ||
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. | ||
131 | * | ||
132 | * It is easiest to just describe the dependencies: | ||
133 | * | ||
134 | * - All modules depend on the \link flac_format Format \endlink module. | ||
135 | * - The decoders and encoders are independent of each other. | ||
136 | * - The metadata interface requires the file decoder. | ||
137 | * - The decoder and encoder layers depend on the layers below them, but | ||
138 | * not above them; e.g. the seekable stream decoder depends on the stream | ||
139 | * decoder but not the file decoder | ||
140 | * | ||
141 | * For example, if your application only requires the stream decoder, no | ||
142 | * encoders, and no metadata interface, you can remove the seekable stream | ||
143 | * decoder, file decoder, all encoders, and the metadata interface, which | ||
144 | * will greatly reduce the size of the library. | ||
145 | */ | ||
146 | |||
147 | /** \defgroup flac FLAC C API | ||
148 | * | ||
149 | * The FLAC C API is the interface to libFLAC, a set of structures | ||
150 | * describing the components of FLAC streams, and functions for | ||
151 | * encoding and decoding streams, as well as manipulating FLAC | ||
152 | * metadata in files. | ||
153 | * | ||
154 | * You should start with the format components as all other modules | ||
155 | * are dependent on it. | ||
156 | */ | ||
157 | |||
158 | #endif | ||
diff --git a/apps/codecs/libFLAC/include/FLAC/assert.h b/apps/codecs/libFLAC/include/FLAC/assert.h new file mode 100644 index 0000000000..99e3381fd1 --- /dev/null +++ b/apps/codecs/libFLAC/include/FLAC/assert.h | |||
@@ -0,0 +1,45 @@ | |||
1 | /* libFLAC - Free Lossless Audio Codec library | ||
2 | * Copyright (C) 2001,2002,2003,2004,2005 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__ASSERT_H | ||
33 | #define FLAC__ASSERT_H | ||
34 | |||
35 | /* we need this since some compilers (like MSVC) leave assert()s on release code (and we don't want to use their ASSERT) */ | ||
36 | #ifdef DEBUG | ||
37 | #include <assert.h> | ||
38 | #define FLAC__ASSERT(x) assert(x) | ||
39 | #define FLAC__ASSERT_DECLARATION(x) x | ||
40 | #else | ||
41 | #define FLAC__ASSERT(x) | ||
42 | #define FLAC__ASSERT_DECLARATION(x) | ||
43 | #endif | ||
44 | |||
45 | #endif | ||
diff --git a/apps/codecs/libFLAC/include/FLAC/callback.h b/apps/codecs/libFLAC/include/FLAC/callback.h new file mode 100644 index 0000000000..c6f94c0cf4 --- /dev/null +++ b/apps/codecs/libFLAC/include/FLAC/callback.h | |||
@@ -0,0 +1,181 @@ | |||
1 | /* libFLAC - Free Lossless Audio Codec library | ||
2 | * Copyright (C) 2004,2005 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__CALLBACK_H | ||
33 | #define FLAC__CALLBACK_H | ||
34 | |||
35 | #include "ordinals.h" | ||
36 | #include <stdlib.h> /* for size_t */ | ||
37 | |||
38 | /** \file include/FLAC/callback.h | ||
39 | * | ||
40 | * \brief | ||
41 | * This module defines the structures for describing I/O callbacks | ||
42 | * to the other FLAC interfaces. | ||
43 | * | ||
44 | * See the detailed documentation for callbacks in the | ||
45 | * \link flac_callbacks callbacks \endlink module. | ||
46 | */ | ||
47 | |||
48 | /** \defgroup flac_callbacks FLAC/callback.h: I/O callback structures | ||
49 | * \ingroup flac | ||
50 | * | ||
51 | * \brief | ||
52 | * This module defines the structures for describing I/O callbacks | ||
53 | * to the other FLAC interfaces. | ||
54 | * | ||
55 | * The purpose of the I/O callback functions is to create a common way | ||
56 | * for the metadata interfaces to handle I/O. | ||
57 | * | ||
58 | * Originally the metadata interfaces required filenames as the way of | ||
59 | * specifying FLAC files to operate on. This is problematic in some | ||
60 | * environments so there is an additional option to specify a set of | ||
61 | * callbacks for doing I/O on the FLAC file, instead of the filename. | ||
62 | * | ||
63 | * In addition to the callbacks, a FLAC__IOHandle type is defined as an | ||
64 | * opaque structure for a data source. | ||
65 | * | ||
66 | * The callback function prototypes are similar (but not identical) to the | ||
67 | * stdio functions fread, fwrite, fseek, ftell, feof, and fclose. If you use | ||
68 | * stdio streams to implement the callbacks, you can pass fread, fwrite, and | ||
69 | * fclose anywhere a FLAC__IOCallback_Read, FLAC__IOCallback_Write, or | ||
70 | * FLAC__IOCallback_Close is required, and a FILE* anywhere a FLAC__IOHandle | ||
71 | * is required. \warning You generally can NOT directly use fseek or ftell | ||
72 | * for FLAC__IOCallback_Seek or FLAC__IOCallback_Tell since on most systems | ||
73 | * these use 32-bit offsets and FLAC requires 64-bit offsets to deal with | ||
74 | * large files. You will have to find an equivalent function (e.g. ftello), | ||
75 | * or write a wrapper. The same is true for feof() since this is usually | ||
76 | * implemented as a macro, not as a function whose address can be taken. | ||
77 | * | ||
78 | * \{ | ||
79 | */ | ||
80 | |||
81 | #ifdef __cplusplus | ||
82 | extern "C" { | ||
83 | #endif | ||
84 | |||
85 | typedef void* FLAC__IOHandle; | ||
86 | |||
87 | /** Signature for the read callback. | ||
88 | * The signature and semantics match POSIX fread() implementations | ||
89 | * and can generally be used interchangeably. | ||
90 | * | ||
91 | * \param ptr The address of the read buffer. | ||
92 | * \param size The size of the records to be read. | ||
93 | * \param nmemb The number of records to be read. | ||
94 | * \param handle The handle to the data source. | ||
95 | * \retval size_t | ||
96 | * The number of records read. | ||
97 | */ | ||
98 | typedef size_t (*FLAC__IOCallback_Read) (void *ptr, size_t size, size_t nmemb, FLAC__IOHandle handle); | ||
99 | |||
100 | /** Signature for the write callback. | ||
101 | * The signature and semantics match POSIX fwrite() implementations | ||
102 | * and can generally be used interchangeably. | ||
103 | * | ||
104 | * \param ptr The address of the write buffer. | ||
105 | * \param size The size of the records to be written. | ||
106 | * \param nmemb The number of records to be written. | ||
107 | * \param handle The handle to the data source. | ||
108 | * \retval size_t | ||
109 | * The number of records written. | ||
110 | */ | ||
111 | typedef size_t (*FLAC__IOCallback_Write) (const void *ptr, size_t size, size_t nmemb, FLAC__IOHandle handle); | ||
112 | |||
113 | /** Signature for the seek callback. | ||
114 | * The signature and semantics mostly match POSIX fseek() WITH ONE IMPORTANT | ||
115 | * EXCEPTION: the offset is a 64-bit type whereas fseek() is generally 'long' | ||
116 | * and 32-bits wide. | ||
117 | * | ||
118 | * \param handle The handle to the data source. | ||
119 | * \param offset The new position, relative to \a whence | ||
120 | * \param whence \c SEEK_SET, \c SEEK_CUR, or \c SEEK_END | ||
121 | * \retval int | ||
122 | * \c 0 on success, \c -1 on error. | ||
123 | */ | ||
124 | typedef int (*FLAC__IOCallback_Seek) (FLAC__IOHandle handle, FLAC__int64 offset, int whence); | ||
125 | |||
126 | /** Signature for the tell callback. | ||
127 | * The signature and semantics mostly match POSIX ftell() WITH ONE IMPORTANT | ||
128 | * EXCEPTION: the offset is a 64-bit type whereas ftell() is generally 'long' | ||
129 | * and 32-bits wide. | ||
130 | * | ||
131 | * \param handle The handle to the data source. | ||
132 | * \retval FLAC__int64 | ||
133 | * The current position on success, \c -1 on error. | ||
134 | */ | ||
135 | typedef FLAC__int64 (*FLAC__IOCallback_Tell) (FLAC__IOHandle handle); | ||
136 | |||
137 | /** Signature for the EOF callback. | ||
138 | * The signature and semantics mostly match POSIX feof() but WATCHOUT: | ||
139 | * on many systems, feof() is a macro, so in this case a wrapper function | ||
140 | * must be provided instead. | ||
141 | * | ||
142 | * \param handle The handle to the data source. | ||
143 | * \retval int | ||
144 | * \c 0 if not at end of file, nonzero if at end of file. | ||
145 | */ | ||
146 | typedef int (*FLAC__IOCallback_Eof) (FLAC__IOHandle handle); | ||
147 | |||
148 | /** Signature for the close callback. | ||
149 | * The signature and semantics match POSIX fclose() implementations | ||
150 | * and can generally be used interchangeably. | ||
151 | * | ||
152 | * \param handle The handle to the data source. | ||
153 | * \retval int | ||
154 | * \c 0 on success, \c EOF on error. | ||
155 | */ | ||
156 | typedef int (*FLAC__IOCallback_Close) (FLAC__IOHandle handle); | ||
157 | |||
158 | /** A structure for holding a set of callbacks. | ||
159 | * Each FLAC interface that requires a FLAC__IOCallbacks structure will | ||
160 | * describe which of the callbacks are required. The ones that are not | ||
161 | * required may be set to NULL. | ||
162 | * | ||
163 | * If the seek requirement for an interface is optional, you can signify that | ||
164 | * a data sorce is not seekable by setting the \a seek field to \c NULL. | ||
165 | */ | ||
166 | typedef struct { | ||
167 | FLAC__IOCallback_Read read; | ||
168 | FLAC__IOCallback_Write write; | ||
169 | FLAC__IOCallback_Seek seek; | ||
170 | FLAC__IOCallback_Tell tell; | ||
171 | FLAC__IOCallback_Eof eof; | ||
172 | FLAC__IOCallback_Close close; | ||
173 | } FLAC__IOCallbacks; | ||
174 | |||
175 | /* \} */ | ||
176 | |||
177 | #ifdef __cplusplus | ||
178 | } | ||
179 | #endif | ||
180 | |||
181 | #endif | ||
diff --git a/apps/codecs/libFLAC/include/FLAC/export.h b/apps/codecs/libFLAC/include/FLAC/export.h new file mode 100644 index 0000000000..db4ec59d2f --- /dev/null +++ b/apps/codecs/libFLAC/include/FLAC/export.h | |||
@@ -0,0 +1,47 @@ | |||
1 | /* libFLAC - Free Lossless Audio Codec library | ||
2 | * Copyright (C) 2000,2001,2002,2003,2004,2005 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__EXPORT_H | ||
33 | #define FLAC__EXPORT_H | ||
34 | |||
35 | #if defined(FLAC__NO_DLL) || !defined(_MSC_VER) | ||
36 | #define FLAC_API | ||
37 | |||
38 | #else | ||
39 | |||
40 | #ifdef FLAC_API_EXPORTS | ||
41 | #define FLAC_API _declspec(dllexport) | ||
42 | #else | ||
43 | #define FLAC_API _declspec(dllimport) | ||
44 | |||
45 | #endif | ||
46 | #endif | ||
47 | #endif | ||
diff --git a/apps/codecs/libFLAC/include/FLAC/file_decoder.h b/apps/codecs/libFLAC/include/FLAC/file_decoder.h new file mode 100644 index 0000000000..c4b1c6cdb7 --- /dev/null +++ b/apps/codecs/libFLAC/include/FLAC/file_decoder.h | |||
@@ -0,0 +1,660 @@ | |||
1 | /* libFLAC - Free Lossless Audio Codec library | ||
2 | * Copyright (C) 2000,2001,2002,2003,2004,2005 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__FILE_DECODER_H | ||
33 | #define FLAC__FILE_DECODER_H | ||
34 | |||
35 | #include "export.h" | ||
36 | #include "seekable_stream_decoder.h" | ||
37 | |||
38 | #ifdef __cplusplus | ||
39 | extern "C" { | ||
40 | #endif | ||
41 | |||
42 | |||
43 | /** \file include/FLAC/file_decoder.h | ||
44 | * | ||
45 | * \brief | ||
46 | * This module contains the functions which implement the file | ||
47 | * decoder. | ||
48 | * | ||
49 | * See the detailed documentation in the | ||
50 | * \link flac_file_decoder file decoder \endlink module. | ||
51 | */ | ||
52 | |||
53 | /** \defgroup flac_file_decoder FLAC/file_decoder.h: file decoder interface | ||
54 | * \ingroup flac_decoder | ||
55 | * | ||
56 | * \brief | ||
57 | * This module contains the functions which implement the file | ||
58 | * decoder. | ||
59 | * | ||
60 | * The basic usage of this decoder is as follows: | ||
61 | * - The program creates an instance of a decoder using | ||
62 | * FLAC__file_decoder_new(). | ||
63 | * - The program overrides the default settings and sets callbacks for | ||
64 | * writing, error reporting, and metadata reporting using | ||
65 | * FLAC__file_decoder_set_*() functions. | ||
66 | * - The program initializes the instance to validate the settings and | ||
67 | * prepare for decoding using FLAC__file_decoder_init(). | ||
68 | * - The program calls the FLAC__file_decoder_process_*() functions | ||
69 | * to decode data, which subsequently calls the callbacks. | ||
70 | * - The program finishes the decoding with FLAC__file_decoder_finish(), | ||
71 | * which flushes the input and output and resets the decoder to the | ||
72 | * uninitialized state. | ||
73 | * - The instance may be used again or deleted with | ||
74 | * FLAC__file_decoder_delete(). | ||
75 | * | ||
76 | * The file decoder is a trivial wrapper around the | ||
77 | * \link flac_seekable_stream_decoder seekable stream decoder \endlink | ||
78 | * meant to simplfy the process of decoding from a standard file. The | ||
79 | * file decoder supplies all but the Write/Metadata/Error callbacks. | ||
80 | * The user needs only to provide the path to the file and the file | ||
81 | * decoder handles the rest. | ||
82 | * | ||
83 | * Like the seekable stream decoder, seeking is exposed through the | ||
84 | * FLAC__file_decoder_seek_absolute() method. At any point after the file | ||
85 | * decoder has been initialized, the user can call this function to seek to | ||
86 | * an exact sample within the file. Subsequently, the first time the write | ||
87 | * callback is called it will be passed a (possibly partial) block starting | ||
88 | * at that sample. | ||
89 | * | ||
90 | * The file decoder also inherits MD5 signature checking from the seekable | ||
91 | * stream decoder. If this is turned on before initialization, | ||
92 | * FLAC__file_decoder_finish() will report when the decoded MD5 signature | ||
93 | * does not match the one stored in the STREAMINFO block. MD5 checking is | ||
94 | * automatically turned off if there is no signature in the STREAMINFO | ||
95 | * block or when a seek is attempted. | ||
96 | * | ||
97 | * Make sure to read the detailed descriptions of the | ||
98 | * \link flac_seekable_stream_decoder seekable stream decoder module \endlink | ||
99 | * and \link flac_stream_decoder stream decoder module \endlink | ||
100 | * since the file decoder inherits much of its behavior from them. | ||
101 | * | ||
102 | * \note | ||
103 | * The "set" functions may only be called when the decoder is in the | ||
104 | * state FLAC__FILE_DECODER_UNINITIALIZED, i.e. after | ||
105 | * FLAC__file_decoder_new() or FLAC__file_decoder_finish(), but | ||
106 | * before FLAC__file_decoder_init(). If this is the case they will | ||
107 | * return \c true, otherwise \c false. | ||
108 | * | ||
109 | * \note | ||
110 | * FLAC__file_decoder_finish() resets all settings to the constructor | ||
111 | * defaults, including the callbacks. | ||
112 | * | ||
113 | * \{ | ||
114 | */ | ||
115 | |||
116 | |||
117 | /** State values for a FLAC__FileDecoder | ||
118 | * | ||
119 | * The decoder's state can be obtained by calling FLAC__file_decoder_get_state(). | ||
120 | */ | ||
121 | typedef enum { | ||
122 | |||
123 | FLAC__FILE_DECODER_OK = 0, | ||
124 | /**< The decoder is in the normal OK state. */ | ||
125 | |||
126 | FLAC__FILE_DECODER_END_OF_FILE, | ||
127 | /**< The decoder has reached the end of the file. */ | ||
128 | |||
129 | FLAC__FILE_DECODER_ERROR_OPENING_FILE, | ||
130 | /**< An error occurred opening the input file. */ | ||
131 | |||
132 | FLAC__FILE_DECODER_MEMORY_ALLOCATION_ERROR, | ||
133 | /**< An error occurred allocating memory. */ | ||
134 | |||
135 | FLAC__FILE_DECODER_SEEK_ERROR, | ||
136 | /**< An error occurred while seeking. */ | ||
137 | |||
138 | FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR, | ||
139 | /**< An error occurred in the underlying seekable stream decoder. */ | ||
140 | |||
141 | FLAC__FILE_DECODER_ALREADY_INITIALIZED, | ||
142 | /**< FLAC__file_decoder_init() was called when the decoder was already | ||
143 | * initialized, usually because FLAC__file_decoder_finish() was not | ||
144 | * called. | ||
145 | */ | ||
146 | |||
147 | FLAC__FILE_DECODER_INVALID_CALLBACK, | ||
148 | /**< FLAC__file_decoder_init() was called without all callbacks | ||
149 | * being set. | ||
150 | */ | ||
151 | |||
152 | FLAC__FILE_DECODER_UNINITIALIZED | ||
153 | /**< The decoder is in the uninitialized state. */ | ||
154 | |||
155 | } FLAC__FileDecoderState; | ||
156 | |||
157 | /** Maps a FLAC__FileDecoderState to a C string. | ||
158 | * | ||
159 | * Using a FLAC__FileDecoderState as the index to this array | ||
160 | * will give the string equivalent. The contents should not be modified. | ||
161 | */ | ||
162 | extern FLAC_API const char * const FLAC__FileDecoderStateString[]; | ||
163 | |||
164 | |||
165 | /*********************************************************************** | ||
166 | * | ||
167 | * class FLAC__FileDecoder : public FLAC__StreamDecoder | ||
168 | * | ||
169 | ***********************************************************************/ | ||
170 | |||
171 | struct FLAC__FileDecoderProtected; | ||
172 | struct FLAC__FileDecoderPrivate; | ||
173 | /** The opaque structure definition for the file decoder type. See the | ||
174 | * \link flac_file_decoder file decoder module \endlink for a detailed | ||
175 | * description. | ||
176 | */ | ||
177 | typedef struct { | ||
178 | struct FLAC__FileDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */ | ||
179 | struct FLAC__FileDecoderPrivate *private_; /* avoid the C++ keyword 'private' */ | ||
180 | } FLAC__FileDecoder; | ||
181 | |||
182 | /** Signature for the write callback. | ||
183 | * See FLAC__file_decoder_set_write_callback() | ||
184 | * and FLAC__SeekableStreamDecoderWriteCallback for more info. | ||
185 | * | ||
186 | * \param decoder The decoder instance calling the callback. | ||
187 | * \param frame The description of the decoded frame. | ||
188 | * \param buffer An array of pointers to decoded channels of data. | ||
189 | * \param client_data The callee's client data set through | ||
190 | * FLAC__file_decoder_set_client_data(). | ||
191 | * \retval FLAC__StreamDecoderWriteStatus | ||
192 | * The callee's return status. | ||
193 | */ | ||
194 | typedef FLAC__StreamDecoderWriteStatus (*FLAC__FileDecoderWriteCallback)(const FLAC__FileDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data); | ||
195 | |||
196 | /** Signature for the metadata callback. | ||
197 | * See FLAC__file_decoder_set_metadata_callback() | ||
198 | * and FLAC__SeekableStreamDecoderMetadataCallback for more info. | ||
199 | * | ||
200 | * \param decoder The decoder instance calling the callback. | ||
201 | * \param metadata The decoded metadata block. | ||
202 | * \param client_data The callee's client data set through | ||
203 | * FLAC__file_decoder_set_client_data(). | ||
204 | */ | ||
205 | typedef void (*FLAC__FileDecoderMetadataCallback)(const FLAC__FileDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data); | ||
206 | |||
207 | /** Signature for the error callback. | ||
208 | * See FLAC__file_decoder_set_error_callback() | ||
209 | * and FLAC__SeekableStreamDecoderErrorCallback for more info. | ||
210 | * | ||
211 | * \param decoder The decoder instance calling the callback. | ||
212 | * \param status The error encountered by the decoder. | ||
213 | * \param client_data The callee's client data set through | ||
214 | * FLAC__file_decoder_set_client_data(). | ||
215 | */ | ||
216 | typedef void (*FLAC__FileDecoderErrorCallback)(const FLAC__FileDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data); | ||
217 | |||
218 | |||
219 | /*********************************************************************** | ||
220 | * | ||
221 | * Class constructor/destructor | ||
222 | * | ||
223 | ***********************************************************************/ | ||
224 | |||
225 | /** Create a new file decoder instance. The instance is created with | ||
226 | * default settings; see the individual FLAC__file_decoder_set_*() | ||
227 | * functions for each setting's default. | ||
228 | * | ||
229 | * \retval FLAC__FileDecoder* | ||
230 | * \c NULL if there was an error allocating memory, else the new instance. | ||
231 | */ | ||
232 | FLAC_API FLAC__FileDecoder *FLAC__file_decoder_new(); | ||
233 | |||
234 | /** Free a decoder instance. Deletes the object pointed to by \a decoder. | ||
235 | * | ||
236 | * \param decoder A pointer to an existing decoder. | ||
237 | * \assert | ||
238 | * \code decoder != NULL \endcode | ||
239 | */ | ||
240 | FLAC_API void FLAC__file_decoder_delete(FLAC__FileDecoder *decoder); | ||
241 | |||
242 | |||
243 | /*********************************************************************** | ||
244 | * | ||
245 | * Public class method prototypes | ||
246 | * | ||
247 | ***********************************************************************/ | ||
248 | |||
249 | /** Set the "MD5 signature checking" flag. | ||
250 | * This is inherited from FLAC__SeekableStreamDecoder; see | ||
251 | * FLAC__seekable_stream_decoder_set_md5_checking(). | ||
252 | * | ||
253 | * \default \c false | ||
254 | * \param decoder A decoder instance to set. | ||
255 | * \param value See above. | ||
256 | * \assert | ||
257 | * \code decoder != NULL \endcode | ||
258 | * \retval FLAC__bool | ||
259 | * \c false if the decoder is already initialized, else \c true. | ||
260 | */ | ||
261 | FLAC_API FLAC__bool FLAC__file_decoder_set_md5_checking(FLAC__FileDecoder *decoder, FLAC__bool value); | ||
262 | |||
263 | /** Set the input file name to decode. | ||
264 | * | ||
265 | * \default \c "-" | ||
266 | * \param decoder A decoder instance to set. | ||
267 | * \param value The input file name, or "-" for \c stdin. | ||
268 | * \assert | ||
269 | * \code decoder != NULL \endcode | ||
270 | * \code value != NULL \endcode | ||
271 | * \retval FLAC__bool | ||
272 | * \c false if the decoder is already initialized, or there was a memory | ||
273 | * allocation error, else \c true. | ||
274 | */ | ||
275 | FLAC_API FLAC__bool FLAC__file_decoder_set_filename(FLAC__FileDecoder *decoder, const char *value); | ||
276 | |||
277 | /** Set the write callback. | ||
278 | * This is inherited from FLAC__SeekableStreamDecoder; see | ||
279 | * FLAC__seekable_stream_decoder_set_write_callback(). | ||
280 | * | ||
281 | * \note | ||
282 | * The callback is mandatory and must be set before initialization. | ||
283 | * | ||
284 | * \default \c NULL | ||
285 | * \param decoder A decoder instance to set. | ||
286 | * \param value See above. | ||
287 | * \assert | ||
288 | * \code decoder != NULL \endcode | ||
289 | * \code value != NULL \endcode | ||
290 | * \retval FLAC__bool | ||
291 | * \c false if the decoder is already initialized, else \c true. | ||
292 | */ | ||
293 | FLAC_API FLAC__bool FLAC__file_decoder_set_write_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderWriteCallback value); | ||
294 | |||
295 | /** Set the metadata callback. | ||
296 | * This is inherited from FLAC__SeekableStreamDecoder; see | ||
297 | * FLAC__seekable_stream_decoder_set_metadata_callback(). | ||
298 | * | ||
299 | * \note | ||
300 | * The callback is mandatory and must be set before initialization. | ||
301 | * | ||
302 | * \default \c NULL | ||
303 | * \param decoder A decoder instance to set. | ||
304 | * \param value See above. | ||
305 | * \assert | ||
306 | * \code decoder != NULL \endcode | ||
307 | * \code value != NULL \endcode | ||
308 | * \retval FLAC__bool | ||
309 | * \c false if the decoder is already initialized, else \c true. | ||
310 | */ | ||
311 | FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderMetadataCallback value); | ||
312 | |||
313 | /** Set the error callback. | ||
314 | * This is inherited from FLAC__SeekableStreamDecoder; see | ||
315 | * FLAC__seekable_stream_decoder_set_error_callback(). | ||
316 | * | ||
317 | * \note | ||
318 | * The callback is mandatory and must be set before initialization. | ||
319 | * | ||
320 | * \default \c NULL | ||
321 | * \param decoder A decoder instance to set. | ||
322 | * \param value See above. | ||
323 | * \assert | ||
324 | * \code decoder != NULL \endcode | ||
325 | * \code value != NULL \endcode | ||
326 | * \retval FLAC__bool | ||
327 | * \c false if the decoder is already initialized, else \c true. | ||
328 | */ | ||
329 | FLAC_API FLAC__bool FLAC__file_decoder_set_error_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderErrorCallback value); | ||
330 | |||
331 | /** Set the client data to be passed back to callbacks. | ||
332 | * This value will be supplied to callbacks in their \a client_data | ||
333 | * argument. | ||
334 | * | ||
335 | * \default \c NULL | ||
336 | * \param decoder A decoder instance to set. | ||
337 | * \param value See above. | ||
338 | * \assert | ||
339 | * \code decoder != NULL \endcode | ||
340 | * \retval FLAC__bool | ||
341 | * \c false if the decoder is already initialized, else \c true. | ||
342 | */ | ||
343 | FLAC_API FLAC__bool FLAC__file_decoder_set_client_data(FLAC__FileDecoder *decoder, void *value); | ||
344 | |||
345 | /** This is inherited from FLAC__SeekableStreamDecoder; see | ||
346 | * FLAC__seekable_stream_decoder_set_metadata_respond(). | ||
347 | * | ||
348 | * \default By default, only the \c STREAMINFO block is returned via the | ||
349 | * metadata callback. | ||
350 | * \param decoder A decoder instance to set. | ||
351 | * \param type See above. | ||
352 | * \assert | ||
353 | * \code decoder != NULL \endcode | ||
354 | * \a type is valid | ||
355 | * \retval FLAC__bool | ||
356 | * \c false if the decoder is already initialized, else \c true. | ||
357 | */ | ||
358 | FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond(FLAC__FileDecoder *decoder, FLAC__MetadataType type); | ||
359 | |||
360 | /** This is inherited from FLAC__SeekableStreamDecoder; see | ||
361 | * FLAC__seekable_stream_decoder_set_metadata_respond_application(). | ||
362 | * | ||
363 | * \default By default, only the \c STREAMINFO block is returned via the | ||
364 | * metadata callback. | ||
365 | * \param decoder A decoder instance to set. | ||
366 | * \param id See above. | ||
367 | * \assert | ||
368 | * \code decoder != NULL \endcode | ||
369 | * \code id != NULL \endcode | ||
370 | * \retval FLAC__bool | ||
371 | * \c false if the decoder is already initialized, else \c true. | ||
372 | */ | ||
373 | FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond_application(FLAC__FileDecoder *decoder, const FLAC__byte id[4]); | ||
374 | |||
375 | /** This is inherited from FLAC__SeekableStreamDecoder; see | ||
376 | * FLAC__seekable_stream_decoder_set_metadata_respond_all(). | ||
377 | * | ||
378 | * \default By default, only the \c STREAMINFO block is returned via the | ||
379 | * metadata callback. | ||
380 | * \param decoder A decoder instance to set. | ||
381 | * \assert | ||
382 | * \code decoder != NULL \endcode | ||
383 | * \retval FLAC__bool | ||
384 | * \c false if the decoder is already initialized, else \c true. | ||
385 | */ | ||
386 | FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond_all(FLAC__FileDecoder *decoder); | ||
387 | |||
388 | /** This is inherited from FLAC__SeekableStreamDecoder; see | ||
389 | * FLAC__seekable_stream_decoder_set_metadata_ignore(). | ||
390 | * | ||
391 | * \default By default, only the \c STREAMINFO block is returned via the | ||
392 | * metadata callback. | ||
393 | * \param decoder A decoder instance to set. | ||
394 | * \param type See above. | ||
395 | * \assert | ||
396 | * \code decoder != NULL \endcode | ||
397 | * \a type is valid | ||
398 | * \retval FLAC__bool | ||
399 | * \c false if the decoder is already initialized, else \c true. | ||
400 | */ | ||
401 | FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore(FLAC__FileDecoder *decoder, FLAC__MetadataType type); | ||
402 | |||
403 | /** This is inherited from FLAC__SeekableStreamDecoder; see | ||
404 | * FLAC__seekable_stream_decoder_set_metadata_ignore_application(). | ||
405 | * | ||
406 | * \default By default, only the \c STREAMINFO block is returned via the | ||
407 | * metadata callback. | ||
408 | * \param decoder A decoder instance to set. | ||
409 | * \param id See above. | ||
410 | * \assert | ||
411 | * \code decoder != NULL \endcode | ||
412 | * \code id != NULL \endcode | ||
413 | * \retval FLAC__bool | ||
414 | * \c false if the decoder is already initialized, else \c true. | ||
415 | */ | ||
416 | FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore_application(FLAC__FileDecoder *decoder, const FLAC__byte id[4]); | ||
417 | |||
418 | /** This is inherited from FLAC__SeekableStreamDecoder; see | ||
419 | * FLAC__seekable_stream_decoder_set_metadata_ignore_all(). | ||
420 | * | ||
421 | * \default By default, only the \c STREAMINFO block is returned via the | ||
422 | * metadata callback. | ||
423 | * \param decoder A decoder instance to set. | ||
424 | * \assert | ||
425 | * \code decoder != NULL \endcode | ||
426 | * \retval FLAC__bool | ||
427 | * \c false if the decoder is already initialized, else \c true. | ||
428 | */ | ||
429 | FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore_all(FLAC__FileDecoder *decoder); | ||
430 | |||
431 | /** Get the current decoder state. | ||
432 | * | ||
433 | * \param decoder A decoder instance to query. | ||
434 | * \assert | ||
435 | * \code decoder != NULL \endcode | ||
436 | * \retval FLAC__FileDecoderState | ||
437 | * The current decoder state. | ||
438 | */ | ||
439 | FLAC_API FLAC__FileDecoderState FLAC__file_decoder_get_state(const FLAC__FileDecoder *decoder); | ||
440 | |||
441 | /** Get the state of the underlying seekable stream decoder. | ||
442 | * Useful when the file decoder state is | ||
443 | * \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR. | ||
444 | * | ||
445 | * \param decoder A decoder instance to query. | ||
446 | * \assert | ||
447 | * \code decoder != NULL \endcode | ||
448 | * \retval FLAC__SeekableStreamDecoderState | ||
449 | * The seekable stream decoder state. | ||
450 | */ | ||
451 | FLAC_API FLAC__SeekableStreamDecoderState FLAC__file_decoder_get_seekable_stream_decoder_state(const FLAC__FileDecoder *decoder); | ||
452 | |||
453 | /** Get the state of the underlying stream decoder. | ||
454 | * Useful when the file decoder state is | ||
455 | * \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR and the seekable stream | ||
456 | * decoder state is \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR. | ||
457 | * | ||
458 | * \param decoder A decoder instance to query. | ||
459 | * \assert | ||
460 | * \code decoder != NULL \endcode | ||
461 | * \retval FLAC__StreamDecoderState | ||
462 | * The seekable stream decoder state. | ||
463 | */ | ||
464 | FLAC_API FLAC__StreamDecoderState FLAC__file_decoder_get_stream_decoder_state(const FLAC__FileDecoder *decoder); | ||
465 | |||
466 | /** Get the current decoder state as a C string. | ||
467 | * This version automatically resolves | ||
468 | * \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR by getting the | ||
469 | * seekable stream decoder's state. | ||
470 | * | ||
471 | * \param decoder A decoder instance to query. | ||
472 | * \assert | ||
473 | * \code decoder != NULL \endcode | ||
474 | * \retval const char * | ||
475 | * The decoder state as a C string. Do not modify the contents. | ||
476 | */ | ||
477 | FLAC_API const char *FLAC__file_decoder_get_resolved_state_string(const FLAC__FileDecoder *decoder); | ||
478 | |||
479 | /** Get the "MD5 signature checking" flag. | ||
480 | * This is inherited from FLAC__SeekableStreamDecoder; see | ||
481 | * FLAC__seekable_stream_decoder_get_md5_checking(). | ||
482 | * | ||
483 | * \param decoder A decoder instance to query. | ||
484 | * \assert | ||
485 | * \code decoder != NULL \endcode | ||
486 | * \retval FLAC__bool | ||
487 | * See above. | ||
488 | */ | ||
489 | FLAC_API FLAC__bool FLAC__file_decoder_get_md5_checking(const FLAC__FileDecoder *decoder); | ||
490 | |||
491 | /** This is inherited from FLAC__SeekableStreamDecoder; see | ||
492 | * FLAC__seekable_stream_decoder_get_channels(). | ||
493 | * | ||
494 | * \param decoder A decoder instance to query. | ||
495 | * \assert | ||
496 | * \code decoder != NULL \endcode | ||
497 | * \retval unsigned | ||
498 | * See above. | ||
499 | */ | ||
500 | FLAC_API unsigned FLAC__file_decoder_get_channels(const FLAC__FileDecoder *decoder); | ||
501 | |||
502 | /** This is inherited from FLAC__SeekableStreamDecoder; see | ||
503 | * FLAC__seekable_stream_decoder_get_channel_assignment(). | ||
504 | * | ||
505 | * \param decoder A decoder instance to query. | ||
506 | * \assert | ||
507 | * \code decoder != NULL \endcode | ||
508 | * \retval FLAC__ChannelAssignment | ||
509 | * See above. | ||
510 | */ | ||
511 | FLAC_API FLAC__ChannelAssignment FLAC__file_decoder_get_channel_assignment(const FLAC__FileDecoder *decoder); | ||
512 | |||
513 | /** This is inherited from FLAC__SeekableStreamDecoder; see | ||
514 | * FLAC__seekable_stream_decoder_get_bits_per_sample(). | ||
515 | * | ||
516 | * \param decoder A decoder instance to query. | ||
517 | * \assert | ||
518 | * \code decoder != NULL \endcode | ||
519 | * \retval unsigned | ||
520 | * See above. | ||
521 | */ | ||
522 | FLAC_API unsigned FLAC__file_decoder_get_bits_per_sample(const FLAC__FileDecoder *decoder); | ||
523 | |||
524 | /** This is inherited from FLAC__SeekableStreamDecoder; see | ||
525 | * FLAC__seekable_stream_decoder_get_sample_rate(). | ||
526 | * | ||
527 | * \param decoder A decoder instance to query. | ||
528 | * \assert | ||
529 | * \code decoder != NULL \endcode | ||
530 | * \retval unsigned | ||
531 | * See above. | ||
532 | */ | ||
533 | FLAC_API unsigned FLAC__file_decoder_get_sample_rate(const FLAC__FileDecoder *decoder); | ||
534 | |||
535 | /** This is inherited from FLAC__SeekableStreamDecoder; see | ||
536 | * FLAC__seekable_stream_decoder_get_blocksize(). | ||
537 | * | ||
538 | * \param decoder A decoder instance to query. | ||
539 | * \assert | ||
540 | * \code decoder != NULL \endcode | ||
541 | * \retval unsigned | ||
542 | * See above. | ||
543 | */ | ||
544 | FLAC_API unsigned FLAC__file_decoder_get_blocksize(const FLAC__FileDecoder *decoder); | ||
545 | |||
546 | /** This is inherited from FLAC__SeekableStreamDecoder; see | ||
547 | * FLAC__seekable_stream_decoder_get_decode_position(). | ||
548 | * | ||
549 | * \param decoder A decoder instance to query. | ||
550 | * \param position Address at which to return the desired position. | ||
551 | * \assert | ||
552 | * \code decoder != NULL \endcode | ||
553 | * \code position != NULL \endcode | ||
554 | * \retval FLAC__bool | ||
555 | * \c true if successful, \c false if there was an error from | ||
556 | * the 'tell' callback. | ||
557 | */ | ||
558 | FLAC_API FLAC__bool FLAC__file_decoder_get_decode_position(const FLAC__FileDecoder *decoder, FLAC__uint64 *position); | ||
559 | |||
560 | /** Initialize the decoder instance. | ||
561 | * Should be called after FLAC__file_decoder_new() and | ||
562 | * FLAC__file_decoder_set_*() but before any of the | ||
563 | * FLAC__file_decoder_process_*() functions. Will set and return | ||
564 | * the decoder state, which will be FLAC__FILE_DECODER_OK if | ||
565 | * initialization succeeded. | ||
566 | * | ||
567 | * \param decoder An uninitialized decoder instance. | ||
568 | * \assert | ||
569 | * \code decoder != NULL \endcode | ||
570 | * \retval FLAC__FileDecoderState | ||
571 | * \c FLAC__FILE_DECODER_OK if initialization was successful; see | ||
572 | * FLAC__FileDecoderState for the meanings of other return values. | ||
573 | */ | ||
574 | FLAC_API FLAC__FileDecoderState FLAC__file_decoder_init(FLAC__FileDecoder *decoder); | ||
575 | |||
576 | /** Finish the decoding process. | ||
577 | * Flushes the decoding buffer, releases resources, resets the decoder | ||
578 | * settings to their defaults, and returns the decoder state to | ||
579 | * FLAC__FILE_DECODER_UNINITIALIZED. | ||
580 | * | ||
581 | * In the event of a prematurely-terminated decode, it is not strictly | ||
582 | * necessary to call this immediately before FLAC__file_decoder_delete() | ||
583 | * but it is good practice to match every FLAC__file_decoder_init() with | ||
584 | * a FLAC__file_decoder_finish(). | ||
585 | * | ||
586 | * \param decoder An uninitialized decoder instance. | ||
587 | * \assert | ||
588 | * \code decoder != NULL \endcode | ||
589 | * \retval FLAC__bool | ||
590 | * \c false if MD5 checking is on AND a STREAMINFO block was available | ||
591 | * AND the MD5 signature in the STREAMINFO block was non-zero AND the | ||
592 | * signature does not match the one computed by the decoder; else | ||
593 | * \c true. | ||
594 | */ | ||
595 | FLAC_API FLAC__bool FLAC__file_decoder_finish(FLAC__FileDecoder *decoder); | ||
596 | |||
597 | /** This is inherited from FLAC__SeekableStreamDecoder; see | ||
598 | * FLAC__seekable_stream_decoder_process_single(). | ||
599 | * | ||
600 | * \param decoder A decoder instance. | ||
601 | * \assert | ||
602 | * \code decoder != NULL \endcode | ||
603 | * \retval FLAC__bool | ||
604 | * See above. | ||
605 | */ | ||
606 | FLAC_API FLAC__bool FLAC__file_decoder_process_single(FLAC__FileDecoder *decoder); | ||
607 | |||
608 | /** This is inherited from FLAC__SeekableStreamDecoder; see | ||
609 | * FLAC__seekable_stream_decoder_process_until_end_of_metadata(). | ||
610 | * | ||
611 | * \param decoder A decoder instance. | ||
612 | * \assert | ||
613 | * \code decoder != NULL \endcode | ||
614 | * \retval FLAC__bool | ||
615 | * See above. | ||
616 | */ | ||
617 | FLAC_API FLAC__bool FLAC__file_decoder_process_until_end_of_metadata(FLAC__FileDecoder *decoder); | ||
618 | |||
619 | /** This is inherited from FLAC__SeekableStreamDecoder; see | ||
620 | * FLAC__seekable_stream_decoder_process_until_end_of_stream(). | ||
621 | * | ||
622 | * \param decoder A decoder instance. | ||
623 | * \assert | ||
624 | * \code decoder != NULL \endcode | ||
625 | * \retval FLAC__bool | ||
626 | * See above. | ||
627 | */ | ||
628 | FLAC_API FLAC__bool FLAC__file_decoder_process_until_end_of_file(FLAC__FileDecoder *decoder); | ||
629 | |||
630 | /** This is inherited from FLAC__SeekableStreamDecoder; see | ||
631 | * FLAC__seekable_stream_decoder_skip_single_frame(). | ||
632 | * | ||
633 | * \param decoder A decoder instance. | ||
634 | * \assert | ||
635 | * \code decoder != NULL \endcode | ||
636 | * \retval FLAC__bool | ||
637 | * See above. | ||
638 | */ | ||
639 | FLAC_API FLAC__bool FLAC__file_decoder_skip_single_frame(FLAC__FileDecoder *decoder); | ||
640 | |||
641 | /** Flush the input and seek to an absolute sample. | ||
642 | * This is inherited from FLAC__SeekableStreamDecoder; see | ||
643 | * FLAC__seekable_stream_decoder_seek_absolute(). | ||
644 | * | ||
645 | * \param decoder A decoder instance. | ||
646 | * \param sample The target sample number to seek to. | ||
647 | * \assert | ||
648 | * \code decoder != NULL \endcode | ||
649 | * \retval FLAC__bool | ||
650 | * \c true if successful, else \c false. | ||
651 | */ | ||
652 | FLAC_API FLAC__bool FLAC__file_decoder_seek_absolute(FLAC__FileDecoder *decoder, FLAC__uint64 sample); | ||
653 | |||
654 | /* \} */ | ||
655 | |||
656 | #ifdef __cplusplus | ||
657 | } | ||
658 | #endif | ||
659 | |||
660 | #endif | ||
diff --git a/apps/codecs/libFLAC/include/FLAC/file_encoder.h b/apps/codecs/libFLAC/include/FLAC/file_encoder.h new file mode 100644 index 0000000000..fbbfadb303 --- /dev/null +++ b/apps/codecs/libFLAC/include/FLAC/file_encoder.h | |||
@@ -0,0 +1,871 @@ | |||
1 | /* libFLAC - Free Lossless Audio Codec library | ||
2 | * Copyright (C) 2002,2003,2004,2005 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__FILE_ENCODER_H | ||
33 | #define FLAC__FILE_ENCODER_H | ||
34 | |||
35 | #include "export.h" | ||
36 | #include "seekable_stream_encoder.h" | ||
37 | |||
38 | #ifdef __cplusplus | ||
39 | extern "C" { | ||
40 | #endif | ||
41 | |||
42 | |||
43 | /** \file include/FLAC/file_encoder.h | ||
44 | * | ||
45 | * \brief | ||
46 | * This module contains the functions which implement the file | ||
47 | * encoder. | ||
48 | * | ||
49 | * See the detailed documentation in the | ||
50 | * \link flac_file_encoder file encoder \endlink module. | ||
51 | */ | ||
52 | |||
53 | /** \defgroup flac_file_encoder FLAC/file_encoder.h: file encoder interface | ||
54 | * \ingroup flac_encoder | ||
55 | * | ||
56 | * \brief | ||
57 | * This module contains the functions which implement the file | ||
58 | * encoder. | ||
59 | * | ||
60 | * The basic usage of this encoder is as follows: | ||
61 | * - The program creates an instance of an encoder using | ||
62 | * FLAC__file_encoder_new(). | ||
63 | * - The program overrides the default settings using | ||
64 | * FLAC__file_encoder_set_*() functions. | ||
65 | * - The program initializes the instance to validate the settings and | ||
66 | * prepare for encoding using FLAC__file_encoder_init(). | ||
67 | * - The program calls FLAC__file_encoder_process() or | ||
68 | * FLAC__file_encoder_process_interleaved() to encode data, which | ||
69 | * subsequently writes data to the output file. | ||
70 | * - The program finishes the encoding with FLAC__file_encoder_finish(), | ||
71 | * which causes the encoder to encode any data still in its input pipe, | ||
72 | * rewind and write the STREAMINFO metadata to file, and finally reset | ||
73 | * the encoder to the uninitialized state. | ||
74 | * - The instance may be used again or deleted with | ||
75 | * FLAC__file_encoder_delete(). | ||
76 | * | ||
77 | * The file encoder is a wrapper around the | ||
78 | * \link flac_seekable_stream_encoder seekable stream encoder \endlink which supplies all | ||
79 | * callbacks internally; the user need specify only the filename. | ||
80 | * | ||
81 | * Make sure to read the detailed description of the | ||
82 | * \link flac_seekable_stream_encoder seekable stream encoder module \endlink since the | ||
83 | * \link flac_stream_encoder stream encoder module \endlink since the | ||
84 | * file encoder inherits much of its behavior from them. | ||
85 | * | ||
86 | * \note | ||
87 | * The "set" functions may only be called when the encoder is in the | ||
88 | * state FLAC__FILE_ENCODER_UNINITIALIZED, i.e. after | ||
89 | * FLAC__file_encoder_new() or FLAC__file_encoder_finish(), but | ||
90 | * before FLAC__file_encoder_init(). If this is the case they will | ||
91 | * return \c true, otherwise \c false. | ||
92 | * | ||
93 | * \note | ||
94 | * FLAC__file_encoder_finish() resets all settings to the constructor | ||
95 | * defaults. | ||
96 | * | ||
97 | * \{ | ||
98 | */ | ||
99 | |||
100 | |||
101 | /** State values for a FLAC__FileEncoder | ||
102 | * | ||
103 | * The encoder's state can be obtained by calling FLAC__file_encoder_get_state(). | ||
104 | */ | ||
105 | typedef enum { | ||
106 | |||
107 | FLAC__FILE_ENCODER_OK = 0, | ||
108 | /**< The encoder is in the normal OK state. */ | ||
109 | |||
110 | FLAC__FILE_ENCODER_NO_FILENAME, | ||
111 | /**< FLAC__file_encoder_init() was called without first calling | ||
112 | * FLAC__file_encoder_set_filename(). | ||
113 | */ | ||
114 | |||
115 | FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR, | ||
116 | /**< An error occurred in the underlying seekable stream encoder; | ||
117 | * check FLAC__file_encoder_get_seekable_stream_encoder_state(). | ||
118 | */ | ||
119 | |||
120 | FLAC__FILE_ENCODER_FATAL_ERROR_WHILE_WRITING, | ||
121 | /**< A fatal error occurred while writing to the encoded file. */ | ||
122 | |||
123 | FLAC__FILE_ENCODER_ERROR_OPENING_FILE, | ||
124 | /**< An error occurred opening the output file for writing. */ | ||
125 | |||
126 | FLAC__FILE_ENCODER_MEMORY_ALLOCATION_ERROR, | ||
127 | /**< Memory allocation failed. */ | ||
128 | |||
129 | FLAC__FILE_ENCODER_ALREADY_INITIALIZED, | ||
130 | /**< FLAC__file_encoder_init() was called when the encoder was | ||
131 | * already initialized, usually because | ||
132 | * FLAC__file_encoder_finish() was not called. | ||
133 | */ | ||
134 | |||
135 | FLAC__FILE_ENCODER_UNINITIALIZED | ||
136 | /**< The encoder is in the uninitialized state. */ | ||
137 | |||
138 | } FLAC__FileEncoderState; | ||
139 | |||
140 | /** Maps a FLAC__FileEncoderState to a C string. | ||
141 | * | ||
142 | * Using a FLAC__FileEncoderState as the index to this array | ||
143 | * will give the string equivalent. The contents should not be modified. | ||
144 | */ | ||
145 | extern FLAC_API const char * const FLAC__FileEncoderStateString[]; | ||
146 | |||
147 | |||
148 | /*********************************************************************** | ||
149 | * | ||
150 | * class FLAC__FileEncoder | ||
151 | * | ||
152 | ***********************************************************************/ | ||
153 | |||
154 | struct FLAC__FileEncoderProtected; | ||
155 | struct FLAC__FileEncoderPrivate; | ||
156 | /** The opaque structure definition for the file encoder type. | ||
157 | * See the \link flac_file_encoder file encoder module \endlink | ||
158 | * for a detailed description. | ||
159 | */ | ||
160 | typedef struct { | ||
161 | struct FLAC__FileEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */ | ||
162 | struct FLAC__FileEncoderPrivate *private_; /* avoid the C++ keyword 'private' */ | ||
163 | } FLAC__FileEncoder; | ||
164 | |||
165 | /** Signature for the progress callback. | ||
166 | * See FLAC__file_encoder_set_progress_callback() for more info. | ||
167 | * | ||
168 | * \param encoder The encoder instance calling the callback. | ||
169 | * \param bytes_written Bytes written so far. | ||
170 | * \param samples_written Samples written so far. | ||
171 | * \param frames_written Frames written so far. | ||
172 | * \param total_frames_estimate The estimate of the total number of | ||
173 | * frames to be written. | ||
174 | * \param client_data The callee's client data set through | ||
175 | * FLAC__file_encoder_set_client_data(). | ||
176 | */ | ||
177 | typedef void (*FLAC__FileEncoderProgressCallback)(const FLAC__FileEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate, void *client_data); | ||
178 | |||
179 | |||
180 | /*********************************************************************** | ||
181 | * | ||
182 | * Class constructor/destructor | ||
183 | * | ||
184 | ***********************************************************************/ | ||
185 | |||
186 | /** Create a new file encoder instance. The instance is created with | ||
187 | * default settings; see the individual FLAC__file_encoder_set_*() | ||
188 | * functions for each setting's default. | ||
189 | * | ||
190 | * \retval FLAC__FileEncoder* | ||
191 | * \c NULL if there was an error allocating memory, else the new instance. | ||
192 | */ | ||
193 | FLAC_API FLAC__FileEncoder *FLAC__file_encoder_new(); | ||
194 | |||
195 | /** Free an encoder instance. Deletes the object pointed to by \a encoder. | ||
196 | * | ||
197 | * \param encoder A pointer to an existing encoder. | ||
198 | * \assert | ||
199 | * \code encoder != NULL \endcode | ||
200 | */ | ||
201 | FLAC_API void FLAC__file_encoder_delete(FLAC__FileEncoder *encoder); | ||
202 | |||
203 | /*********************************************************************** | ||
204 | * | ||
205 | * Public class method prototypes | ||
206 | * | ||
207 | ***********************************************************************/ | ||
208 | |||
209 | /** This is inherited from FLAC__SeekableStreamEncoder; see | ||
210 | * FLAC__seekable_stream_encoder_set_verify(). | ||
211 | * | ||
212 | * \default \c true | ||
213 | * \param encoder An encoder instance to set. | ||
214 | * \param value See above. | ||
215 | * \assert | ||
216 | * \code encoder != NULL \endcode | ||
217 | * \retval FLAC__bool | ||
218 | * \c false if the encoder is already initialized, else \c true. | ||
219 | */ | ||
220 | FLAC_API FLAC__bool FLAC__file_encoder_set_verify(FLAC__FileEncoder *encoder, FLAC__bool value); | ||
221 | |||
222 | /** This is inherited from FLAC__SeekableStreamEncoder; see | ||
223 | * FLAC__seekable_stream_encoder_set_streamable_subset(). | ||
224 | * | ||
225 | * \default \c true | ||
226 | * \param encoder An encoder instance to set. | ||
227 | * \param value See above. | ||
228 | * \assert | ||
229 | * \code encoder != NULL \endcode | ||
230 | * \retval FLAC__bool | ||
231 | * \c false if the encoder is already initialized, else \c true. | ||
232 | */ | ||
233 | FLAC_API FLAC__bool FLAC__file_encoder_set_streamable_subset(FLAC__FileEncoder *encoder, FLAC__bool value); | ||
234 | |||
235 | /** This is inherited from FLAC__SeekableStreamEncoder; see | ||
236 | * FLAC__seekable_stream_encoder_set_do_mid_side_stereo(). | ||
237 | * | ||
238 | * \default \c false | ||
239 | * \param encoder An encoder instance to set. | ||
240 | * \param value See above. | ||
241 | * \assert | ||
242 | * \code encoder != NULL \endcode | ||
243 | * \retval FLAC__bool | ||
244 | * \c false if the encoder is already initialized, else \c true. | ||
245 | */ | ||
246 | FLAC_API FLAC__bool FLAC__file_encoder_set_do_mid_side_stereo(FLAC__FileEncoder *encoder, FLAC__bool value); | ||
247 | |||
248 | /** This is inherited from FLAC__SeekableStreamEncoder; see | ||
249 | * FLAC__seekable_stream_encoder_set_loose_mid_side_stereo(). | ||
250 | * | ||
251 | * \default \c false | ||
252 | * \param encoder An encoder instance to set. | ||
253 | * \param value See above. | ||
254 | * \assert | ||
255 | * \code encoder != NULL \endcode | ||
256 | * \retval FLAC__bool | ||
257 | * \c false if the encoder is already initialized, else \c true. | ||
258 | */ | ||
259 | FLAC_API FLAC__bool FLAC__file_encoder_set_loose_mid_side_stereo(FLAC__FileEncoder *encoder, FLAC__bool value); | ||
260 | |||
261 | /** This is inherited from FLAC__SeekableStreamEncoder; see | ||
262 | * FLAC__seekable_stream_encoder_set_channels(). | ||
263 | * | ||
264 | * \default \c 2 | ||
265 | * \param encoder An encoder instance to set. | ||
266 | * \param value See above. | ||
267 | * \assert | ||
268 | * \code encoder != NULL \endcode | ||
269 | * \retval FLAC__bool | ||
270 | * \c false if the encoder is already initialized, else \c true. | ||
271 | */ | ||
272 | FLAC_API FLAC__bool FLAC__file_encoder_set_channels(FLAC__FileEncoder *encoder, unsigned value); | ||
273 | |||
274 | /** This is inherited from FLAC__SeekableStreamEncoder; see | ||
275 | * FLAC__seekable_stream_encoder_set_bits_per_sample(). | ||
276 | * | ||
277 | * \warning | ||
278 | * Do not feed the encoder data that is wider than the value you | ||
279 | * set here or you will generate an invalid stream. | ||
280 | * | ||
281 | * \default \c 16 | ||
282 | * \param encoder An encoder instance to set. | ||
283 | * \param value See above. | ||
284 | * \assert | ||
285 | * \code encoder != NULL \endcode | ||
286 | * \retval FLAC__bool | ||
287 | * \c false if the encoder is already initialized, else \c true. | ||
288 | */ | ||
289 | FLAC_API FLAC__bool FLAC__file_encoder_set_bits_per_sample(FLAC__FileEncoder *encoder, unsigned value); | ||
290 | |||
291 | /** This is inherited from FLAC__SeekableStreamEncoder; see | ||
292 | * FLAC__seekable_stream_encoder_set_sample_rate(). | ||
293 | * | ||
294 | * \default \c 44100 | ||
295 | * \param encoder An encoder instance to set. | ||
296 | * \param value See above. | ||
297 | * \assert | ||
298 | * \code encoder != NULL \endcode | ||
299 | * \retval FLAC__bool | ||
300 | * \c false if the encoder is already initialized, else \c true. | ||
301 | */ | ||
302 | FLAC_API FLAC__bool FLAC__file_encoder_set_sample_rate(FLAC__FileEncoder *encoder, unsigned value); | ||
303 | |||
304 | /** This is inherited from FLAC__SeekableStreamEncoder; see | ||
305 | * FLAC__seekable_stream_encoder_set_blocksize(). | ||
306 | * | ||
307 | * \default \c 1152 | ||
308 | * \param encoder An encoder instance to set. | ||
309 | * \param value See above. | ||
310 | * \assert | ||
311 | * \code encoder != NULL \endcode | ||
312 | * \retval FLAC__bool | ||
313 | * \c false if the encoder is already initialized, else \c true. | ||
314 | */ | ||
315 | FLAC_API FLAC__bool FLAC__file_encoder_set_blocksize(FLAC__FileEncoder *encoder, unsigned value); | ||
316 | |||
317 | /** This is inherited from FLAC__SeekableStreamEncoder; see | ||
318 | * FLAC__seekable_stream_encoder_set_max_lpc_order(). | ||
319 | * | ||
320 | * \default \c 0 | ||
321 | * \param encoder An encoder instance to set. | ||
322 | * \param value See above. | ||
323 | * \assert | ||
324 | * \code encoder != NULL \endcode | ||
325 | * \retval FLAC__bool | ||
326 | * \c false if the encoder is already initialized, else \c true. | ||
327 | */ | ||
328 | FLAC_API FLAC__bool FLAC__file_encoder_set_max_lpc_order(FLAC__FileEncoder *encoder, unsigned value); | ||
329 | |||
330 | /** This is inherited from FLAC__SeekableStreamEncoder; see | ||
331 | * FLAC__seekable_stream_encoder_set_qlp_coeff_precision(). | ||
332 | * | ||
333 | * \note | ||
334 | * In the current implementation, qlp_coeff_precision + bits_per_sample must | ||
335 | * be less than 32. | ||
336 | * | ||
337 | * \default \c 0 | ||
338 | * \param encoder An encoder instance to set. | ||
339 | * \param value See above. | ||
340 | * \assert | ||
341 | * \code encoder != NULL \endcode | ||
342 | * \retval FLAC__bool | ||
343 | * \c false if the encoder is already initialized, else \c true. | ||
344 | */ | ||
345 | FLAC_API FLAC__bool FLAC__file_encoder_set_qlp_coeff_precision(FLAC__FileEncoder *encoder, unsigned value); | ||
346 | |||
347 | /** This is inherited from FLAC__SeekableStreamEncoder; see | ||
348 | * FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search(). | ||
349 | * | ||
350 | * \default \c false | ||
351 | * \param encoder An encoder instance to set. | ||
352 | * \param value See above. | ||
353 | * \assert | ||
354 | * \code encoder != NULL \endcode | ||
355 | * \retval FLAC__bool | ||
356 | * \c false if the encoder is already initialized, else \c true. | ||
357 | */ | ||
358 | FLAC_API FLAC__bool FLAC__file_encoder_set_do_qlp_coeff_prec_search(FLAC__FileEncoder *encoder, FLAC__bool value); | ||
359 | |||
360 | /** This is inherited from FLAC__SeekableStreamEncoder; see | ||
361 | * FLAC__seekable_stream_encoder_set_do_escape_coding(). | ||
362 | * | ||
363 | * \default \c false | ||
364 | * \param encoder An encoder instance to set. | ||
365 | * \param value See above. | ||
366 | * \assert | ||
367 | * \code encoder != NULL \endcode | ||
368 | * \retval FLAC__bool | ||
369 | * \c false if the encoder is already initialized, else \c true. | ||
370 | */ | ||
371 | FLAC_API FLAC__bool FLAC__file_encoder_set_do_escape_coding(FLAC__FileEncoder *encoder, FLAC__bool value); | ||
372 | |||
373 | /** This is inherited from FLAC__SeekableStreamEncoder; see | ||
374 | * FLAC__seekable_stream_encoder_set_do_exhaustive_model_search(). | ||
375 | * | ||
376 | * \default \c false | ||
377 | * \param encoder An encoder instance to set. | ||
378 | * \param value See above. | ||
379 | * \assert | ||
380 | * \code encoder != NULL \endcode | ||
381 | * \retval FLAC__bool | ||
382 | * \c false if the encoder is already initialized, else \c true. | ||
383 | */ | ||
384 | FLAC_API FLAC__bool FLAC__file_encoder_set_do_exhaustive_model_search(FLAC__FileEncoder *encoder, FLAC__bool value); | ||
385 | |||
386 | /** This is inherited from FLAC__SeekableStreamEncoder; see | ||
387 | * FLAC__seekable_stream_encoder_set_min_residual_partition_order(). | ||
388 | * | ||
389 | * \default \c 0 | ||
390 | * \param encoder An encoder instance to set. | ||
391 | * \param value See above. | ||
392 | * \assert | ||
393 | * \code encoder != NULL \endcode | ||
394 | * \retval FLAC__bool | ||
395 | * \c false if the encoder is already initialized, else \c true. | ||
396 | */ | ||
397 | FLAC_API FLAC__bool FLAC__file_encoder_set_min_residual_partition_order(FLAC__FileEncoder *encoder, unsigned value); | ||
398 | |||
399 | /** This is inherited from FLAC__SeekableStreamEncoder; see | ||
400 | * FLAC__seekable_stream_encoder_set_max_residual_partition_order(). | ||
401 | * | ||
402 | * \default \c 0 | ||
403 | * \param encoder An encoder instance to set. | ||
404 | * \param value See above. | ||
405 | * \assert | ||
406 | * \code encoder != NULL \endcode | ||
407 | * \retval FLAC__bool | ||
408 | * \c false if the encoder is already initialized, else \c true. | ||
409 | */ | ||
410 | FLAC_API FLAC__bool FLAC__file_encoder_set_max_residual_partition_order(FLAC__FileEncoder *encoder, unsigned value); | ||
411 | |||
412 | /** This is inherited from FLAC__SeekableStreamEncoder; see | ||
413 | * FLAC__seekable_stream_encoder_set_rice_parameter_search_dist(). | ||
414 | * | ||
415 | * \default \c 0 | ||
416 | * \param encoder An encoder instance to set. | ||
417 | * \param value See above. | ||
418 | * \assert | ||
419 | * \code encoder != NULL \endcode | ||
420 | * \retval FLAC__bool | ||
421 | * \c false if the encoder is already initialized, else \c true. | ||
422 | */ | ||
423 | FLAC_API FLAC__bool FLAC__file_encoder_set_rice_parameter_search_dist(FLAC__FileEncoder *encoder, unsigned value); | ||
424 | |||
425 | /** This is inherited from FLAC__SeekableStreamEncoder; see | ||
426 | * FLAC__seekable_stream_encoder_set_total_samples_estimate(). | ||
427 | * | ||
428 | * \default \c 0 | ||
429 | * \param encoder An encoder instance to set. | ||
430 | * \param value See above. | ||
431 | * \assert | ||
432 | * \code encoder != NULL \endcode | ||
433 | * \retval FLAC__bool | ||
434 | * \c false if the encoder is already initialized, else \c true. | ||
435 | */ | ||
436 | FLAC_API FLAC__bool FLAC__file_encoder_set_total_samples_estimate(FLAC__FileEncoder *encoder, FLAC__uint64 value); | ||
437 | |||
438 | /** This is inherited from FLAC__SeekableStreamEncoder; see | ||
439 | * FLAC__seekable_stream_encoder_set_metadata(). | ||
440 | * | ||
441 | * \default \c NULL, 0 | ||
442 | * \param encoder An encoder instance to set. | ||
443 | * \param metadata See above. | ||
444 | * \param num_blocks See above. | ||
445 | * \assert | ||
446 | * \code encoder != NULL \endcode | ||
447 | * \retval FLAC__bool | ||
448 | * \c false if the encoder is already initialized, else \c true. | ||
449 | */ | ||
450 | FLAC_API FLAC__bool FLAC__file_encoder_set_metadata(FLAC__FileEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks); | ||
451 | |||
452 | /** Set the output file name encode to. | ||
453 | * | ||
454 | * \note | ||
455 | * The filename is mandatory and must be set before initialization. | ||
456 | * | ||
457 | * \note | ||
458 | * Unlike the FLAC__FileDecoder, the filename does not interpret "-" for | ||
459 | * \c stdout; writing to \c stdout is not relevant in the file encoder. | ||
460 | * | ||
461 | * \default \c NULL | ||
462 | * \param encoder A encoder instance to set. | ||
463 | * \param value The output file name. | ||
464 | * \assert | ||
465 | * \code encoder != NULL \endcode | ||
466 | * \code value != NULL \endcode | ||
467 | * \retval FLAC__bool | ||
468 | * \c false if the encoder is already initialized, or there was a memory | ||
469 | * allocation error, else \c true. | ||
470 | */ | ||
471 | FLAC_API FLAC__bool FLAC__file_encoder_set_filename(FLAC__FileEncoder *encoder, const char *value); | ||
472 | |||
473 | /** Set the progress callback. | ||
474 | * The supplied function will be called when the encoder has finished | ||
475 | * writing a frame. The \c total_frames_estimate argument to the callback | ||
476 | * will be based on the value from | ||
477 | * FLAC__file_encoder_set_total_samples_estimate(). | ||
478 | * | ||
479 | * \note | ||
480 | * Unlike most other callbacks, the progress callback is \b not mandatory | ||
481 | * and need not be set before initialization. | ||
482 | * | ||
483 | * \default \c NULL | ||
484 | * \param encoder An encoder instance to set. | ||
485 | * \param value See above. | ||
486 | * \assert | ||
487 | * \code encoder != NULL \endcode | ||
488 | * \code value != NULL \endcode | ||
489 | * \retval FLAC__bool | ||
490 | * \c false if the encoder is already initialized, else \c true. | ||
491 | */ | ||
492 | FLAC_API FLAC__bool FLAC__file_encoder_set_progress_callback(FLAC__FileEncoder *encoder, FLAC__FileEncoderProgressCallback value); | ||
493 | |||
494 | /** Set the client data to be passed back to callbacks. | ||
495 | * This value will be supplied to callbacks in their \a client_data | ||
496 | * argument. | ||
497 | * | ||
498 | * \default \c NULL | ||
499 | * \param encoder An encoder instance to set. | ||
500 | * \param value See above. | ||
501 | * \assert | ||
502 | * \code encoder != NULL \endcode | ||
503 | * \retval FLAC__bool | ||
504 | * \c false if the encoder is already initialized, else \c true. | ||
505 | */ | ||
506 | FLAC_API FLAC__bool FLAC__file_encoder_set_client_data(FLAC__FileEncoder *encoder, void *value); | ||
507 | |||
508 | /** Get the current encoder state. | ||
509 | * | ||
510 | * \param encoder An encoder instance to query. | ||
511 | * \assert | ||
512 | * \code encoder != NULL \endcode | ||
513 | * \retval FLAC__FileEncoderState | ||
514 | * The current encoder state. | ||
515 | */ | ||
516 | FLAC_API FLAC__FileEncoderState FLAC__file_encoder_get_state(const FLAC__FileEncoder *encoder); | ||
517 | |||
518 | /** Get the state of the underlying seekable stream encoder. | ||
519 | * Useful when the file encoder state is | ||
520 | * \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR. | ||
521 | * | ||
522 | * \param encoder An encoder instance to query. | ||
523 | * \assert | ||
524 | * \code encoder != NULL \endcode | ||
525 | * \retval FLAC__SeekableStreamEncoderState | ||
526 | * The seekable stream encoder state. | ||
527 | */ | ||
528 | FLAC_API FLAC__SeekableStreamEncoderState FLAC__file_encoder_get_seekable_stream_encoder_state(const FLAC__FileEncoder *encoder); | ||
529 | |||
530 | /** Get the state of the underlying stream encoder. | ||
531 | * Useful when the file encoder state is | ||
532 | * \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR and the seekable stream | ||
533 | * encoder state is \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR. | ||
534 | * | ||
535 | * \param encoder An encoder instance to query. | ||
536 | * \assert | ||
537 | * \code encoder != NULL \endcode | ||
538 | * \retval FLAC__StreamEncoderState | ||
539 | * The seekable stream encoder state. | ||
540 | */ | ||
541 | FLAC_API FLAC__StreamEncoderState FLAC__file_encoder_get_stream_encoder_state(const FLAC__FileEncoder *encoder); | ||
542 | |||
543 | /** Get the state of the underlying stream encoder's verify decoder. | ||
544 | * Useful when the file encoder state is | ||
545 | * \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR and the seekable stream | ||
546 | * encoder state is \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and | ||
547 | * the stream encoder state is \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR. | ||
548 | * | ||
549 | * \param encoder An encoder instance to query. | ||
550 | * \assert | ||
551 | * \code encoder != NULL \endcode | ||
552 | * \retval FLAC__StreamDecoderState | ||
553 | * The stream encoder state. | ||
554 | */ | ||
555 | FLAC_API FLAC__StreamDecoderState FLAC__file_encoder_get_verify_decoder_state(const FLAC__FileEncoder *encoder); | ||
556 | |||
557 | /** Get the current encoder state as a C string. | ||
558 | * This version automatically resolves | ||
559 | * \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR by getting the | ||
560 | * seekable stream encoder's state. | ||
561 | * | ||
562 | * \param encoder A encoder instance to query. | ||
563 | * \assert | ||
564 | * \code encoder != NULL \endcode | ||
565 | * \retval const char * | ||
566 | * The encoder state as a C string. Do not modify the contents. | ||
567 | */ | ||
568 | FLAC_API const char *FLAC__file_encoder_get_resolved_state_string(const FLAC__FileEncoder *encoder); | ||
569 | |||
570 | /** Get relevant values about the nature of a verify decoder error. | ||
571 | * Inherited from FLAC__seekable_stream_encoder_get_verify_decoder_error_stats(). | ||
572 | * Useful when the file encoder state is | ||
573 | * \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR and the seekable stream | ||
574 | * encoder state is | ||
575 | * \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and the | ||
576 | * stream encoder state is | ||
577 | * \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR. | ||
578 | * | ||
579 | * \param encoder An encoder instance to query. | ||
580 | * \param absolute_sample The absolute sample number of the mismatch. | ||
581 | * \param frame_number The number of the frame in which the mismatch occurred. | ||
582 | * \param channel The channel in which the mismatch occurred. | ||
583 | * \param sample The number of the sample (relative to the frame) in | ||
584 | * which the mismatch occurred. | ||
585 | * \param expected The expected value for the sample in question. | ||
586 | * \param got The actual value returned by the decoder. | ||
587 | * \assert | ||
588 | * \code encoder != NULL \endcode | ||
589 | */ | ||
590 | FLAC_API void FLAC__file_encoder_get_verify_decoder_error_stats(const FLAC__FileEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got); | ||
591 | |||
592 | /** Get the "verify" flag. | ||
593 | * This is inherited from FLAC__SeekableStreamEncoder; see | ||
594 | * FLAC__seekable_stream_encoder_get_verify(). | ||
595 | * | ||
596 | * \param encoder An encoder instance to query. | ||
597 | * \assert | ||
598 | * \code encoder != NULL \endcode | ||
599 | * \retval FLAC__bool | ||
600 | * See FLAC__file_encoder_set_verify(). | ||
601 | */ | ||
602 | FLAC_API FLAC__bool FLAC__file_encoder_get_verify(const FLAC__FileEncoder *encoder); | ||
603 | |||
604 | /** Get the "streamable subset" flag. | ||
605 | * This is inherited from FLAC__SeekableStreamEncoder; see | ||
606 | * FLAC__seekable_stream_encoder_get_streamable_subset(). | ||
607 | * | ||
608 | * \param encoder An encoder instance to query. | ||
609 | * \assert | ||
610 | * \code encoder != NULL \endcode | ||
611 | * \retval FLAC__bool | ||
612 | * See FLAC__file_encoder_set_streamable_subset(). | ||
613 | */ | ||
614 | FLAC_API FLAC__bool FLAC__file_encoder_get_streamable_subset(const FLAC__FileEncoder *encoder); | ||
615 | |||
616 | /** Get the "mid/side stereo coding" flag. | ||
617 | * This is inherited from FLAC__SeekableStreamEncoder; see | ||
618 | * FLAC__seekable_stream_encoder_get_do_mid_side_stereo(). | ||
619 | * | ||
620 | * \param encoder An encoder instance to query. | ||
621 | * \assert | ||
622 | * \code encoder != NULL \endcode | ||
623 | * \retval FLAC__bool | ||
624 | * See FLAC__file_encoder_get_do_mid_side_stereo(). | ||
625 | */ | ||
626 | FLAC_API FLAC__bool FLAC__file_encoder_get_do_mid_side_stereo(const FLAC__FileEncoder *encoder); | ||
627 | |||
628 | /** Get the "adaptive mid/side switching" flag. | ||
629 | * This is inherited from FLAC__SeekableStreamEncoder; see | ||
630 | * FLAC__seekable_stream_encoder_get_loose_mid_side_stereo(). | ||
631 | * | ||
632 | * \param encoder An encoder instance to query. | ||
633 | * \assert | ||
634 | * \code encoder != NULL \endcode | ||
635 | * \retval FLAC__bool | ||
636 | * See FLAC__file_encoder_set_loose_mid_side_stereo(). | ||
637 | */ | ||
638 | FLAC_API FLAC__bool FLAC__file_encoder_get_loose_mid_side_stereo(const FLAC__FileEncoder *encoder); | ||
639 | |||
640 | /** Get the number of input channels being processed. | ||
641 | * This is inherited from FLAC__SeekableStreamEncoder; see | ||
642 | * FLAC__seekable_stream_encoder_get_channels(). | ||
643 | * | ||
644 | * \param encoder An encoder instance to query. | ||
645 | * \assert | ||
646 | * \code encoder != NULL \endcode | ||
647 | * \retval unsigned | ||
648 | * See FLAC__file_encoder_set_channels(). | ||
649 | */ | ||
650 | FLAC_API unsigned FLAC__file_encoder_get_channels(const FLAC__FileEncoder *encoder); | ||
651 | |||
652 | /** Get the input sample resolution setting. | ||
653 | * This is inherited from FLAC__SeekableStreamEncoder; see | ||
654 | * FLAC__seekable_stream_encoder_get_bits_per_sample(). | ||
655 | * | ||
656 | * \param encoder An encoder instance to query. | ||
657 | * \assert | ||
658 | * \code encoder != NULL \endcode | ||
659 | * \retval unsigned | ||
660 | * See FLAC__file_encoder_set_bits_per_sample(). | ||
661 | */ | ||
662 | FLAC_API unsigned FLAC__file_encoder_get_bits_per_sample(const FLAC__FileEncoder *encoder); | ||
663 | |||
664 | /** Get the input sample rate setting. | ||
665 | * This is inherited from FLAC__SeekableStreamEncoder; see | ||
666 | * FLAC__seekable_stream_encoder_get_sample_rate(). | ||
667 | * | ||
668 | * \param encoder An encoder instance to query. | ||
669 | * \assert | ||
670 | * \code encoder != NULL \endcode | ||
671 | * \retval unsigned | ||
672 | * See FLAC__file_encoder_set_sample_rate(). | ||
673 | */ | ||
674 | FLAC_API unsigned FLAC__file_encoder_get_sample_rate(const FLAC__FileEncoder *encoder); | ||
675 | |||
676 | /** Get the blocksize setting. | ||
677 | * This is inherited from FLAC__SeekableStreamEncoder; see | ||
678 | * FLAC__seekable_stream_encoder_get_blocksize(). | ||
679 | * | ||
680 | * \param encoder An encoder instance to query. | ||
681 | * \assert | ||
682 | * \code encoder != NULL \endcode | ||
683 | * \retval unsigned | ||
684 | * See FLAC__file_encoder_set_blocksize(). | ||
685 | */ | ||
686 | FLAC_API unsigned FLAC__file_encoder_get_blocksize(const FLAC__FileEncoder *encoder); | ||
687 | |||
688 | /** Get the maximum LPC order setting. | ||
689 | * This is inherited from FLAC__SeekableStreamEncoder; see | ||
690 | * FLAC__seekable_stream_encoder_get_max_lpc_order(). | ||
691 | * | ||
692 | * \param encoder An encoder instance to query. | ||
693 | * \assert | ||
694 | * \code encoder != NULL \endcode | ||
695 | * \retval unsigned | ||
696 | * See FLAC__file_encoder_set_max_lpc_order(). | ||
697 | */ | ||
698 | FLAC_API unsigned FLAC__file_encoder_get_max_lpc_order(const FLAC__FileEncoder *encoder); | ||
699 | |||
700 | /** Get the quantized linear predictor coefficient precision setting. | ||
701 | * This is inherited from FLAC__SeekableStreamEncoder; see | ||
702 | * FLAC__seekable_stream_encoder_get_qlp_coeff_precision(). | ||
703 | * | ||
704 | * \param encoder An encoder instance to query. | ||
705 | * \assert | ||
706 | * \code encoder != NULL \endcode | ||
707 | * \retval unsigned | ||
708 | * See FLAC__file_encoder_set_qlp_coeff_precision(). | ||
709 | */ | ||
710 | FLAC_API unsigned FLAC__file_encoder_get_qlp_coeff_precision(const FLAC__FileEncoder *encoder); | ||
711 | |||
712 | /** Get the qlp coefficient precision search flag. | ||
713 | * This is inherited from FLAC__SeekableStreamEncoder; see | ||
714 | * FLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search(). | ||
715 | * | ||
716 | * \param encoder An encoder instance to query. | ||
717 | * \assert | ||
718 | * \code encoder != NULL \endcode | ||
719 | * \retval FLAC__bool | ||
720 | * See FLAC__file_encoder_set_do_qlp_coeff_prec_search(). | ||
721 | */ | ||
722 | FLAC_API FLAC__bool FLAC__file_encoder_get_do_qlp_coeff_prec_search(const FLAC__FileEncoder *encoder); | ||
723 | |||
724 | /** Get the "escape coding" flag. | ||
725 | * This is inherited from FLAC__SeekableStreamEncoder; see | ||
726 | * FLAC__seekable_stream_encoder_get_do_escape_coding(). | ||
727 | * | ||
728 | * \param encoder An encoder instance to query. | ||
729 | * \assert | ||
730 | * \code encoder != NULL \endcode | ||
731 | * \retval FLAC__bool | ||
732 | * See FLAC__file_encoder_set_do_escape_coding(). | ||
733 | */ | ||
734 | FLAC_API FLAC__bool FLAC__file_encoder_get_do_escape_coding(const FLAC__FileEncoder *encoder); | ||
735 | |||
736 | /** Get the exhaustive model search flag. | ||
737 | * This is inherited from FLAC__SeekableStreamEncoder; see | ||
738 | * FLAC__seekable_stream_encoder_get_do_exhaustive_model_search(). | ||
739 | * | ||
740 | * \param encoder An encoder instance to query. | ||
741 | * \assert | ||
742 | * \code encoder != NULL \endcode | ||
743 | * \retval FLAC__bool | ||
744 | * See FLAC__file_encoder_set_do_exhaustive_model_search(). | ||
745 | */ | ||
746 | FLAC_API FLAC__bool FLAC__file_encoder_get_do_exhaustive_model_search(const FLAC__FileEncoder *encoder); | ||
747 | |||
748 | /** Get the minimum residual partition order setting. | ||
749 | * This is inherited from FLAC__SeekableStreamEncoder; see | ||
750 | * FLAC__seekable_stream_encoder_get_min_residual_partition_order(). | ||
751 | * | ||
752 | * \param encoder An encoder instance to query. | ||
753 | * \assert | ||
754 | * \code encoder != NULL \endcode | ||
755 | * \retval unsigned | ||
756 | * See FLAC__file_encoder_set_min_residual_partition_order(). | ||
757 | */ | ||
758 | FLAC_API unsigned FLAC__file_encoder_get_min_residual_partition_order(const FLAC__FileEncoder *encoder); | ||
759 | |||
760 | /** Get maximum residual partition order setting. | ||
761 | * This is inherited from FLAC__SeekableStreamEncoder; see | ||
762 | * FLAC__seekable_stream_encoder_get_max_residual_partition_order(). | ||
763 | * | ||
764 | * \param encoder An encoder instance to query. | ||
765 | * \assert | ||
766 | * \code encoder != NULL \endcode | ||
767 | * \retval unsigned | ||
768 | * See FLAC__file_encoder_set_max_residual_partition_order(). | ||
769 | */ | ||
770 | FLAC_API unsigned FLAC__file_encoder_get_max_residual_partition_order(const FLAC__FileEncoder *encoder); | ||
771 | |||
772 | /** Get the Rice parameter search distance setting. | ||
773 | * This is inherited from FLAC__SeekableStreamEncoder; see | ||
774 | * FLAC__seekable_stream_encoder_get_rice_parameter_search_dist(). | ||
775 | * | ||
776 | * \param encoder An encoder instance to query. | ||
777 | * \assert | ||
778 | * \code encoder != NULL \endcode | ||
779 | * \retval unsigned | ||
780 | * See FLAC__file_encoder_set_rice_parameter_search_dist(). | ||
781 | */ | ||
782 | FLAC_API unsigned FLAC__file_encoder_get_rice_parameter_search_dist(const FLAC__FileEncoder *encoder); | ||
783 | |||
784 | /** Get the previously set estimate of the total samples to be encoded. | ||
785 | * This is inherited from FLAC__SeekableStreamEncoder; see | ||
786 | * FLAC__seekable_stream_encoder_get_total_samples_estimate(). | ||
787 | * | ||
788 | * \param encoder An encoder instance to query. | ||
789 | * \assert | ||
790 | * \code encoder != NULL \endcode | ||
791 | * \retval FLAC__uint64 | ||
792 | * See FLAC__file_encoder_set_total_samples_estimate(). | ||
793 | */ | ||
794 | FLAC_API FLAC__uint64 FLAC__file_encoder_get_total_samples_estimate(const FLAC__FileEncoder *encoder); | ||
795 | |||
796 | /** Initialize the encoder instance. | ||
797 | * Should be called after FLAC__file_encoder_new() and | ||
798 | * FLAC__file_encoder_set_*() but before FLAC__file_encoder_process() | ||
799 | * or FLAC__file_encoder_process_interleaved(). Will set and return | ||
800 | * the encoder state, which will be FLAC__FILE_ENCODER_OK if | ||
801 | * initialization succeeded. | ||
802 | * | ||
803 | * \param encoder An uninitialized encoder instance. | ||
804 | * \assert | ||
805 | * \code encoder != NULL \endcode | ||
806 | * \retval FLAC__FileEncoderState | ||
807 | * \c FLAC__FILE_ENCODER_OK if initialization was successful; see | ||
808 | * FLAC__FileEncoderState for the meanings of other return values. | ||
809 | */ | ||
810 | FLAC_API FLAC__FileEncoderState FLAC__file_encoder_init(FLAC__FileEncoder *encoder); | ||
811 | |||
812 | /** Finish the encoding process. | ||
813 | * Flushes the encoding buffer, releases resources, resets the encoder | ||
814 | * settings to their defaults, and returns the encoder state to | ||
815 | * FLAC__FILE_ENCODER_UNINITIALIZED. | ||
816 | * | ||
817 | * In the event of a prematurely-terminated encode, it is not strictly | ||
818 | * necessary to call this immediately before FLAC__file_encoder_delete() | ||
819 | * but it is good practice to match every FLAC__file_encoder_init() | ||
820 | * with a FLAC__file_encoder_finish(). | ||
821 | * | ||
822 | * \param encoder An uninitialized encoder instance. | ||
823 | * \assert | ||
824 | * \code encoder != NULL \endcode | ||
825 | */ | ||
826 | FLAC_API void FLAC__file_encoder_finish(FLAC__FileEncoder *encoder); | ||
827 | |||
828 | /** Submit data for encoding. | ||
829 | * This is inherited from FLAC__SeekableStreamEncoder; see | ||
830 | * FLAC__seekable_stream_encoder_process(). | ||
831 | * | ||
832 | * \param encoder An initialized encoder instance in the OK state. | ||
833 | * \param buffer An array of pointers to each channel's signal. | ||
834 | * \param samples The number of samples in one channel. | ||
835 | * \assert | ||
836 | * \code encoder != NULL \endcode | ||
837 | * \code FLAC__file_encoder_get_state(encoder) == FLAC__FILE_ENCODER_OK \endcode | ||
838 | * \retval FLAC__bool | ||
839 | * \c true if successful, else \c false; in this case, check the | ||
840 | * encoder state with FLAC__file_encoder_get_state() to see what | ||
841 | * went wrong. | ||
842 | */ | ||
843 | FLAC_API FLAC__bool FLAC__file_encoder_process(FLAC__FileEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples); | ||
844 | |||
845 | /** Submit data for encoding. | ||
846 | * This is inherited from FLAC__SeekableStreamEncoder; see | ||
847 | * FLAC__seekable_stream_encoder_process_interleaved(). | ||
848 | * | ||
849 | * \param encoder An initialized encoder instance in the OK state. | ||
850 | * \param buffer An array of channel-interleaved data (see above). | ||
851 | * \param samples The number of samples in one channel, the same as for | ||
852 | * FLAC__file_encoder_process(). For example, if | ||
853 | * encoding two channels, \c 1000 \a samples corresponds | ||
854 | * to a \a buffer of 2000 values. | ||
855 | * \assert | ||
856 | * \code encoder != NULL \endcode | ||
857 | * \code FLAC__file_encoder_get_state(encoder) == FLAC__FILE_ENCODER_OK \endcode | ||
858 | * \retval FLAC__bool | ||
859 | * \c true if successful, else \c false; in this case, check the | ||
860 | * encoder state with FLAC__file_encoder_get_state() to see what | ||
861 | * went wrong. | ||
862 | */ | ||
863 | FLAC_API FLAC__bool FLAC__file_encoder_process_interleaved(FLAC__FileEncoder *encoder, const FLAC__int32 buffer[], unsigned samples); | ||
864 | |||
865 | /* \} */ | ||
866 | |||
867 | #ifdef __cplusplus | ||
868 | } | ||
869 | #endif | ||
870 | |||
871 | #endif | ||
diff --git a/apps/codecs/libFLAC/include/FLAC/format.h b/apps/codecs/libFLAC/include/FLAC/format.h new file mode 100644 index 0000000000..26080cbf72 --- /dev/null +++ b/apps/codecs/libFLAC/include/FLAC/format.h | |||
@@ -0,0 +1,861 @@ | |||
1 | /* libFLAC - Free Lossless Audio Codec library | ||
2 | * Copyright (C) 2000,2001,2002,2003,2004,2005 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__FORMAT_H | ||
33 | #define FLAC__FORMAT_H | ||
34 | |||
35 | #include "export.h" | ||
36 | #include "ordinals.h" | ||
37 | |||
38 | #ifdef __cplusplus | ||
39 | extern "C" { | ||
40 | #endif | ||
41 | |||
42 | /** \file include/FLAC/format.h | ||
43 | * | ||
44 | * \brief | ||
45 | * This module contains structure definitions for the representation | ||
46 | * of FLAC format components in memory. These are the basic | ||
47 | * structures used by the rest of the interfaces. | ||
48 | * | ||
49 | * See the detailed documentation in the | ||
50 | * \link flac_format format \endlink module. | ||
51 | */ | ||
52 | |||
53 | /** \defgroup flac_format FLAC/format.h: format components | ||
54 | * \ingroup flac | ||
55 | * | ||
56 | * \brief | ||
57 | * This module contains structure definitions for the representation | ||
58 | * of FLAC format components in memory. These are the basic | ||
59 | * structures used by the rest of the interfaces. | ||
60 | * | ||
61 | * First, you should be familiar with the | ||
62 | * <A HREF="../format.html">FLAC format</A>. Many of the values here | ||
63 | * follow directly from the specification. As a user of libFLAC, the | ||
64 | * interesting parts really are the structures that describe the frame | ||
65 | * header and metadata blocks. | ||
66 | * | ||
67 | * The format structures here are very primitive, designed to store | ||
68 | * information in an efficient way. Reading information from the | ||
69 | * structures is easy but creating or modifying them directly is | ||
70 | * more complex. For the most part, as a user of a library, editing | ||
71 | * is not necessary; however, for metadata blocks it is, so there are | ||
72 | * convenience functions provided in the \link flac_metadata metadata | ||
73 | * module \endlink to simplify the manipulation of metadata blocks. | ||
74 | * | ||
75 | * \note | ||
76 | * It's not the best convention, but symbols ending in _LEN are in bits | ||
77 | * and _LENGTH are in bytes. _LENGTH symbols are \#defines instead of | ||
78 | * global variables because they are usually used when declaring byte | ||
79 | * arrays and some compilers require compile-time knowledge of array | ||
80 | * sizes when declared on the stack. | ||
81 | * | ||
82 | * \{ | ||
83 | */ | ||
84 | |||
85 | |||
86 | /* | ||
87 | Most of the values described in this file are defined by the FLAC | ||
88 | format specification. There is nothing to tune here. | ||
89 | */ | ||
90 | |||
91 | /** The largest legal metadata type code. */ | ||
92 | #define FLAC__MAX_METADATA_TYPE_CODE (126u) | ||
93 | |||
94 | /** The minimum block size, in samples, permitted by the format. */ | ||
95 | #define FLAC__MIN_BLOCK_SIZE (16u) | ||
96 | |||
97 | /** The maximum block size, in samples, permitted by the format. */ | ||
98 | #define FLAC__MAX_BLOCK_SIZE (65535u) | ||
99 | |||
100 | /** The maximum number of channels permitted by the format. */ | ||
101 | #define FLAC__MAX_CHANNELS (8u) | ||
102 | |||
103 | /** The minimum sample resolution permitted by the format. */ | ||
104 | #define FLAC__MIN_BITS_PER_SAMPLE (4u) | ||
105 | |||
106 | /** The maximum sample resolution permitted by the format. */ | ||
107 | #define FLAC__MAX_BITS_PER_SAMPLE (32u) | ||
108 | |||
109 | /** The maximum sample resolution permitted by libFLAC. | ||
110 | * | ||
111 | * \warning | ||
112 | * FLAC__MAX_BITS_PER_SAMPLE is the limit of the FLAC format. However, | ||
113 | * the reference encoder/decoder is currently limited to 24 bits because | ||
114 | * of prevalent 32-bit math, so make sure and use this value when | ||
115 | * appropriate. | ||
116 | */ | ||
117 | #define FLAC__REFERENCE_CODEC_MAX_BITS_PER_SAMPLE (24u) | ||
118 | |||
119 | /** The maximum sample rate permitted by the format. The value is | ||
120 | * ((2 ^ 16) - 1) * 10; see <A HREF="../format.html">FLAC format</A> | ||
121 | * as to why. | ||
122 | */ | ||
123 | #define FLAC__MAX_SAMPLE_RATE (655350u) | ||
124 | |||
125 | /** The maximum LPC order permitted by the format. */ | ||
126 | #define FLAC__MAX_LPC_ORDER (32u) | ||
127 | |||
128 | /** The minimum quantized linear predictor coefficient precision | ||
129 | * permitted by the format. | ||
130 | */ | ||
131 | #define FLAC__MIN_QLP_COEFF_PRECISION (5u) | ||
132 | |||
133 | /** The maximum quantized linear predictor coefficient precision | ||
134 | * permitted by the format. | ||
135 | */ | ||
136 | #define FLAC__MAX_QLP_COEFF_PRECISION (15u) | ||
137 | |||
138 | /** The maximum order of the fixed predictors permitted by the format. */ | ||
139 | #define FLAC__MAX_FIXED_ORDER (4u) | ||
140 | |||
141 | /** The maximum Rice partition order permitted by the format. */ | ||
142 | #define FLAC__MAX_RICE_PARTITION_ORDER (15u) | ||
143 | |||
144 | /** The maximum Rice partition order permitted by the FLAC Subset. */ | ||
145 | #define FLAC__SUBSET_MAX_RICE_PARTITION_ORDER (8u) | ||
146 | |||
147 | /** The version string of the release, stamped onto the libraries and binaries. | ||
148 | * | ||
149 | * \note | ||
150 | * This does not correspond to the shared library version number, which | ||
151 | * is used to determine binary compatibility. | ||
152 | */ | ||
153 | extern FLAC_API const char *FLAC__VERSION_STRING; | ||
154 | |||
155 | /** The vendor string inserted by the encoder into the VORBIS_COMMENT block. | ||
156 | * This is a nulL-terminated ASCII string; when inserted into the | ||
157 | * VORBIS_COMMENT the trailing null is stripped. | ||
158 | */ | ||
159 | extern FLAC_API const char *FLAC__VENDOR_STRING; | ||
160 | |||
161 | /** The byte string representation of the beginning of a FLAC stream. */ | ||
162 | extern FLAC_API const FLAC__byte FLAC__STREAM_SYNC_STRING[4]; /* = "fLaC" */ | ||
163 | |||
164 | /** The 32-bit integer big-endian representation of the beginning of | ||
165 | * a FLAC stream. | ||
166 | */ | ||
167 | extern FLAC_API const unsigned FLAC__STREAM_SYNC; /* = 0x664C6143 */ | ||
168 | |||
169 | /** The length of the FLAC signature in bits. */ | ||
170 | extern FLAC_API const unsigned FLAC__STREAM_SYNC_LEN; /* = 32 bits */ | ||
171 | |||
172 | /** The length of the FLAC signature in bytes. */ | ||
173 | #define FLAC__STREAM_SYNC_LENGTH (4u) | ||
174 | |||
175 | |||
176 | /***************************************************************************** | ||
177 | * | ||
178 | * Subframe structures | ||
179 | * | ||
180 | *****************************************************************************/ | ||
181 | |||
182 | /*****************************************************************************/ | ||
183 | |||
184 | /** An enumeration of the available entropy coding methods. */ | ||
185 | typedef enum { | ||
186 | FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE = 0 | ||
187 | /**< Residual is coded by partitioning into contexts, each with it's own | ||
188 | * Rice parameter. */ | ||
189 | } FLAC__EntropyCodingMethodType; | ||
190 | |||
191 | /** Maps a FLAC__EntropyCodingMethodType to a C string. | ||
192 | * | ||
193 | * Using a FLAC__EntropyCodingMethodType as the index to this array will | ||
194 | * give the string equivalent. The contents should not be modified. | ||
195 | */ | ||
196 | extern FLAC_API const char * const FLAC__EntropyCodingMethodTypeString[]; | ||
197 | |||
198 | |||
199 | /** Contents of a Rice partitioned residual | ||
200 | */ | ||
201 | typedef struct { | ||
202 | |||
203 | unsigned *parameters; | ||
204 | /**< The Rice parameters for each context. */ | ||
205 | |||
206 | unsigned *raw_bits; | ||
207 | /**< Widths for escape-coded partitions. */ | ||
208 | |||
209 | unsigned capacity_by_order; | ||
210 | /**< The capacity of the \a parameters and \a raw_bits arrays | ||
211 | * specified as an order, i.e. the number of array elements | ||
212 | * allocated is 2 ^ \a capacity_by_order. | ||
213 | */ | ||
214 | } FLAC__EntropyCodingMethod_PartitionedRiceContents; | ||
215 | |||
216 | /** Header for a Rice partitioned residual. (c.f. <A HREF="../format.html#partitioned_rice">format specification</A>) | ||
217 | */ | ||
218 | typedef struct { | ||
219 | |||
220 | unsigned order; | ||
221 | /**< The partition order, i.e. # of contexts = 2 ^ \a order. */ | ||
222 | |||
223 | const FLAC__EntropyCodingMethod_PartitionedRiceContents *contents; | ||
224 | /**< The context's Rice parameters and/or raw bits. */ | ||
225 | |||
226 | } FLAC__EntropyCodingMethod_PartitionedRice; | ||
227 | |||
228 | extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ORDER_LEN; /**< == 4 (bits) */ | ||
229 | extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_PARAMETER_LEN; /**< == 4 (bits) */ | ||
230 | extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_RAW_LEN; /**< == 5 (bits) */ | ||
231 | |||
232 | extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ESCAPE_PARAMETER; | ||
233 | /**< == (1<<FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_PARAMETER_LEN)-1 */ | ||
234 | |||
235 | /** Header for the entropy coding method. (c.f. <A HREF="../format.html#residual">format specification</A>) | ||
236 | */ | ||
237 | typedef struct { | ||
238 | FLAC__EntropyCodingMethodType type; | ||
239 | union { | ||
240 | FLAC__EntropyCodingMethod_PartitionedRice partitioned_rice; | ||
241 | } data; | ||
242 | } FLAC__EntropyCodingMethod; | ||
243 | |||
244 | extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_TYPE_LEN; /**< == 2 (bits) */ | ||
245 | |||
246 | /*****************************************************************************/ | ||
247 | |||
248 | /** An enumeration of the available subframe types. */ | ||
249 | typedef enum { | ||
250 | FLAC__SUBFRAME_TYPE_CONSTANT = 0, /**< constant signal */ | ||
251 | FLAC__SUBFRAME_TYPE_VERBATIM = 1, /**< uncompressed signal */ | ||
252 | FLAC__SUBFRAME_TYPE_FIXED = 2, /**< fixed polynomial prediction */ | ||
253 | FLAC__SUBFRAME_TYPE_LPC = 3 /**< linear prediction */ | ||
254 | } FLAC__SubframeType; | ||
255 | |||
256 | /** Maps a FLAC__SubframeType to a C string. | ||
257 | * | ||
258 | * Using a FLAC__SubframeType as the index to this array will | ||
259 | * give the string equivalent. The contents should not be modified. | ||
260 | */ | ||
261 | extern FLAC_API const char * const FLAC__SubframeTypeString[]; | ||
262 | |||
263 | |||
264 | /** CONSTANT subframe. (c.f. <A HREF="../format.html#subframe_constant">format specification</A>) | ||
265 | */ | ||
266 | typedef struct { | ||
267 | FLAC__int32 value; /**< The constant signal value. */ | ||
268 | } FLAC__Subframe_Constant; | ||
269 | |||
270 | |||
271 | /** VERBATIM subframe. (c.f. <A HREF="../format.html#subframe_verbatim">format specification</A>) | ||
272 | */ | ||
273 | typedef struct { | ||
274 | const FLAC__int32 *data; /**< A pointer to verbatim signal. */ | ||
275 | } FLAC__Subframe_Verbatim; | ||
276 | |||
277 | |||
278 | /** FIXED subframe. (c.f. <A HREF="../format.html#subframe_fixed">format specification</A>) | ||
279 | */ | ||
280 | typedef struct { | ||
281 | FLAC__EntropyCodingMethod entropy_coding_method; | ||
282 | /**< The residual coding method. */ | ||
283 | |||
284 | unsigned order; | ||
285 | /**< The polynomial order. */ | ||
286 | |||
287 | FLAC__int32 warmup[FLAC__MAX_FIXED_ORDER]; | ||
288 | /**< Warmup samples to prime the predictor, length == order. */ | ||
289 | |||
290 | const FLAC__int32 *residual; | ||
291 | /**< The residual signal, length == (blocksize minus order) samples. */ | ||
292 | } FLAC__Subframe_Fixed; | ||
293 | |||
294 | |||
295 | /** LPC subframe. (c.f. <A HREF="../format.html#subframe_lpc">format specification</A>) | ||
296 | */ | ||
297 | typedef struct { | ||
298 | FLAC__EntropyCodingMethod entropy_coding_method; | ||
299 | /**< The residual coding method. */ | ||
300 | |||
301 | unsigned order; | ||
302 | /**< The FIR order. */ | ||
303 | |||
304 | unsigned qlp_coeff_precision; | ||
305 | /**< Quantized FIR filter coefficient precision in bits. */ | ||
306 | |||
307 | int quantization_level; | ||
308 | /**< The qlp coeff shift needed. */ | ||
309 | |||
310 | FLAC__int32 qlp_coeff[FLAC__MAX_LPC_ORDER]; | ||
311 | /**< FIR filter coefficients. */ | ||
312 | |||
313 | FLAC__int32 warmup[FLAC__MAX_LPC_ORDER]; | ||
314 | /**< Warmup samples to prime the predictor, length == order. */ | ||
315 | |||
316 | const FLAC__int32 *residual; | ||
317 | /**< The residual signal, length == (blocksize minus order) samples. */ | ||
318 | } FLAC__Subframe_LPC; | ||
319 | |||
320 | extern FLAC_API const unsigned FLAC__SUBFRAME_LPC_QLP_COEFF_PRECISION_LEN; /**< == 4 (bits) */ | ||
321 | extern FLAC_API const unsigned FLAC__SUBFRAME_LPC_QLP_SHIFT_LEN; /**< == 5 (bits) */ | ||
322 | |||
323 | |||
324 | /** FLAC subframe structure. (c.f. <A HREF="../format.html#subframe">format specification</A>) | ||
325 | */ | ||
326 | typedef struct { | ||
327 | FLAC__SubframeType type; | ||
328 | union { | ||
329 | FLAC__Subframe_Constant constant; | ||
330 | FLAC__Subframe_Fixed fixed; | ||
331 | FLAC__Subframe_LPC lpc; | ||
332 | FLAC__Subframe_Verbatim verbatim; | ||
333 | } data; | ||
334 | unsigned wasted_bits; | ||
335 | } FLAC__Subframe; | ||
336 | |||
337 | extern FLAC_API const unsigned FLAC__SUBFRAME_ZERO_PAD_LEN; /**< == 1 (bit) */ | ||
338 | extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LEN; /**< == 6 (bits) */ | ||
339 | extern FLAC_API const unsigned FLAC__SUBFRAME_WASTED_BITS_FLAG_LEN; /**< == 1 (bit) */ | ||
340 | |||
341 | extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_CONSTANT_BYTE_ALIGNED_MASK; /* = 0x00 */ | ||
342 | extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_VERBATIM_BYTE_ALIGNED_MASK; /* = 0x02 */ | ||
343 | extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_FIXED_BYTE_ALIGNED_MASK; /* = 0x10 */ | ||
344 | extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LPC_BYTE_ALIGNED_MASK; /* = 0x40 */ | ||
345 | |||
346 | /*****************************************************************************/ | ||
347 | |||
348 | |||
349 | /***************************************************************************** | ||
350 | * | ||
351 | * Frame structures | ||
352 | * | ||
353 | *****************************************************************************/ | ||
354 | |||
355 | /** An enumeration of the available channel assignments. */ | ||
356 | typedef enum { | ||
357 | FLAC__CHANNEL_ASSIGNMENT_INDEPENDENT = 0, /**< independent channels */ | ||
358 | FLAC__CHANNEL_ASSIGNMENT_LEFT_SIDE = 1, /**< left+side stereo */ | ||
359 | FLAC__CHANNEL_ASSIGNMENT_RIGHT_SIDE = 2, /**< right+side stereo */ | ||
360 | FLAC__CHANNEL_ASSIGNMENT_MID_SIDE = 3 /**< mid+side stereo */ | ||
361 | } FLAC__ChannelAssignment; | ||
362 | |||
363 | /** Maps a FLAC__ChannelAssignment to a C string. | ||
364 | * | ||
365 | * Using a FLAC__ChannelAssignment as the index to this array will | ||
366 | * give the string equivalent. The contents should not be modified. | ||
367 | */ | ||
368 | extern FLAC_API const char * const FLAC__ChannelAssignmentString[]; | ||
369 | |||
370 | /** An enumeration of the possible frame numbering methods. */ | ||
371 | typedef enum { | ||
372 | FLAC__FRAME_NUMBER_TYPE_FRAME_NUMBER, /**< number contains the frame number */ | ||
373 | FLAC__FRAME_NUMBER_TYPE_SAMPLE_NUMBER /**< number contains the sample number of first sample in frame */ | ||
374 | } FLAC__FrameNumberType; | ||
375 | |||
376 | /** Maps a FLAC__FrameNumberType to a C string. | ||
377 | * | ||
378 | * Using a FLAC__FrameNumberType as the index to this array will | ||
379 | * give the string equivalent. The contents should not be modified. | ||
380 | */ | ||
381 | extern FLAC_API const char * const FLAC__FrameNumberTypeString[]; | ||
382 | |||
383 | |||
384 | /** FLAC frame header structure. (c.f. <A HREF="../format.html#frame_header">format specification</A>) | ||
385 | */ | ||
386 | typedef struct { | ||
387 | unsigned blocksize; | ||
388 | /**< The number of samples per subframe. */ | ||
389 | |||
390 | unsigned sample_rate; | ||
391 | /**< The sample rate in Hz. */ | ||
392 | |||
393 | unsigned channels; | ||
394 | /**< The number of channels (== number of subframes). */ | ||
395 | |||
396 | FLAC__ChannelAssignment channel_assignment; | ||
397 | /**< The channel assignment for the frame. */ | ||
398 | |||
399 | unsigned bits_per_sample; | ||
400 | /**< The sample resolution. */ | ||
401 | |||
402 | FLAC__FrameNumberType number_type; | ||
403 | /**< The numbering scheme used for the frame. */ | ||
404 | |||
405 | union { | ||
406 | FLAC__uint32 frame_number; | ||
407 | FLAC__uint64 sample_number; | ||
408 | } number; | ||
409 | /**< The frame number or sample number of first sample in frame; | ||
410 | * use the \a number_type value to determine which to use. */ | ||
411 | |||
412 | FLAC__uint8 crc; | ||
413 | /**< CRC-8 (polynomial = x^8 + x^2 + x^1 + x^0, initialized with 0) | ||
414 | * of the raw frame header bytes, meaning everything before the CRC byte | ||
415 | * including the sync code. | ||
416 | */ | ||
417 | } FLAC__FrameHeader; | ||
418 | |||
419 | extern FLAC_API const unsigned FLAC__FRAME_HEADER_SYNC; /**< == 0x3ffe; the frame header sync code */ | ||
420 | extern FLAC_API const unsigned FLAC__FRAME_HEADER_SYNC_LEN; /**< == 14 (bits) */ | ||
421 | extern FLAC_API const unsigned FLAC__FRAME_HEADER_RESERVED_LEN; /**< == 2 (bits) */ | ||
422 | extern FLAC_API const unsigned FLAC__FRAME_HEADER_BLOCK_SIZE_LEN; /**< == 4 (bits) */ | ||
423 | extern FLAC_API const unsigned FLAC__FRAME_HEADER_SAMPLE_RATE_LEN; /**< == 4 (bits) */ | ||
424 | extern FLAC_API const unsigned FLAC__FRAME_HEADER_CHANNEL_ASSIGNMENT_LEN; /**< == 4 (bits) */ | ||
425 | extern FLAC_API const unsigned FLAC__FRAME_HEADER_BITS_PER_SAMPLE_LEN; /**< == 3 (bits) */ | ||
426 | extern FLAC_API const unsigned FLAC__FRAME_HEADER_ZERO_PAD_LEN; /**< == 1 (bit) */ | ||
427 | extern FLAC_API const unsigned FLAC__FRAME_HEADER_CRC_LEN; /**< == 8 (bits) */ | ||
428 | |||
429 | |||
430 | /** FLAC frame footer structure. (c.f. <A HREF="../format.html#frame_footer">format specification</A>) | ||
431 | */ | ||
432 | typedef struct { | ||
433 | FLAC__uint16 crc; | ||
434 | /**< CRC-16 (polynomial = x^16 + x^15 + x^2 + x^0, initialized with | ||
435 | * 0) of the bytes before the crc, back to and including the frame header | ||
436 | * sync code. | ||
437 | */ | ||
438 | } FLAC__FrameFooter; | ||
439 | |||
440 | extern FLAC_API const unsigned FLAC__FRAME_FOOTER_CRC_LEN; /**< == 16 (bits) */ | ||
441 | |||
442 | |||
443 | /** FLAC frame structure. (c.f. <A HREF="../format.html#frame">format specification</A>) | ||
444 | */ | ||
445 | typedef struct { | ||
446 | FLAC__FrameHeader header; | ||
447 | FLAC__Subframe subframes[FLAC__MAX_CHANNELS]; | ||
448 | FLAC__FrameFooter footer; | ||
449 | } FLAC__Frame; | ||
450 | |||
451 | /*****************************************************************************/ | ||
452 | |||
453 | |||
454 | /***************************************************************************** | ||
455 | * | ||
456 | * Meta-data structures | ||
457 | * | ||
458 | *****************************************************************************/ | ||
459 | |||
460 | /** An enumeration of the available metadata block types. */ | ||
461 | typedef enum { | ||
462 | |||
463 | FLAC__METADATA_TYPE_STREAMINFO = 0, | ||
464 | /**< <A HREF="../format.html#metadata_block_streaminfo">STREAMINFO</A> block */ | ||
465 | |||
466 | FLAC__METADATA_TYPE_PADDING = 1, | ||
467 | /**< <A HREF="../format.html#metadata_block_padding">PADDING</A> block */ | ||
468 | |||
469 | FLAC__METADATA_TYPE_APPLICATION = 2, | ||
470 | /**< <A HREF="../format.html#metadata_block_application">APPLICATION</A> block */ | ||
471 | |||
472 | FLAC__METADATA_TYPE_SEEKTABLE = 3, | ||
473 | /**< <A HREF="../format.html#metadata_block_seektable">SEEKTABLE</A> block */ | ||
474 | |||
475 | FLAC__METADATA_TYPE_VORBIS_COMMENT = 4, | ||
476 | /**< <A HREF="../format.html#metadata_block_vorbis_comment">VORBISCOMMENT</A> block */ | ||
477 | |||
478 | FLAC__METADATA_TYPE_CUESHEET = 5, | ||
479 | /**< <A HREF="../format.html#metadata_block_cuesheet">CUESHEET</A> block */ | ||
480 | |||
481 | FLAC__METADATA_TYPE_UNDEFINED = 6 | ||
482 | /**< marker to denote beginning of undefined type range; this number will increase as new metadata types are added */ | ||
483 | |||
484 | } FLAC__MetadataType; | ||
485 | |||
486 | /** Maps a FLAC__MetadataType to a C string. | ||
487 | * | ||
488 | * Using a FLAC__MetadataType as the index to this array will | ||
489 | * give the string equivalent. The contents should not be modified. | ||
490 | */ | ||
491 | extern FLAC_API const char * const FLAC__MetadataTypeString[]; | ||
492 | |||
493 | |||
494 | /** FLAC STREAMINFO structure. (c.f. <A HREF="../format.html#metadata_block_streaminfo">format specification</A>) | ||
495 | */ | ||
496 | typedef struct { | ||
497 | unsigned min_blocksize, max_blocksize; | ||
498 | unsigned min_framesize, max_framesize; | ||
499 | unsigned sample_rate; | ||
500 | unsigned channels; | ||
501 | unsigned bits_per_sample; | ||
502 | FLAC__uint64 total_samples; | ||
503 | FLAC__byte md5sum[16]; | ||
504 | } FLAC__StreamMetadata_StreamInfo; | ||
505 | |||
506 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_BLOCK_SIZE_LEN; /**< == 16 (bits) */ | ||
507 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_BLOCK_SIZE_LEN; /**< == 16 (bits) */ | ||
508 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_FRAME_SIZE_LEN; /**< == 24 (bits) */ | ||
509 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_FRAME_SIZE_LEN; /**< == 24 (bits) */ | ||
510 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_SAMPLE_RATE_LEN; /**< == 20 (bits) */ | ||
511 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_CHANNELS_LEN; /**< == 3 (bits) */ | ||
512 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_BITS_PER_SAMPLE_LEN; /**< == 5 (bits) */ | ||
513 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_TOTAL_SAMPLES_LEN; /**< == 36 (bits) */ | ||
514 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MD5SUM_LEN; /**< == 128 (bits) */ | ||
515 | |||
516 | /** The total stream length of the STREAMINFO block in bytes. */ | ||
517 | #define FLAC__STREAM_METADATA_STREAMINFO_LENGTH (34u) | ||
518 | |||
519 | /** FLAC PADDING structure. (c.f. <A HREF="../format.html#metadata_block_padding">format specification</A>) | ||
520 | */ | ||
521 | typedef struct { | ||
522 | int dummy; | ||
523 | /**< Conceptually this is an empty struct since we don't store the | ||
524 | * padding bytes. Empty structs are not allowed by some C compilers, | ||
525 | * hence the dummy. | ||
526 | */ | ||
527 | } FLAC__StreamMetadata_Padding; | ||
528 | |||
529 | |||
530 | /** FLAC APPLICATION structure. (c.f. <A HREF="../format.html#metadata_block_application">format specification</A>) | ||
531 | */ | ||
532 | typedef struct { | ||
533 | FLAC__byte id[4]; | ||
534 | FLAC__byte *data; | ||
535 | } FLAC__StreamMetadata_Application; | ||
536 | |||
537 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_APPLICATION_ID_LEN; /**< == 32 (bits) */ | ||
538 | |||
539 | /** SeekPoint structure used in SEEKTABLE blocks. (c.f. <A HREF="../format.html#seekpoint">format specification</A>) | ||
540 | */ | ||
541 | typedef struct { | ||
542 | FLAC__uint64 sample_number; | ||
543 | /**< The sample number of the target frame. */ | ||
544 | |||
545 | FLAC__uint64 stream_offset; | ||
546 | /**< The offset, in bytes, of the target frame with respect to | ||
547 | * beginning of the first frame. */ | ||
548 | |||
549 | unsigned frame_samples; | ||
550 | /**< The number of samples in the target frame. */ | ||
551 | } FLAC__StreamMetadata_SeekPoint; | ||
552 | |||
553 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_SAMPLE_NUMBER_LEN; /**< == 64 (bits) */ | ||
554 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_STREAM_OFFSET_LEN; /**< == 64 (bits) */ | ||
555 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_FRAME_SAMPLES_LEN; /**< == 16 (bits) */ | ||
556 | |||
557 | /** The total stream length of a seek point in bytes. */ | ||
558 | #define FLAC__STREAM_METADATA_SEEKPOINT_LENGTH (18u) | ||
559 | |||
560 | /** The value used in the \a sample_number field of | ||
561 | * FLAC__StreamMetadataSeekPoint used to indicate a placeholder | ||
562 | * point (== 0xffffffffffffffff). | ||
563 | */ | ||
564 | extern FLAC_API const FLAC__uint64 FLAC__STREAM_METADATA_SEEKPOINT_PLACEHOLDER; | ||
565 | |||
566 | |||
567 | /** FLAC SEEKTABLE structure. (c.f. <A HREF="../format.html#metadata_block_seektable">format specification</A>) | ||
568 | * | ||
569 | * \note From the format specification: | ||
570 | * - The seek points must be sorted by ascending sample number. | ||
571 | * - Each seek point's sample number must be the first sample of the | ||
572 | * target frame. | ||
573 | * - Each seek point's sample number must be unique within the table. | ||
574 | * - Existence of a SEEKTABLE block implies a correct setting of | ||
575 | * total_samples in the stream_info block. | ||
576 | * - Behavior is undefined when more than one SEEKTABLE block is | ||
577 | * present in a stream. | ||
578 | */ | ||
579 | typedef struct { | ||
580 | unsigned num_points; | ||
581 | FLAC__StreamMetadata_SeekPoint *points; | ||
582 | } FLAC__StreamMetadata_SeekTable; | ||
583 | |||
584 | |||
585 | /** Vorbis comment entry structure used in VORBIS_COMMENT blocks. (c.f. <A HREF="../format.html#metadata_block_vorbis_comment">format specification</A>) | ||
586 | * | ||
587 | * For convenience, the APIs maintain a trailing NUL character at the end of | ||
588 | * \a entry which is not counted toward \a length, i.e. | ||
589 | * \code strlen(entry) == length \endcode | ||
590 | */ | ||
591 | typedef struct { | ||
592 | FLAC__uint32 length; | ||
593 | FLAC__byte *entry; | ||
594 | } FLAC__StreamMetadata_VorbisComment_Entry; | ||
595 | |||
596 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_ENTRY_LENGTH_LEN; /**< == 32 (bits) */ | ||
597 | |||
598 | |||
599 | /** FLAC VORBIS_COMMENT structure. (c.f. <A HREF="../format.html#metadata_block_vorbis_comment">format specification</A>) | ||
600 | */ | ||
601 | typedef struct { | ||
602 | FLAC__StreamMetadata_VorbisComment_Entry vendor_string; | ||
603 | FLAC__uint32 num_comments; | ||
604 | FLAC__StreamMetadata_VorbisComment_Entry *comments; | ||
605 | } FLAC__StreamMetadata_VorbisComment; | ||
606 | |||
607 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_NUM_COMMENTS_LEN; /**< == 32 (bits) */ | ||
608 | |||
609 | |||
610 | /** FLAC CUESHEET track index structure. (See the | ||
611 | * <A HREF="../format.html#cuesheet_track_index">format specification</A> for | ||
612 | * the full description of each field.) | ||
613 | */ | ||
614 | typedef struct { | ||
615 | FLAC__uint64 offset; | ||
616 | /**< Offset in samples, relative to the track offset, of the index | ||
617 | * point. | ||
618 | */ | ||
619 | |||
620 | FLAC__byte number; | ||
621 | /**< The index point number. */ | ||
622 | } FLAC__StreamMetadata_CueSheet_Index; | ||
623 | |||
624 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_OFFSET_LEN; /**< == 64 (bits) */ | ||
625 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_NUMBER_LEN; /**< == 8 (bits) */ | ||
626 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_RESERVED_LEN; /**< == 3*8 (bits) */ | ||
627 | |||
628 | |||
629 | /** FLAC CUESHEET track structure. (See the | ||
630 | * <A HREF="../format.html#cuesheet_track">format specification</A> for | ||
631 | * the full description of each field.) | ||
632 | */ | ||
633 | typedef struct { | ||
634 | FLAC__uint64 offset; | ||
635 | /**< Track offset in samples, relative to the beginning of the FLAC audio stream. */ | ||
636 | |||
637 | FLAC__byte number; | ||
638 | /**< The track number. */ | ||
639 | |||
640 | char isrc[13]; | ||
641 | /**< Track ISRC. This is a 12-digit alphanumeric code plus a trailing '\0' */ | ||
642 | |||
643 | unsigned type:1; | ||
644 | /**< The track type: 0 for audio, 1 for non-audio. */ | ||
645 | |||
646 | unsigned pre_emphasis:1; | ||
647 | /**< The pre-emphasis flag: 0 for no pre-emphasis, 1 for pre-emphasis. */ | ||
648 | |||
649 | FLAC__byte num_indices; | ||
650 | /**< The number of track index points. */ | ||
651 | |||
652 | FLAC__StreamMetadata_CueSheet_Index *indices; | ||
653 | /**< NULL if num_indices == 0, else pointer to array of index points. */ | ||
654 | |||
655 | } FLAC__StreamMetadata_CueSheet_Track; | ||
656 | |||
657 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_OFFSET_LEN; /**< == 64 (bits) */ | ||
658 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUMBER_LEN; /**< == 8 (bits) */ | ||
659 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_ISRC_LEN; /**< == 12*8 (bits) */ | ||
660 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_TYPE_LEN; /**< == 1 (bit) */ | ||
661 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_PRE_EMPHASIS_LEN; /**< == 1 (bit) */ | ||
662 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_RESERVED_LEN; /**< == 6+13*8 (bits) */ | ||
663 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUM_INDICES_LEN; /**< == 8 (bits) */ | ||
664 | |||
665 | |||
666 | /** FLAC CUESHEET structure. (See the | ||
667 | * <A HREF="../format.html#metadata_block_cuesheet">format specification</A> | ||
668 | * for the full description of each field.) | ||
669 | */ | ||
670 | typedef struct { | ||
671 | char media_catalog_number[129]; | ||
672 | /**< Media catalog number, in ASCII printable characters 0x20-0x7e. In | ||
673 | * general, the media catalog number may be 0 to 128 bytes long; any | ||
674 | * unused characters should be right-padded with NUL characters. | ||
675 | */ | ||
676 | |||
677 | FLAC__uint64 lead_in; | ||
678 | /**< The number of lead-in samples. */ | ||
679 | |||
680 | FLAC__bool is_cd; | ||
681 | /**< \c true if CUESHEET corresponds to a Compact Disc, else \c false */ | ||
682 | |||
683 | unsigned num_tracks; | ||
684 | /**< The number of tracks. */ | ||
685 | |||
686 | FLAC__StreamMetadata_CueSheet_Track *tracks; | ||
687 | /**< NULL if num_tracks == 0, else pointer to array of tracks. */ | ||
688 | |||
689 | } FLAC__StreamMetadata_CueSheet; | ||
690 | |||
691 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_MEDIA_CATALOG_NUMBER_LEN; /**< == 128*8 (bits) */ | ||
692 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_LEAD_IN_LEN; /**< == 64 (bits) */ | ||
693 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_IS_CD_LEN; /**< == 1 (bit) */ | ||
694 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_RESERVED_LEN; /**< == 7+258*8 (bits) */ | ||
695 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_NUM_TRACKS_LEN; /**< == 8 (bits) */ | ||
696 | |||
697 | |||
698 | /** Structure that is used when a metadata block of unknown type is loaded. | ||
699 | * The contents are opaque. The structure is used only internally to | ||
700 | * correctly handle unknown metadata. | ||
701 | */ | ||
702 | typedef struct { | ||
703 | FLAC__byte *data; | ||
704 | } FLAC__StreamMetadata_Unknown; | ||
705 | |||
706 | |||
707 | /** FLAC metadata block structure. (c.f. <A HREF="../format.html#metadata_block">format specification</A>) | ||
708 | */ | ||
709 | typedef struct { | ||
710 | FLAC__MetadataType type; | ||
711 | /**< The type of the metadata block; used determine which member of the | ||
712 | * \a data union to dereference. If type >= FLAC__METADATA_TYPE_UNDEFINED | ||
713 | * then \a data.unknown must be used. */ | ||
714 | |||
715 | FLAC__bool is_last; | ||
716 | /**< \c true if this metadata block is the last, else \a false */ | ||
717 | |||
718 | unsigned length; | ||
719 | /**< Length, in bytes, of the block data as it appears in the stream. */ | ||
720 | |||
721 | union { | ||
722 | FLAC__StreamMetadata_StreamInfo stream_info; | ||
723 | FLAC__StreamMetadata_Padding padding; | ||
724 | FLAC__StreamMetadata_Application application; | ||
725 | FLAC__StreamMetadata_SeekTable seek_table; | ||
726 | FLAC__StreamMetadata_VorbisComment vorbis_comment; | ||
727 | FLAC__StreamMetadata_CueSheet cue_sheet; | ||
728 | FLAC__StreamMetadata_Unknown unknown; | ||
729 | } data; | ||
730 | /**< Polymorphic block data; use the \a type value to determine which | ||
731 | * to use. */ | ||
732 | } FLAC__StreamMetadata; | ||
733 | |||
734 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_IS_LAST_LEN; /**< == 1 (bit) */ | ||
735 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_TYPE_LEN; /**< == 7 (bits) */ | ||
736 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_LENGTH_LEN; /**< == 24 (bits) */ | ||
737 | |||
738 | /** The total stream length of a metadata block header in bytes. */ | ||
739 | #define FLAC__STREAM_METADATA_HEADER_LENGTH (4u) | ||
740 | |||
741 | /*****************************************************************************/ | ||
742 | |||
743 | |||
744 | /***************************************************************************** | ||
745 | * | ||
746 | * Utility functions | ||
747 | * | ||
748 | *****************************************************************************/ | ||
749 | |||
750 | /** Tests that a sample rate is valid for FLAC. Since the rules for valid | ||
751 | * sample rates are slightly complex, they are encapsulated in this function. | ||
752 | * | ||
753 | * \param sample_rate The sample rate to test for compliance. | ||
754 | * \retval FLAC__bool | ||
755 | * \c true if the given sample rate conforms to the specification, else | ||
756 | * \c false. | ||
757 | */ | ||
758 | FLAC_API FLAC__bool FLAC__format_sample_rate_is_valid(unsigned sample_rate); | ||
759 | |||
760 | /** Check a Vorbis comment entry name to see if it conforms to the Vorbis | ||
761 | * comment specification. | ||
762 | * | ||
763 | * Vorbis comment names must be composed only of characters from | ||
764 | * [0x20-0x3C,0x3E-0x7D]. | ||
765 | * | ||
766 | * \param name A NUL-terminated string to be checked. | ||
767 | * \assert | ||
768 | * \code name != NULL \endcode | ||
769 | * \retval FLAC__bool | ||
770 | * \c false if entry name is illegal, else \c true. | ||
771 | */ | ||
772 | FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_name_is_legal(const char *name); | ||
773 | |||
774 | /** Check a Vorbis comment entry value to see if it conforms to the Vorbis | ||
775 | * comment specification. | ||
776 | * | ||
777 | * Vorbis comment values must be valid UTF-8 sequences. | ||
778 | * | ||
779 | * \param value A string to be checked. | ||
780 | * \param length A the length of \a value in bytes. May be | ||
781 | * \c (unsigned)(-1) to indicate that \a value is a plain | ||
782 | * UTF-8 NUL-terminated string. | ||
783 | * \assert | ||
784 | * \code value != NULL \endcode | ||
785 | * \retval FLAC__bool | ||
786 | * \c false if entry name is illegal, else \c true. | ||
787 | */ | ||
788 | FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_value_is_legal(const FLAC__byte *value, unsigned length); | ||
789 | |||
790 | /** Check a Vorbis comment entry to see if it conforms to the Vorbis | ||
791 | * comment specification. | ||
792 | * | ||
793 | * Vorbis comment entries must be of the form 'name=value', and 'name' and | ||
794 | * 'value' must be legal according to | ||
795 | * FLAC__format_vorbiscomment_entry_name_is_legal() and | ||
796 | * FLAC__format_vorbiscomment_entry_value_is_legal() respectively. | ||
797 | * | ||
798 | * \param value A string to be checked. | ||
799 | * \assert | ||
800 | * \code value != NULL \endcode | ||
801 | * \retval FLAC__bool | ||
802 | * \c false if entry name is illegal, else \c true. | ||
803 | */ | ||
804 | FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_is_legal(const FLAC__byte *entry, unsigned length); | ||
805 | |||
806 | /* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */ | ||
807 | /** Check a seek table to see if it conforms to the FLAC specification. | ||
808 | * See the format specification for limits on the contents of the | ||
809 | * seek table. | ||
810 | * | ||
811 | * \param seek_table A pointer to a seek table to be checked. | ||
812 | * \assert | ||
813 | * \code seek_table != NULL \endcode | ||
814 | * \retval FLAC__bool | ||
815 | * \c false if seek table is illegal, else \c true. | ||
816 | */ | ||
817 | FLAC_API FLAC__bool FLAC__format_seektable_is_legal(const FLAC__StreamMetadata_SeekTable *seek_table); | ||
818 | |||
819 | /* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */ | ||
820 | /** Sort a seek table's seek points according to the format specification. | ||
821 | * This includes a "unique-ification" step to remove duplicates, i.e. | ||
822 | * seek points with identical \a sample_number values. Duplicate seek | ||
823 | * points are converted into placeholder points and sorted to the end of | ||
824 | * the table. | ||
825 | * | ||
826 | * \param seek_table A pointer to a seek table to be sorted. | ||
827 | * \assert | ||
828 | * \code seek_table != NULL \endcode | ||
829 | * \retval unsigned | ||
830 | * The number of duplicate seek points converted into placeholders. | ||
831 | */ | ||
832 | FLAC_API unsigned FLAC__format_seektable_sort(FLAC__StreamMetadata_SeekTable *seek_table); | ||
833 | |||
834 | /* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */ | ||
835 | /** Check a cue sheet to see if it conforms to the FLAC specification. | ||
836 | * See the format specification for limits on the contents of the | ||
837 | * cue sheet. | ||
838 | * | ||
839 | * \param cue_sheet A pointer to an existing cue sheet to be checked. | ||
840 | * \param check_cd_da_subset If \c true, check CUESHEET against more | ||
841 | * stringent requirements for a CD-DA (audio) disc. | ||
842 | * \param violation Address of a pointer to a string. If there is a | ||
843 | * violation, a pointer to a string explanation of the | ||
844 | * violation will be returned here. \a violation may be | ||
845 | * \c NULL if you don't need the returned string. Do not | ||
846 | * free the returned string; it will always point to static | ||
847 | * data. | ||
848 | * \assert | ||
849 | * \code cue_sheet != NULL \endcode | ||
850 | * \retval FLAC__bool | ||
851 | * \c false if cue sheet is illegal, else \c true. | ||
852 | */ | ||
853 | FLAC_API FLAC__bool FLAC__format_cuesheet_is_legal(const FLAC__StreamMetadata_CueSheet *cue_sheet, FLAC__bool check_cd_da_subset, const char **violation); | ||
854 | |||
855 | /* \} */ | ||
856 | |||
857 | #ifdef __cplusplus | ||
858 | } | ||
859 | #endif | ||
860 | |||
861 | #endif | ||
diff --git a/apps/codecs/libFLAC/include/FLAC/metadata.h b/apps/codecs/libFLAC/include/FLAC/metadata.h new file mode 100644 index 0000000000..ff40e6d5ed --- /dev/null +++ b/apps/codecs/libFLAC/include/FLAC/metadata.h | |||
@@ -0,0 +1,1858 @@ | |||
1 | /* libFLAC - Free Lossless Audio Codec library | ||
2 | * Copyright (C) 2001,2002,2003,2004,2005 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__METADATA_H | ||
33 | #define FLAC__METADATA_H | ||
34 | |||
35 | #include "export.h" | ||
36 | #include "callback.h" | ||
37 | #include "format.h" | ||
38 | |||
39 | /****************************************************************************** | ||
40 | (For an example of how all these routines are used, see the source | ||
41 | code for the unit tests in src/test_libFLAC/metadata_*.c, or metaflac | ||
42 | in src/metaflac/) | ||
43 | ******************************************************************************/ | ||
44 | |||
45 | /** \file include/FLAC/metadata.h | ||
46 | * | ||
47 | * \brief | ||
48 | * This module provides functions for creating and manipulating FLAC | ||
49 | * metadata blocks in memory, and three progressively more powerful | ||
50 | * interfaces for traversing and editing metadata in FLAC files. | ||
51 | * | ||
52 | * See the detailed documentation for each interface in the | ||
53 | * \link flac_metadata metadata \endlink module. | ||
54 | */ | ||
55 | |||
56 | /** \defgroup flac_metadata FLAC/metadata.h: metadata interfaces | ||
57 | * \ingroup flac | ||
58 | * | ||
59 | * \brief | ||
60 | * This module provides functions for creating and manipulating FLAC | ||
61 | * metadata blocks in memory, and three progressively more powerful | ||
62 | * interfaces for traversing and editing metadata in FLAC files. | ||
63 | * | ||
64 | * There are three metadata interfaces of increasing complexity: | ||
65 | * | ||
66 | * Level 0: | ||
67 | * Read-only access to the STREAMINFO and VORBIS_COMMENT blocks. | ||
68 | * | ||
69 | * Level 1: | ||
70 | * Read-write access to all metadata blocks. This level is write- | ||
71 | * efficient in most cases (more on this below), and uses less memory | ||
72 | * than level 2. | ||
73 | * | ||
74 | * Level 2: | ||
75 | * Read-write access to all metadata blocks. This level is write- | ||
76 | * efficient in all cases, but uses more memory since all metadata for | ||
77 | * the whole file is read into memory and manipulated before writing | ||
78 | * out again. | ||
79 | * | ||
80 | * What do we mean by efficient? Since FLAC metadata appears at the | ||
81 | * beginning of the file, when writing metadata back to a FLAC file | ||
82 | * it is possible to grow or shrink the metadata such that the entire | ||
83 | * file must be rewritten. However, if the size remains the same during | ||
84 | * changes or PADDING blocks are utilized, only the metadata needs to be | ||
85 | * overwritten, which is much faster. | ||
86 | * | ||
87 | * Efficient means the whole file is rewritten at most one time, and only | ||
88 | * when necessary. Level 1 is not efficient only in the case that you | ||
89 | * cause more than one metadata block to grow or shrink beyond what can | ||
90 | * be accomodated by padding. In this case you should probably use level | ||
91 | * 2, which allows you to edit all the metadata for a file in memory and | ||
92 | * write it out all at once. | ||
93 | * | ||
94 | * All levels know how to skip over and not disturb an ID3v2 tag at the | ||
95 | * front of the file. | ||
96 | * | ||
97 | * All levels access files via their filenames. In addition, level 2 | ||
98 | * has additional alternative read and write functions that take an I/O | ||
99 | * handle and callbacks, for times when access by filename is not possible. | ||
100 | * | ||
101 | * In addition to the three interfaces, this module defines functions for | ||
102 | * creating and manipulating various metadata objects in memory. As we see | ||
103 | * from the Format module, FLAC metadata blocks in memory are very primitive | ||
104 | * structures for storing information in an efficient way. Reading | ||
105 | * information from the structures is easy but creating or modifying them | ||
106 | * directly is more complex. The metadata object routines here facilitate | ||
107 | * this by taking care of the consistency and memory management drudgery. | ||
108 | * | ||
109 | * Unless you will be using the level 1 or 2 interfaces to modify existing | ||
110 | * metadata however, you will not probably not need these. | ||
111 | * | ||
112 | * From a dependency standpoint, none of the encoders or decoders require | ||
113 | * the metadata module. This is so that embedded users can strip out the | ||
114 | * metadata module from libFLAC to reduce the size and complexity. | ||
115 | */ | ||
116 | |||
117 | #ifdef __cplusplus | ||
118 | extern "C" { | ||
119 | #endif | ||
120 | |||
121 | |||
122 | /** \defgroup flac_metadata_level0 FLAC/metadata.h: metadata level 0 interface | ||
123 | * \ingroup flac_metadata | ||
124 | * | ||
125 | * \brief | ||
126 | * The level 0 interface consists of individual routines to read the | ||
127 | * STREAMINFO and VORBIS_COMMENT blocks, requiring only a filename. | ||
128 | * | ||
129 | * It skips any ID3v2 tag at the head of the file. | ||
130 | * | ||
131 | * \{ | ||
132 | */ | ||
133 | |||
134 | /** Read the STREAMINFO metadata block of the given FLAC file. This function | ||
135 | * will skip any ID3v2 tag at the head of the file. | ||
136 | * | ||
137 | * \param filename The path to the FLAC file to read. | ||
138 | * \param streaminfo A pointer to space for the STREAMINFO block. Since | ||
139 | * FLAC__StreamMetadata is a simple structure with no | ||
140 | * memory allocation involved, you pass the address of | ||
141 | * an existing structure. It need not be initialized. | ||
142 | * \assert | ||
143 | * \code filename != NULL \endcode | ||
144 | * \code streaminfo != NULL \endcode | ||
145 | * \retval FLAC__bool | ||
146 | * \c true if a valid STREAMINFO block was read from \a filename. Returns | ||
147 | * \c false if there was a memory allocation error, a file decoder error, | ||
148 | * or the file contained no STREAMINFO block. (A memory allocation error | ||
149 | * is possible because this function must set up a file decoder.) | ||
150 | */ | ||
151 | FLAC_API FLAC__bool FLAC__metadata_get_streaminfo(const char *filename, FLAC__StreamMetadata *streaminfo); | ||
152 | |||
153 | /** Read the VORBIS_COMMENT metadata block of the given FLAC file. This | ||
154 | * function will skip any ID3v2 tag at the head of the file. | ||
155 | * | ||
156 | * \param filename The path to the FLAC file to read. | ||
157 | * \param tags The address where the returned pointer will be | ||
158 | * stored. The \a tags object must be deleted by | ||
159 | * the caller using FLAC__metadata_object_delete(). | ||
160 | * \assert | ||
161 | * \code filename != NULL \endcode | ||
162 | * \code streaminfo != NULL \endcode | ||
163 | * \retval FLAC__bool | ||
164 | * \c true if a valid VORBIS_COMMENT block was read from \a filename, | ||
165 | * and \a *tags will be set to the address of the tag structure. | ||
166 | * Returns \c false if there was a memory allocation error, a file | ||
167 | * decoder error, or the file contained no VORBIS_COMMENT block, and | ||
168 | * \a *tags will be set to \c NULL. | ||
169 | */ | ||
170 | FLAC_API FLAC__bool FLAC__metadata_get_tags(const char *filename, FLAC__StreamMetadata **tags); | ||
171 | |||
172 | /* \} */ | ||
173 | |||
174 | |||
175 | /** \defgroup flac_metadata_level1 FLAC/metadata.h: metadata level 1 interface | ||
176 | * \ingroup flac_metadata | ||
177 | * | ||
178 | * \brief | ||
179 | * The level 1 interface provides read-write access to FLAC file metadata and | ||
180 | * operates directly on the FLAC file. | ||
181 | * | ||
182 | * The general usage of this interface is: | ||
183 | * | ||
184 | * - Create an iterator using FLAC__metadata_simple_iterator_new() | ||
185 | * - Attach it to a file using FLAC__metadata_simple_iterator_init() and check | ||
186 | * the exit code. Call FLAC__metadata_simple_iterator_is_writable() to | ||
187 | * see if the file is writable, or read-only access is allowed. | ||
188 | * - Use FLAC__metadata_simple_iterator_next() and | ||
189 | * FLAC__metadata_simple_iterator_prev() to move around the blocks. | ||
190 | * This is does not read the actual blocks themselves. | ||
191 | * FLAC__metadata_simple_iterator_next() is relatively fast. | ||
192 | * FLAC__metadata_simple_iterator_prev() is slower since it needs to search | ||
193 | * forward from the front of the file. | ||
194 | * - Use FLAC__metadata_simple_iterator_get_block_type() or | ||
195 | * FLAC__metadata_simple_iterator_get_block() to access the actual data at | ||
196 | * the current iterator position. The returned object is yours to modify | ||
197 | * and free. | ||
198 | * - Use FLAC__metadata_simple_iterator_set_block() to write a modified block | ||
199 | * back. You must have write permission to the original file. Make sure to | ||
200 | * read the whole comment to FLAC__metadata_simple_iterator_set_block() | ||
201 | * below. | ||
202 | * - Use FLAC__metadata_simple_iterator_insert_block_after() to add new blocks. | ||
203 | * Use the object creation functions from | ||
204 | * \link flac_metadata_object here \endlink to generate new objects. | ||
205 | * - Use FLAC__metadata_simple_iterator_delete_block() to remove the block | ||
206 | * currently referred to by the iterator, or replace it with padding. | ||
207 | * - Destroy the iterator with FLAC__metadata_simple_iterator_delete() when | ||
208 | * finished. | ||
209 | * | ||
210 | * \note | ||
211 | * The FLAC file remains open the whole time between | ||
212 | * FLAC__metadata_simple_iterator_init() and | ||
213 | * FLAC__metadata_simple_iterator_delete(), so make sure you are not altering | ||
214 | * the file during this time. | ||
215 | * | ||
216 | * \note | ||
217 | * Do not modify the \a is_last, \a length, or \a type fields of returned | ||
218 | * FLAC__StreamMetadata objects. These are managed automatically. | ||
219 | * | ||
220 | * \note | ||
221 | * If any of the modification functions | ||
222 | * (FLAC__metadata_simple_iterator_set_block(), | ||
223 | * FLAC__metadata_simple_iterator_delete_block(), | ||
224 | * FLAC__metadata_simple_iterator_insert_block_after(), etc.) return \c false, | ||
225 | * you should delete the iterator as it may no longer be valid. | ||
226 | * | ||
227 | * \{ | ||
228 | */ | ||
229 | |||
230 | struct FLAC__Metadata_SimpleIterator; | ||
231 | /** The opaque structure definition for the level 1 iterator type. | ||
232 | * See the | ||
233 | * \link flac_metadata_level1 metadata level 1 module \endlink | ||
234 | * for a detailed description. | ||
235 | */ | ||
236 | typedef struct FLAC__Metadata_SimpleIterator FLAC__Metadata_SimpleIterator; | ||
237 | |||
238 | /** Status type for FLAC__Metadata_SimpleIterator. | ||
239 | * | ||
240 | * The iterator's current status can be obtained by calling FLAC__metadata_simple_iterator_status(). | ||
241 | */ | ||
242 | typedef enum { | ||
243 | |||
244 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK = 0, | ||
245 | /**< The iterator is in the normal OK state */ | ||
246 | |||
247 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ILLEGAL_INPUT, | ||
248 | /**< The data passed into a function violated the function's usage criteria */ | ||
249 | |||
250 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ERROR_OPENING_FILE, | ||
251 | /**< The iterator could not open the target file */ | ||
252 | |||
253 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_A_FLAC_FILE, | ||
254 | /**< The iterator could not find the FLAC signature at the start of the file */ | ||
255 | |||
256 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_WRITABLE, | ||
257 | /**< The iterator tried to write to a file that was not writable */ | ||
258 | |||
259 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_BAD_METADATA, | ||
260 | /**< The iterator encountered input that does not conform to the FLAC metadata specification */ | ||
261 | |||
262 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_READ_ERROR, | ||
263 | /**< The iterator encountered an error while reading the FLAC file */ | ||
264 | |||
265 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_SEEK_ERROR, | ||
266 | /**< The iterator encountered an error while seeking in the FLAC file */ | ||
267 | |||
268 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_WRITE_ERROR, | ||
269 | /**< The iterator encountered an error while writing the FLAC file */ | ||
270 | |||
271 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_RENAME_ERROR, | ||
272 | /**< The iterator encountered an error renaming the FLAC file */ | ||
273 | |||
274 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_UNLINK_ERROR, | ||
275 | /**< The iterator encountered an error removing the temporary file */ | ||
276 | |||
277 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_MEMORY_ALLOCATION_ERROR, | ||
278 | /**< Memory allocation failed */ | ||
279 | |||
280 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_INTERNAL_ERROR | ||
281 | /**< The caller violated an assertion or an unexpected error occurred */ | ||
282 | |||
283 | } FLAC__Metadata_SimpleIteratorStatus; | ||
284 | |||
285 | /** Maps a FLAC__Metadata_SimpleIteratorStatus to a C string. | ||
286 | * | ||
287 | * Using a FLAC__Metadata_SimpleIteratorStatus as the index to this array | ||
288 | * will give the string equivalent. The contents should not be modified. | ||
289 | */ | ||
290 | extern FLAC_API const char * const FLAC__Metadata_SimpleIteratorStatusString[]; | ||
291 | |||
292 | |||
293 | /** Create a new iterator instance. | ||
294 | * | ||
295 | * \retval FLAC__Metadata_SimpleIterator* | ||
296 | * \c NULL if there was an error allocating memory, else the new instance. | ||
297 | */ | ||
298 | FLAC_API FLAC__Metadata_SimpleIterator *FLAC__metadata_simple_iterator_new(); | ||
299 | |||
300 | /** Free an iterator instance. Deletes the object pointed to by \a iterator. | ||
301 | * | ||
302 | * \param iterator A pointer to an existing iterator. | ||
303 | * \assert | ||
304 | * \code iterator != NULL \endcode | ||
305 | */ | ||
306 | FLAC_API void FLAC__metadata_simple_iterator_delete(FLAC__Metadata_SimpleIterator *iterator); | ||
307 | |||
308 | /** Get the current status of the iterator. Call this after a function | ||
309 | * returns \c false to get the reason for the error. Also resets the status | ||
310 | * to FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK. | ||
311 | * | ||
312 | * \param iterator A pointer to an existing iterator. | ||
313 | * \assert | ||
314 | * \code iterator != NULL \endcode | ||
315 | * \retval FLAC__Metadata_SimpleIteratorStatus | ||
316 | * The current status of the iterator. | ||
317 | */ | ||
318 | FLAC_API FLAC__Metadata_SimpleIteratorStatus FLAC__metadata_simple_iterator_status(FLAC__Metadata_SimpleIterator *iterator); | ||
319 | |||
320 | /** Initialize the iterator to point to the first metadata block in the | ||
321 | * given FLAC file. | ||
322 | * | ||
323 | * \param iterator A pointer to an existing iterator. | ||
324 | * \param filename The path to the FLAC file. | ||
325 | * \param read_only If \c true, the FLAC file will be opened | ||
326 | * in read-only mode; if \c false, the FLAC | ||
327 | * file will be opened for edit even if no | ||
328 | * edits are performed. | ||
329 | * \param preserve_file_stats If \c true, the owner and modification | ||
330 | * time will be preserved even if the FLAC | ||
331 | * file is written to. | ||
332 | * \assert | ||
333 | * \code iterator != NULL \endcode | ||
334 | * \code filename != NULL \endcode | ||
335 | * \retval FLAC__bool | ||
336 | * \c false if a memory allocation error occurs, the file can't be | ||
337 | * opened, or another error occurs, else \c true. | ||
338 | */ | ||
339 | FLAC_API FLAC__bool FLAC__metadata_simple_iterator_init(FLAC__Metadata_SimpleIterator *iterator, const char *filename, FLAC__bool read_only, FLAC__bool preserve_file_stats); | ||
340 | |||
341 | /** Returns \c true if the FLAC file is writable. If \c false, calls to | ||
342 | * FLAC__metadata_simple_iterator_set_block() and | ||
343 | * FLAC__metadata_simple_iterator_insert_block_after() will fail. | ||
344 | * | ||
345 | * \param iterator A pointer to an existing iterator. | ||
346 | * \assert | ||
347 | * \code iterator != NULL \endcode | ||
348 | * \retval FLAC__bool | ||
349 | * See above. | ||
350 | */ | ||
351 | FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_writable(const FLAC__Metadata_SimpleIterator *iterator); | ||
352 | |||
353 | /** Moves the iterator forward one metadata block, returning \c false if | ||
354 | * already at the end. | ||
355 | * | ||
356 | * \param iterator A pointer to an existing initialized iterator. | ||
357 | * \assert | ||
358 | * \code iterator != NULL \endcode | ||
359 | * \a iterator has been successfully initialized with | ||
360 | * FLAC__metadata_simple_iterator_init() | ||
361 | * \retval FLAC__bool | ||
362 | * \c false if already at the last metadata block of the chain, else | ||
363 | * \c true. | ||
364 | */ | ||
365 | FLAC_API FLAC__bool FLAC__metadata_simple_iterator_next(FLAC__Metadata_SimpleIterator *iterator); | ||
366 | |||
367 | /** Moves the iterator backward one metadata block, returning \c false if | ||
368 | * already at the beginning. | ||
369 | * | ||
370 | * \param iterator A pointer to an existing initialized iterator. | ||
371 | * \assert | ||
372 | * \code iterator != NULL \endcode | ||
373 | * \a iterator has been successfully initialized with | ||
374 | * FLAC__metadata_simple_iterator_init() | ||
375 | * \retval FLAC__bool | ||
376 | * \c false if already at the first metadata block of the chain, else | ||
377 | * \c true. | ||
378 | */ | ||
379 | FLAC_API FLAC__bool FLAC__metadata_simple_iterator_prev(FLAC__Metadata_SimpleIterator *iterator); | ||
380 | |||
381 | /** Get the type of the metadata block at the current position. This | ||
382 | * avoids reading the actual block data which can save time for large | ||
383 | * blocks. | ||
384 | * | ||
385 | * \param iterator A pointer to an existing initialized iterator. | ||
386 | * \assert | ||
387 | * \code iterator != NULL \endcode | ||
388 | * \a iterator has been successfully initialized with | ||
389 | * FLAC__metadata_simple_iterator_init() | ||
390 | * \retval FLAC__MetadataType | ||
391 | * The type of the metadata block at the current iterator position. | ||
392 | */ | ||
393 | |||
394 | FLAC_API FLAC__MetadataType FLAC__metadata_simple_iterator_get_block_type(const FLAC__Metadata_SimpleIterator *iterator); | ||
395 | |||
396 | /** Get the metadata block at the current position. You can modify the | ||
397 | * block but must use FLAC__metadata_simple_iterator_set_block() to | ||
398 | * write it back to the FLAC file. | ||
399 | * | ||
400 | * You must call FLAC__metadata_object_delete() on the returned object | ||
401 | * when you are finished with it. | ||
402 | * | ||
403 | * \param iterator A pointer to an existing initialized iterator. | ||
404 | * \assert | ||
405 | * \code iterator != NULL \endcode | ||
406 | * \a iterator has been successfully initialized with | ||
407 | * FLAC__metadata_simple_iterator_init() | ||
408 | * \retval FLAC__StreamMetadata* | ||
409 | * The current metadata block. | ||
410 | */ | ||
411 | FLAC_API FLAC__StreamMetadata *FLAC__metadata_simple_iterator_get_block(FLAC__Metadata_SimpleIterator *iterator); | ||
412 | |||
413 | /** Write a block back to the FLAC file. This function tries to be | ||
414 | * as efficient as possible; how the block is actually written is | ||
415 | * shown by the following: | ||
416 | * | ||
417 | * Existing block is a STREAMINFO block and the new block is a | ||
418 | * STREAMINFO block: the new block is written in place. Make sure | ||
419 | * you know what you're doing when changing the values of a | ||
420 | * STREAMINFO block. | ||
421 | * | ||
422 | * Existing block is a STREAMINFO block and the new block is a | ||
423 | * not a STREAMINFO block: this is an error since the first block | ||
424 | * must be a STREAMINFO block. Returns \c false without altering the | ||
425 | * file. | ||
426 | * | ||
427 | * Existing block is not a STREAMINFO block and the new block is a | ||
428 | * STREAMINFO block: this is an error since there may be only one | ||
429 | * STREAMINFO block. Returns \c false without altering the file. | ||
430 | * | ||
431 | * Existing block and new block are the same length: the existing | ||
432 | * block will be replaced by the new block, written in place. | ||
433 | * | ||
434 | * Existing block is longer than new block: if use_padding is \c true, | ||
435 | * the existing block will be overwritten in place with the new | ||
436 | * block followed by a PADDING block, if possible, to make the total | ||
437 | * size the same as the existing block. Remember that a padding | ||
438 | * block requires at least four bytes so if the difference in size | ||
439 | * between the new block and existing block is less than that, the | ||
440 | * entire file will have to be rewritten, using the new block's | ||
441 | * exact size. If use_padding is \c false, the entire file will be | ||
442 | * rewritten, replacing the existing block by the new block. | ||
443 | * | ||
444 | * Existing block is shorter than new block: if use_padding is \c true, | ||
445 | * the function will try and expand the new block into the following | ||
446 | * PADDING block, if it exists and doing so won't shrink the PADDING | ||
447 | * block to less than 4 bytes. If there is no following PADDING | ||
448 | * block, or it will shrink to less than 4 bytes, or use_padding is | ||
449 | * \c false, the entire file is rewritten, replacing the existing block | ||
450 | * with the new block. Note that in this case any following PADDING | ||
451 | * block is preserved as is. | ||
452 | * | ||
453 | * After writing the block, the iterator will remain in the same | ||
454 | * place, i.e. pointing to the new block. | ||
455 | * | ||
456 | * \param iterator A pointer to an existing initialized iterator. | ||
457 | * \param block The block to set. | ||
458 | * \param use_padding See above. | ||
459 | * \assert | ||
460 | * \code iterator != NULL \endcode | ||
461 | * \a iterator has been successfully initialized with | ||
462 | * FLAC__metadata_simple_iterator_init() | ||
463 | * \code block != NULL \endcode | ||
464 | * \retval FLAC__bool | ||
465 | * \c true if successful, else \c false. | ||
466 | */ | ||
467 | FLAC_API FLAC__bool FLAC__metadata_simple_iterator_set_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding); | ||
468 | |||
469 | /** This is similar to FLAC__metadata_simple_iterator_set_block() | ||
470 | * except that instead of writing over an existing block, it appends | ||
471 | * a block after the existing block. \a use_padding is again used to | ||
472 | * tell the function to try an expand into following padding in an | ||
473 | * attempt to avoid rewriting the entire file. | ||
474 | * | ||
475 | * This function will fail and return \c false if given a STREAMINFO | ||
476 | * block. | ||
477 | * | ||
478 | * After writing the block, the iterator will be pointing to the | ||
479 | * new block. | ||
480 | * | ||
481 | * \param iterator A pointer to an existing initialized iterator. | ||
482 | * \param block The block to set. | ||
483 | * \param use_padding See above. | ||
484 | * \assert | ||
485 | * \code iterator != NULL \endcode | ||
486 | * \a iterator has been successfully initialized with | ||
487 | * FLAC__metadata_simple_iterator_init() | ||
488 | * \code block != NULL \endcode | ||
489 | * \retval FLAC__bool | ||
490 | * \c true if successful, else \c false. | ||
491 | */ | ||
492 | FLAC_API FLAC__bool FLAC__metadata_simple_iterator_insert_block_after(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding); | ||
493 | |||
494 | /** Deletes the block at the current position. This will cause the | ||
495 | * entire FLAC file to be rewritten, unless \a use_padding is \c true, | ||
496 | * in which case the block will be replaced by an equal-sized PADDING | ||
497 | * block. The iterator will be left pointing to the block before the | ||
498 | * one just deleted. | ||
499 | * | ||
500 | * You may not delete the STREAMINFO block. | ||
501 | * | ||
502 | * \param iterator A pointer to an existing initialized iterator. | ||
503 | * \param use_padding See above. | ||
504 | * \assert | ||
505 | * \code iterator != NULL \endcode | ||
506 | * \a iterator has been successfully initialized with | ||
507 | * FLAC__metadata_simple_iterator_init() | ||
508 | * \retval FLAC__bool | ||
509 | * \c true if successful, else \c false. | ||
510 | */ | ||
511 | FLAC_API FLAC__bool FLAC__metadata_simple_iterator_delete_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__bool use_padding); | ||
512 | |||
513 | /* \} */ | ||
514 | |||
515 | |||
516 | /** \defgroup flac_metadata_level2 FLAC/metadata.h: metadata level 2 interface | ||
517 | * \ingroup flac_metadata | ||
518 | * | ||
519 | * \brief | ||
520 | * The level 2 interface provides read-write access to FLAC file metadata; | ||
521 | * all metadata is read into memory, operated on in memory, and then written | ||
522 | * to file, which is more efficient than level 1 when editing multiple blocks. | ||
523 | * | ||
524 | * The general usage of this interface is: | ||
525 | * | ||
526 | * - Create a new chain using FLAC__metadata_chain_new(). A chain is a | ||
527 | * linked list of FLAC metadata blocks. | ||
528 | * - Read all metadata into the the chain from a FLAC file using | ||
529 | * FLAC__metadata_chain_read() and check the status. | ||
530 | * - Optionally, consolidate the padding using | ||
531 | * FLAC__metadata_chain_merge_padding() or | ||
532 | * FLAC__metadata_chain_sort_padding(). | ||
533 | * - Create a new iterator using FLAC__metadata_iterator_new() | ||
534 | * - Initialize the iterator to point to the first element in the chain | ||
535 | * using FLAC__metadata_iterator_init() | ||
536 | * - Traverse the chain using FLAC__metadata_iterator_next and | ||
537 | * FLAC__metadata_iterator_prev(). | ||
538 | * - Get a block for reading or modification using | ||
539 | * FLAC__metadata_iterator_get_block(). The pointer to the object | ||
540 | * inside the chain is returned, so the block is yours to modify. | ||
541 | * Changes will be reflected in the FLAC file when you write the | ||
542 | * chain. You can also add and delete blocks (see functions below). | ||
543 | * - When done, write out the chain using FLAC__metadata_chain_write(). | ||
544 | * Make sure to read the whole comment to the function below. | ||
545 | * - Delete the chain using FLAC__metadata_chain_delete(). | ||
546 | * | ||
547 | * \note | ||
548 | * Even though the FLAC file is not open while the chain is being | ||
549 | * manipulated, you must not alter the file externally during | ||
550 | * this time. The chain assumes the FLAC file will not change | ||
551 | * between the time of FLAC__metadata_chain_read() and | ||
552 | * FLAC__metadata_chain_write(). | ||
553 | * | ||
554 | * \note | ||
555 | * Do not modify the is_last, length, or type fields of returned | ||
556 | * FLAC__StreamMetadata objects. These are managed automatically. | ||
557 | * | ||
558 | * \note | ||
559 | * The metadata objects returned by FLAC__metadata_iterator_get_block() | ||
560 | * are owned by the chain; do not FLAC__metadata_object_delete() them. | ||
561 | * In the same way, blocks passed to FLAC__metadata_iterator_set_block() | ||
562 | * become owned by the chain and they will be deleted when the chain is | ||
563 | * deleted. | ||
564 | * | ||
565 | * \{ | ||
566 | */ | ||
567 | |||
568 | struct FLAC__Metadata_Chain; | ||
569 | /** The opaque structure definition for the level 2 chain type. | ||
570 | */ | ||
571 | typedef struct FLAC__Metadata_Chain FLAC__Metadata_Chain; | ||
572 | |||
573 | struct FLAC__Metadata_Iterator; | ||
574 | /** The opaque structure definition for the level 2 iterator type. | ||
575 | */ | ||
576 | typedef struct FLAC__Metadata_Iterator FLAC__Metadata_Iterator; | ||
577 | |||
578 | typedef enum { | ||
579 | FLAC__METADATA_CHAIN_STATUS_OK = 0, | ||
580 | /**< The chain is in the normal OK state */ | ||
581 | |||
582 | FLAC__METADATA_CHAIN_STATUS_ILLEGAL_INPUT, | ||
583 | /**< The data passed into a function violated the function's usage criteria */ | ||
584 | |||
585 | FLAC__METADATA_CHAIN_STATUS_ERROR_OPENING_FILE, | ||
586 | /**< The chain could not open the target file */ | ||
587 | |||
588 | FLAC__METADATA_CHAIN_STATUS_NOT_A_FLAC_FILE, | ||
589 | /**< The chain could not find the FLAC signature at the start of the file */ | ||
590 | |||
591 | FLAC__METADATA_CHAIN_STATUS_NOT_WRITABLE, | ||
592 | /**< The chain tried to write to a file that was not writable */ | ||
593 | |||
594 | FLAC__METADATA_CHAIN_STATUS_BAD_METADATA, | ||
595 | /**< The chain encountered input that does not conform to the FLAC metadata specification */ | ||
596 | |||
597 | FLAC__METADATA_CHAIN_STATUS_READ_ERROR, | ||
598 | /**< The chain encountered an error while reading the FLAC file */ | ||
599 | |||
600 | FLAC__METADATA_CHAIN_STATUS_SEEK_ERROR, | ||
601 | /**< The chain encountered an error while seeking in the FLAC file */ | ||
602 | |||
603 | FLAC__METADATA_CHAIN_STATUS_WRITE_ERROR, | ||
604 | /**< The chain encountered an error while writing the FLAC file */ | ||
605 | |||
606 | FLAC__METADATA_CHAIN_STATUS_RENAME_ERROR, | ||
607 | /**< The chain encountered an error renaming the FLAC file */ | ||
608 | |||
609 | FLAC__METADATA_CHAIN_STATUS_UNLINK_ERROR, | ||
610 | /**< The chain encountered an error removing the temporary file */ | ||
611 | |||
612 | FLAC__METADATA_CHAIN_STATUS_MEMORY_ALLOCATION_ERROR, | ||
613 | /**< Memory allocation failed */ | ||
614 | |||
615 | FLAC__METADATA_CHAIN_STATUS_INTERNAL_ERROR, | ||
616 | /**< The caller violated an assertion or an unexpected error occurred */ | ||
617 | |||
618 | FLAC__METADATA_CHAIN_STATUS_INVALID_CALLBACKS, | ||
619 | /**< One or more of the required callbacks was NULL */ | ||
620 | |||
621 | FLAC__METADATA_CHAIN_STATUS_READ_WRITE_MISMATCH, | ||
622 | /**< FLAC__metadata_chain_write() was called on a chain read by | ||
623 | * FLAC__metadata_chain_read_with_callbacks(), or | ||
624 | * FLAC__metadata_chain_write_with_callbacks() or | ||
625 | * FLAC__metadata_chain_write_with_callbacks_and_tempfile() was | ||
626 | * called on a chain read by FLAC__metadata_chain_read(). Matching | ||
627 | * read/write methods must always be used. */ | ||
628 | |||
629 | FLAC__METADATA_CHAIN_STATUS_WRONG_WRITE_CALL | ||
630 | /**< FLAC__metadata_chain_write_with_callbacks() was called when the | ||
631 | * chain write requires a tempfile; use | ||
632 | * FLAC__metadata_chain_write_with_callbacks_and_tempfile() instead. | ||
633 | * Or, FLAC__metadata_chain_write_with_callbacks_and_tempfile() was | ||
634 | * called when the chain write does not require a tempfile; use | ||
635 | * FLAC__metadata_chain_write_with_callbacks() instead. | ||
636 | * Always check FLAC__metadata_chain_check_if_tempfile_needed() | ||
637 | * before writing via callbacks. */ | ||
638 | |||
639 | } FLAC__Metadata_ChainStatus; | ||
640 | |||
641 | /** Maps a FLAC__Metadata_ChainStatus to a C string. | ||
642 | * | ||
643 | * Using a FLAC__Metadata_ChainStatus as the index to this array | ||
644 | * will give the string equivalent. The contents should not be modified. | ||
645 | */ | ||
646 | extern FLAC_API const char * const FLAC__Metadata_ChainStatusString[]; | ||
647 | |||
648 | /*********** FLAC__Metadata_Chain ***********/ | ||
649 | |||
650 | /** Create a new chain instance. | ||
651 | * | ||
652 | * \retval FLAC__Metadata_Chain* | ||
653 | * \c NULL if there was an error allocating memory, else the new instance. | ||
654 | */ | ||
655 | FLAC_API FLAC__Metadata_Chain *FLAC__metadata_chain_new(); | ||
656 | |||
657 | /** Free a chain instance. Deletes the object pointed to by \a chain. | ||
658 | * | ||
659 | * \param chain A pointer to an existing chain. | ||
660 | * \assert | ||
661 | * \code chain != NULL \endcode | ||
662 | */ | ||
663 | FLAC_API void FLAC__metadata_chain_delete(FLAC__Metadata_Chain *chain); | ||
664 | |||
665 | /** Get the current status of the chain. Call this after a function | ||
666 | * returns \c false to get the reason for the error. Also resets the | ||
667 | * status to FLAC__METADATA_CHAIN_STATUS_OK. | ||
668 | * | ||
669 | * \param chain A pointer to an existing chain. | ||
670 | * \assert | ||
671 | * \code chain != NULL \endcode | ||
672 | * \retval FLAC__Metadata_ChainStatus | ||
673 | * The current status of the chain. | ||
674 | */ | ||
675 | FLAC_API FLAC__Metadata_ChainStatus FLAC__metadata_chain_status(FLAC__Metadata_Chain *chain); | ||
676 | |||
677 | /** Read all metadata from a FLAC file into the chain. | ||
678 | * | ||
679 | * \param chain A pointer to an existing chain. | ||
680 | * \param filename The path to the FLAC file to read. | ||
681 | * \assert | ||
682 | * \code chain != NULL \endcode | ||
683 | * \code filename != NULL \endcode | ||
684 | * \retval FLAC__bool | ||
685 | * \c true if a valid list of metadata blocks was read from | ||
686 | * \a filename, else \c false. On failure, check the status with | ||
687 | * FLAC__metadata_chain_status(). | ||
688 | */ | ||
689 | FLAC_API FLAC__bool FLAC__metadata_chain_read(FLAC__Metadata_Chain *chain, const char *filename); | ||
690 | |||
691 | /** Read all metadata from a FLAC stream into the chain via I/O callbacks. | ||
692 | * | ||
693 | * The \a handle need only be open for reading, but must be seekable. | ||
694 | * The equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb" | ||
695 | * for Windows). | ||
696 | * | ||
697 | * \param chain A pointer to an existing chain. | ||
698 | * \param handle The I/O handle of the FLAC stream to read. The | ||
699 | * handle will NOT be closed after the metadata is read; | ||
700 | * that is the duty of the caller. | ||
701 | * \param callbacks | ||
702 | * A set of callbacks to use for I/O. The mandatory | ||
703 | * callbacks are \a read, \a seek, and \a tell. | ||
704 | * \assert | ||
705 | * \code chain != NULL \endcode | ||
706 | * \retval FLAC__bool | ||
707 | * \c true if a valid list of metadata blocks was read from | ||
708 | * \a handle, else \c false. On failure, check the status with | ||
709 | * FLAC__metadata_chain_status(). | ||
710 | */ | ||
711 | FLAC_API FLAC__bool FLAC__metadata_chain_read_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks); | ||
712 | |||
713 | /** Checks if writing the given chain would require the use of a | ||
714 | * temporary file, or if it could be written in place. | ||
715 | * | ||
716 | * Under certain conditions, padding can be utilized so that writing | ||
717 | * edited metadata back to the FLAC file does not require rewriting the | ||
718 | * entire file. If rewriting is required, then a temporary workfile is | ||
719 | * required. When writing metadata using callbacks, you must check | ||
720 | * this function to know whether to call | ||
721 | * FLAC__metadata_chain_write_with_callbacks() or | ||
722 | * FLAC__metadata_chain_write_with_callbacks_and_tempfile(). When | ||
723 | * writing with FLAC__metadata_chain_write(), the temporary file is | ||
724 | * handled internally. | ||
725 | * | ||
726 | * \param chain A pointer to an existing chain. | ||
727 | * \param use_padding | ||
728 | * Whether or not padding will be allowed to be used | ||
729 | * during the write. The value of \a use_padding given | ||
730 | * here must match the value later passed to | ||
731 | * FLAC__metadata_chain_write_with_callbacks() or | ||
732 | * FLAC__metadata_chain_write_with_callbacks_with_tempfile(). | ||
733 | * \assert | ||
734 | * \code chain != NULL \endcode | ||
735 | * \retval FLAC__bool | ||
736 | * \c true if writing the current chain would require a tempfile, or | ||
737 | * \c false if metadata can be written in place. | ||
738 | */ | ||
739 | FLAC_API FLAC__bool FLAC__metadata_chain_check_if_tempfile_needed(FLAC__Metadata_Chain *chain, FLAC__bool use_padding); | ||
740 | |||
741 | /** Write all metadata out to the FLAC file. This function tries to be as | ||
742 | * efficient as possible; how the metadata is actually written is shown by | ||
743 | * the following: | ||
744 | * | ||
745 | * If the current chain is the same size as the existing metadata, the new | ||
746 | * data is written in place. | ||
747 | * | ||
748 | * If the current chain is longer than the existing metadata, and | ||
749 | * \a use_padding is \c true, and the last block is a PADDING block of | ||
750 | * sufficient length, the function will truncate the final padding block | ||
751 | * so that the overall size of the metadata is the same as the existing | ||
752 | * metadata, and then just rewrite the metadata. Otherwise, if not all of | ||
753 | * the above conditions are met, the entire FLAC file must be rewritten. | ||
754 | * If you want to use padding this way it is a good idea to call | ||
755 | * FLAC__metadata_chain_sort_padding() first so that you have the maximum | ||
756 | * amount of padding to work with, unless you need to preserve ordering | ||
757 | * of the PADDING blocks for some reason. | ||
758 | * | ||
759 | * If the current chain is shorter than the existing metadata, and | ||
760 | * \a use_padding is \c true, and the final block is a PADDING block, the padding | ||
761 | * is extended to make the overall size the same as the existing data. If | ||
762 | * \a use_padding is \c true and the last block is not a PADDING block, a new | ||
763 | * PADDING block is added to the end of the new data to make it the same | ||
764 | * size as the existing data (if possible, see the note to | ||
765 | * FLAC__metadata_simple_iterator_set_block() about the four byte limit) | ||
766 | * and the new data is written in place. If none of the above apply or | ||
767 | * \a use_padding is \c false, the entire FLAC file is rewritten. | ||
768 | * | ||
769 | * If \a preserve_file_stats is \c true, the owner and modification time will | ||
770 | * be preserved even if the FLAC file is written. | ||
771 | * | ||
772 | * For this write function to be used, the chain must have been read with | ||
773 | * FLAC__metadata_chain_read(), not FLAC__metadata_chain_read_with_callbacks(). | ||
774 | * | ||
775 | * \param chain A pointer to an existing chain. | ||
776 | * \param use_padding See above. | ||
777 | * \param preserve_file_stats See above. | ||
778 | * \assert | ||
779 | * \code chain != NULL \endcode | ||
780 | * \retval FLAC__bool | ||
781 | * \c true if the write succeeded, else \c false. On failure, | ||
782 | * check the status with FLAC__metadata_chain_status(). | ||
783 | */ | ||
784 | FLAC_API FLAC__bool FLAC__metadata_chain_write(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__bool preserve_file_stats); | ||
785 | |||
786 | /** Write all metadata out to a FLAC stream via callbacks. | ||
787 | * | ||
788 | * (See FLAC__metadata_chain_write() for the details on how padding is | ||
789 | * used to write metadata in place if possible.) | ||
790 | * | ||
791 | * The \a handle must be open for updating and be seekable. The | ||
792 | * equivalent minimum stdio fopen() file mode is \c "r+" (or \c "r+b" | ||
793 | * for Windows). | ||
794 | * | ||
795 | * For this write function to be used, the chain must have been read with | ||
796 | * FLAC__metadata_chain_read_with_callbacks(), not FLAC__metadata_chain_read(). | ||
797 | * Also, FLAC__metadata_chain_check_if_tempfile_needed() must have returned | ||
798 | * \c false. | ||
799 | * | ||
800 | * \param chain A pointer to an existing chain. | ||
801 | * \param use_padding See FLAC__metadata_chain_write() | ||
802 | * \param handle The I/O handle of the FLAC stream to write. The | ||
803 | * handle will NOT be closed after the metadata is | ||
804 | * written; that is the duty of the caller. | ||
805 | * \param callbacks A set of callbacks to use for I/O. The mandatory | ||
806 | * callbacks are \a write and \a seek. | ||
807 | * \assert | ||
808 | * \code chain != NULL \endcode | ||
809 | * \retval FLAC__bool | ||
810 | * \c true if the write succeeded, else \c false. On failure, | ||
811 | * check the status with FLAC__metadata_chain_status(). | ||
812 | */ | ||
813 | FLAC_API FLAC__bool FLAC__metadata_chain_write_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks); | ||
814 | |||
815 | /** Write all metadata out to a FLAC stream via callbacks. | ||
816 | * | ||
817 | * (See FLAC__metadata_chain_write() for the details on how padding is | ||
818 | * used to write metadata in place if possible.) | ||
819 | * | ||
820 | * This version of the write-with-callbacks function must be used when | ||
821 | * FLAC__metadata_chain_check_if_tempfile_needed() returns true. In | ||
822 | * this function, you must supply an I/O handle corresponding to the | ||
823 | * FLAC file to edit, and a temporary handle to which the new FLAC | ||
824 | * file will be written. It is the caller's job to move this temporary | ||
825 | * FLAC file on top of the original FLAC file to complete the metadata | ||
826 | * edit. | ||
827 | * | ||
828 | * The \a handle must be open for reading and be seekable. The | ||
829 | * equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb" | ||
830 | * for Windows). | ||
831 | * | ||
832 | * The \a temp_handle must be open for writing. The | ||
833 | * equivalent minimum stdio fopen() file mode is \c "w" (or \c "wb" | ||
834 | * for Windows). It should be an empty stream, or at least positioned | ||
835 | * at the start-of-file (in which case it is the caller's duty to | ||
836 | * truncate it on return). | ||
837 | * | ||
838 | * For this write function to be used, the chain must have been read with | ||
839 | * FLAC__metadata_chain_read_with_callbacks(), not FLAC__metadata_chain_read(). | ||
840 | * Also, FLAC__metadata_chain_check_if_tempfile_needed() must have returned | ||
841 | * \c true. | ||
842 | * | ||
843 | * \param chain A pointer to an existing chain. | ||
844 | * \param use_padding See FLAC__metadata_chain_write() | ||
845 | * \param handle The I/O handle of the original FLAC stream to read. | ||
846 | * The handle will NOT be closed after the metadata is | ||
847 | * written; that is the duty of the caller. | ||
848 | * \param callbacks A set of callbacks to use for I/O on \a handle. | ||
849 | * The mandatory callbacks are \a read, \a seek, and | ||
850 | * \a eof. | ||
851 | * \param temp_handle The I/O handle of the FLAC stream to write. The | ||
852 | * handle will NOT be closed after the metadata is | ||
853 | * written; that is the duty of the caller. | ||
854 | * \param temp_callbacks | ||
855 | * A set of callbacks to use for I/O on temp_handle. | ||
856 | * The only mandatory callback is \a write. | ||
857 | * \assert | ||
858 | * \code chain != NULL \endcode | ||
859 | * \retval FLAC__bool | ||
860 | * \c true if the write succeeded, else \c false. On failure, | ||
861 | * check the status with FLAC__metadata_chain_status(). | ||
862 | */ | ||
863 | FLAC_API FLAC__bool FLAC__metadata_chain_write_with_callbacks_and_tempfile(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks, FLAC__IOHandle temp_handle, FLAC__IOCallbacks temp_callbacks); | ||
864 | |||
865 | /** Merge adjacent PADDING blocks into a single block. | ||
866 | * | ||
867 | * \note This function does not write to the FLAC file, it only | ||
868 | * modifies the chain. | ||
869 | * | ||
870 | * \warning Any iterator on the current chain will become invalid after this | ||
871 | * call. You should delete the iterator and get a new one. | ||
872 | * | ||
873 | * \param chain A pointer to an existing chain. | ||
874 | * \assert | ||
875 | * \code chain != NULL \endcode | ||
876 | */ | ||
877 | FLAC_API void FLAC__metadata_chain_merge_padding(FLAC__Metadata_Chain *chain); | ||
878 | |||
879 | /** This function will move all PADDING blocks to the end on the metadata, | ||
880 | * then merge them into a single block. | ||
881 | * | ||
882 | * \note This function does not write to the FLAC file, it only | ||
883 | * modifies the chain. | ||
884 | * | ||
885 | * \warning Any iterator on the current chain will become invalid after this | ||
886 | * call. You should delete the iterator and get a new one. | ||
887 | * | ||
888 | * \param chain A pointer to an existing chain. | ||
889 | * \assert | ||
890 | * \code chain != NULL \endcode | ||
891 | */ | ||
892 | FLAC_API void FLAC__metadata_chain_sort_padding(FLAC__Metadata_Chain *chain); | ||
893 | |||
894 | |||
895 | /*********** FLAC__Metadata_Iterator ***********/ | ||
896 | |||
897 | /** Create a new iterator instance. | ||
898 | * | ||
899 | * \retval FLAC__Metadata_Iterator* | ||
900 | * \c NULL if there was an error allocating memory, else the new instance. | ||
901 | */ | ||
902 | FLAC_API FLAC__Metadata_Iterator *FLAC__metadata_iterator_new(); | ||
903 | |||
904 | /** Free an iterator instance. Deletes the object pointed to by \a iterator. | ||
905 | * | ||
906 | * \param iterator A pointer to an existing iterator. | ||
907 | * \assert | ||
908 | * \code iterator != NULL \endcode | ||
909 | */ | ||
910 | FLAC_API void FLAC__metadata_iterator_delete(FLAC__Metadata_Iterator *iterator); | ||
911 | |||
912 | /** Initialize the iterator to point to the first metadata block in the | ||
913 | * given chain. | ||
914 | * | ||
915 | * \param iterator A pointer to an existing iterator. | ||
916 | * \param chain A pointer to an existing and initialized (read) chain. | ||
917 | * \assert | ||
918 | * \code iterator != NULL \endcode | ||
919 | * \code chain != NULL \endcode | ||
920 | */ | ||
921 | FLAC_API void FLAC__metadata_iterator_init(FLAC__Metadata_Iterator *iterator, FLAC__Metadata_Chain *chain); | ||
922 | |||
923 | /** Moves the iterator forward one metadata block, returning \c false if | ||
924 | * already at the end. | ||
925 | * | ||
926 | * \param iterator A pointer to an existing initialized iterator. | ||
927 | * \assert | ||
928 | * \code iterator != NULL \endcode | ||
929 | * \a iterator has been successfully initialized with | ||
930 | * FLAC__metadata_iterator_init() | ||
931 | * \retval FLAC__bool | ||
932 | * \c false if already at the last metadata block of the chain, else | ||
933 | * \c true. | ||
934 | */ | ||
935 | FLAC_API FLAC__bool FLAC__metadata_iterator_next(FLAC__Metadata_Iterator *iterator); | ||
936 | |||
937 | /** Moves the iterator backward one metadata block, returning \c false if | ||
938 | * already at the beginning. | ||
939 | * | ||
940 | * \param iterator A pointer to an existing initialized iterator. | ||
941 | * \assert | ||
942 | * \code iterator != NULL \endcode | ||
943 | * \a iterator has been successfully initialized with | ||
944 | * FLAC__metadata_iterator_init() | ||
945 | * \retval FLAC__bool | ||
946 | * \c false if already at the first metadata block of the chain, else | ||
947 | * \c true. | ||
948 | */ | ||
949 | FLAC_API FLAC__bool FLAC__metadata_iterator_prev(FLAC__Metadata_Iterator *iterator); | ||
950 | |||
951 | /** Get the type of the metadata block at the current position. | ||
952 | * | ||
953 | * \param iterator A pointer to an existing initialized iterator. | ||
954 | * \assert | ||
955 | * \code iterator != NULL \endcode | ||
956 | * \a iterator has been successfully initialized with | ||
957 | * FLAC__metadata_iterator_init() | ||
958 | * \retval FLAC__MetadataType | ||
959 | * The type of the metadata block at the current iterator position. | ||
960 | */ | ||
961 | FLAC_API FLAC__MetadataType FLAC__metadata_iterator_get_block_type(const FLAC__Metadata_Iterator *iterator); | ||
962 | |||
963 | /** Get the metadata block at the current position. You can modify | ||
964 | * the block in place but must write the chain before the changes | ||
965 | * are reflected to the FLAC file. You do not need to call | ||
966 | * FLAC__metadata_iterator_set_block() to reflect the changes; | ||
967 | * the pointer returned by FLAC__metadata_iterator_get_block() | ||
968 | * points directly into the chain. | ||
969 | * | ||
970 | * \warning | ||
971 | * Do not call FLAC__metadata_object_delete() on the returned object; | ||
972 | * to delete a block use FLAC__metadata_iterator_delete_block(). | ||
973 | * | ||
974 | * \param iterator A pointer to an existing initialized iterator. | ||
975 | * \assert | ||
976 | * \code iterator != NULL \endcode | ||
977 | * \a iterator has been successfully initialized with | ||
978 | * FLAC__metadata_iterator_init() | ||
979 | * \retval FLAC__StreamMetadata* | ||
980 | * The current metadata block. | ||
981 | */ | ||
982 | FLAC_API FLAC__StreamMetadata *FLAC__metadata_iterator_get_block(FLAC__Metadata_Iterator *iterator); | ||
983 | |||
984 | /** Set the metadata block at the current position, replacing the existing | ||
985 | * block. The new block passed in becomes owned by the chain and it will be | ||
986 | * deleted when the chain is deleted. | ||
987 | * | ||
988 | * \param iterator A pointer to an existing initialized iterator. | ||
989 | * \param block A pointer to a metadata block. | ||
990 | * \assert | ||
991 | * \code iterator != NULL \endcode | ||
992 | * \a iterator has been successfully initialized with | ||
993 | * FLAC__metadata_iterator_init() | ||
994 | * \code block != NULL \endcode | ||
995 | * \retval FLAC__bool | ||
996 | * \c false if the conditions in the above description are not met, or | ||
997 | * a memory allocation error occurs, otherwise \c true. | ||
998 | */ | ||
999 | FLAC_API FLAC__bool FLAC__metadata_iterator_set_block(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block); | ||
1000 | |||
1001 | /** Removes the current block from the chain. If \a replace_with_padding is | ||
1002 | * \c true, the block will instead be replaced with a padding block of equal | ||
1003 | * size. You can not delete the STREAMINFO block. The iterator will be | ||
1004 | * left pointing to the block before the one just "deleted", even if | ||
1005 | * \a replace_with_padding is \c true. | ||
1006 | * | ||
1007 | * \param iterator A pointer to an existing initialized iterator. | ||
1008 | * \param replace_with_padding See above. | ||
1009 | * \assert | ||
1010 | * \code iterator != NULL \endcode | ||
1011 | * \a iterator has been successfully initialized with | ||
1012 | * FLAC__metadata_iterator_init() | ||
1013 | * \retval FLAC__bool | ||
1014 | * \c false if the conditions in the above description are not met, | ||
1015 | * otherwise \c true. | ||
1016 | */ | ||
1017 | FLAC_API FLAC__bool FLAC__metadata_iterator_delete_block(FLAC__Metadata_Iterator *iterator, FLAC__bool replace_with_padding); | ||
1018 | |||
1019 | /** Insert a new block before the current block. You cannot insert a block | ||
1020 | * before the first STREAMINFO block. You cannot insert a STREAMINFO block | ||
1021 | * as there can be only one, the one that already exists at the head when you | ||
1022 | * read in a chain. The chain takes ownership of the new block and it will be | ||
1023 | * deleted when the chain is deleted. The iterator will be left pointing to | ||
1024 | * the new block. | ||
1025 | * | ||
1026 | * \param iterator A pointer to an existing initialized iterator. | ||
1027 | * \param block A pointer to a metadata block to insert. | ||
1028 | * \assert | ||
1029 | * \code iterator != NULL \endcode | ||
1030 | * \a iterator has been successfully initialized with | ||
1031 | * FLAC__metadata_iterator_init() | ||
1032 | * \retval FLAC__bool | ||
1033 | * \c false if the conditions in the above description are not met, or | ||
1034 | * a memory allocation error occurs, otherwise \c true. | ||
1035 | */ | ||
1036 | FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_before(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block); | ||
1037 | |||
1038 | /** Insert a new block after the current block. You cannot insert a STREAMINFO | ||
1039 | * block as there can be only one, the one that already exists at the head when | ||
1040 | * you read in a chain. The chain takes ownership of the new block and it will | ||
1041 | * be deleted when the chain is deleted. The iterator will be left pointing to | ||
1042 | * the new block. | ||
1043 | * | ||
1044 | * \param iterator A pointer to an existing initialized iterator. | ||
1045 | * \param block A pointer to a metadata block to insert. | ||
1046 | * \assert | ||
1047 | * \code iterator != NULL \endcode | ||
1048 | * \a iterator has been successfully initialized with | ||
1049 | * FLAC__metadata_iterator_init() | ||
1050 | * \retval FLAC__bool | ||
1051 | * \c false if the conditions in the above description are not met, or | ||
1052 | * a memory allocation error occurs, otherwise \c true. | ||
1053 | */ | ||
1054 | FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_after(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block); | ||
1055 | |||
1056 | /* \} */ | ||
1057 | |||
1058 | |||
1059 | /** \defgroup flac_metadata_object FLAC/metadata.h: metadata object methods | ||
1060 | * \ingroup flac_metadata | ||
1061 | * | ||
1062 | * \brief | ||
1063 | * This module contains methods for manipulating FLAC metadata objects. | ||
1064 | * | ||
1065 | * Since many are variable length we have to be careful about the memory | ||
1066 | * management. We decree that all pointers to data in the object are | ||
1067 | * owned by the object and memory-managed by the object. | ||
1068 | * | ||
1069 | * Use the FLAC__metadata_object_new() and FLAC__metadata_object_delete() | ||
1070 | * functions to create all instances. When using the | ||
1071 | * FLAC__metadata_object_set_*() functions to set pointers to data, set | ||
1072 | * \a copy to \c true to have the function make it's own copy of the data, or | ||
1073 | * to \c false to give the object ownership of your data. In the latter case | ||
1074 | * your pointer must be freeable by free() and will be free()d when the object | ||
1075 | * is FLAC__metadata_object_delete()d. It is legal to pass a null pointer as | ||
1076 | * the data pointer to a FLAC__metadata_object_set_*() function as long as | ||
1077 | * the length argument is 0 and the \a copy argument is \c false. | ||
1078 | * | ||
1079 | * The FLAC__metadata_object_new() and FLAC__metadata_object_clone() function | ||
1080 | * will return \c NULL in the case of a memory allocation error, otherwise a new | ||
1081 | * object. The FLAC__metadata_object_set_*() functions return \c false in the | ||
1082 | * case of a memory allocation error. | ||
1083 | * | ||
1084 | * We don't have the convenience of C++ here, so note that the library relies | ||
1085 | * on you to keep the types straight. In other words, if you pass, for | ||
1086 | * example, a FLAC__StreamMetadata* that represents a STREAMINFO block to | ||
1087 | * FLAC__metadata_object_application_set_data(), you will get an assertion | ||
1088 | * failure. | ||
1089 | * | ||
1090 | * For convenience the FLAC__metadata_object_vorbiscomment_*() functions | ||
1091 | * maintain a trailing NUL on each Vorbis comment entry. This is not counted | ||
1092 | * toward the length or stored in the stream, but it can make working with plain | ||
1093 | * comments (those that don't contain embedded-NULs in the value) easier. | ||
1094 | * Entries passed into these functions have trailing NULs added if missing, and | ||
1095 | * returned entries are guaranteed to have a trailing NUL. | ||
1096 | * | ||
1097 | * The FLAC__metadata_object_vorbiscomment_*() functions that take a Vorbis | ||
1098 | * comment entry/name/value will first validate that it complies with the Vorbis | ||
1099 | * comment specification and return false if it does not. | ||
1100 | * | ||
1101 | * There is no need to recalculate the length field on metadata blocks you | ||
1102 | * have modified. They will be calculated automatically before they are | ||
1103 | * written back to a file. | ||
1104 | * | ||
1105 | * \{ | ||
1106 | */ | ||
1107 | |||
1108 | |||
1109 | /** Create a new metadata object instance of the given type. | ||
1110 | * | ||
1111 | * The object will be "empty"; i.e. values and data pointers will be \c 0, | ||
1112 | * with the exception of FLAC__METADATA_TYPE_VORBIS_COMMENT, which will have | ||
1113 | * the vendor string set (but zero comments). | ||
1114 | * | ||
1115 | * Do not pass in a value greater than or equal to | ||
1116 | * \a FLAC__METADATA_TYPE_UNDEFINED unless you really know what you're | ||
1117 | * doing. | ||
1118 | * | ||
1119 | * \param type Type of object to create | ||
1120 | * \retval FLAC__StreamMetadata* | ||
1121 | * \c NULL if there was an error allocating memory or the type code is | ||
1122 | * greater than FLAC__MAX_METADATA_TYPE_CODE, else the new instance. | ||
1123 | */ | ||
1124 | FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_new(FLAC__MetadataType type); | ||
1125 | |||
1126 | /** Create a copy of an existing metadata object. | ||
1127 | * | ||
1128 | * The copy is a "deep" copy, i.e. dynamically allocated data within the | ||
1129 | * object is also copied. The caller takes ownership of the new block and | ||
1130 | * is responsible for freeing it with FLAC__metadata_object_delete(). | ||
1131 | * | ||
1132 | * \param object Pointer to object to copy. | ||
1133 | * \assert | ||
1134 | * \code object != NULL \endcode | ||
1135 | * \retval FLAC__StreamMetadata* | ||
1136 | * \c NULL if there was an error allocating memory, else the new instance. | ||
1137 | */ | ||
1138 | FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_clone(const FLAC__StreamMetadata *object); | ||
1139 | |||
1140 | /** Free a metadata object. Deletes the object pointed to by \a object. | ||
1141 | * | ||
1142 | * The delete is a "deep" delete, i.e. dynamically allocated data within the | ||
1143 | * object is also deleted. | ||
1144 | * | ||
1145 | * \param object A pointer to an existing object. | ||
1146 | * \assert | ||
1147 | * \code object != NULL \endcode | ||
1148 | */ | ||
1149 | FLAC_API void FLAC__metadata_object_delete(FLAC__StreamMetadata *object); | ||
1150 | |||
1151 | /** Compares two metadata objects. | ||
1152 | * | ||
1153 | * The compare is "deep", i.e. dynamically allocated data within the | ||
1154 | * object is also compared. | ||
1155 | * | ||
1156 | * \param block1 A pointer to an existing object. | ||
1157 | * \param block2 A pointer to an existing object. | ||
1158 | * \assert | ||
1159 | * \code block1 != NULL \endcode | ||
1160 | * \code block2 != NULL \endcode | ||
1161 | * \retval FLAC__bool | ||
1162 | * \c true if objects are identical, else \c false. | ||
1163 | */ | ||
1164 | FLAC_API FLAC__bool FLAC__metadata_object_is_equal(const FLAC__StreamMetadata *block1, const FLAC__StreamMetadata *block2); | ||
1165 | |||
1166 | /** Sets the application data of an APPLICATION block. | ||
1167 | * | ||
1168 | * If \a copy is \c true, a copy of the data is stored; otherwise, the object | ||
1169 | * takes ownership of the pointer. | ||
1170 | * | ||
1171 | * \param object A pointer to an existing APPLICATION object. | ||
1172 | * \param data A pointer to the data to set. | ||
1173 | * \param length The length of \a data in bytes. | ||
1174 | * \param copy See above. | ||
1175 | * \assert | ||
1176 | * \code object != NULL \endcode | ||
1177 | * \code object->type == FLAC__METADATA_TYPE_APPLICATION \endcode | ||
1178 | * \code (data != NULL && length > 0) || | ||
1179 | * (data == NULL && length == 0 && copy == false) \endcode | ||
1180 | * \retval FLAC__bool | ||
1181 | * \c false if \a copy is \c true and malloc() fails, else \c true. | ||
1182 | */ | ||
1183 | FLAC_API FLAC__bool FLAC__metadata_object_application_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, unsigned length, FLAC__bool copy); | ||
1184 | |||
1185 | /** Resize the seekpoint array. | ||
1186 | * | ||
1187 | * If the size shrinks, elements will truncated; if it grows, new placeholder | ||
1188 | * points will be added to the end. | ||
1189 | * | ||
1190 | * \param object A pointer to an existing SEEKTABLE object. | ||
1191 | * \param new_num_points The desired length of the array; may be \c 0. | ||
1192 | * \assert | ||
1193 | * \code object != NULL \endcode | ||
1194 | * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode | ||
1195 | * \code (object->data.seek_table.points == NULL && object->data.seek_table.num_points == 0) || | ||
1196 | * (object->data.seek_table.points != NULL && object->data.seek_table.num_points > 0) \endcode | ||
1197 | * \retval FLAC__bool | ||
1198 | * \c false if memory allocation error, else \c true. | ||
1199 | */ | ||
1200 | FLAC_API FLAC__bool FLAC__metadata_object_seektable_resize_points(FLAC__StreamMetadata *object, unsigned new_num_points); | ||
1201 | |||
1202 | /** Set a seekpoint in a seektable. | ||
1203 | * | ||
1204 | * \param object A pointer to an existing SEEKTABLE object. | ||
1205 | * \param point_num Index into seekpoint array to set. | ||
1206 | * \param point The point to set. | ||
1207 | * \assert | ||
1208 | * \code object != NULL \endcode | ||
1209 | * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode | ||
1210 | * \code object->data.seek_table.num_points > point_num \endcode | ||
1211 | */ | ||
1212 | FLAC_API void FLAC__metadata_object_seektable_set_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point); | ||
1213 | |||
1214 | /** Insert a seekpoint into a seektable. | ||
1215 | * | ||
1216 | * \param object A pointer to an existing SEEKTABLE object. | ||
1217 | * \param point_num Index into seekpoint array to set. | ||
1218 | * \param point The point to set. | ||
1219 | * \assert | ||
1220 | * \code object != NULL \endcode | ||
1221 | * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode | ||
1222 | * \code object->data.seek_table.num_points >= point_num \endcode | ||
1223 | * \retval FLAC__bool | ||
1224 | * \c false if memory allocation error, else \c true. | ||
1225 | */ | ||
1226 | FLAC_API FLAC__bool FLAC__metadata_object_seektable_insert_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point); | ||
1227 | |||
1228 | /** Delete a seekpoint from a seektable. | ||
1229 | * | ||
1230 | * \param object A pointer to an existing SEEKTABLE object. | ||
1231 | * \param point_num Index into seekpoint array to set. | ||
1232 | * \assert | ||
1233 | * \code object != NULL \endcode | ||
1234 | * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode | ||
1235 | * \code object->data.seek_table.num_points > point_num \endcode | ||
1236 | * \retval FLAC__bool | ||
1237 | * \c false if memory allocation error, else \c true. | ||
1238 | */ | ||
1239 | FLAC_API FLAC__bool FLAC__metadata_object_seektable_delete_point(FLAC__StreamMetadata *object, unsigned point_num); | ||
1240 | |||
1241 | /** Check a seektable to see if it conforms to the FLAC specification. | ||
1242 | * See the format specification for limits on the contents of the | ||
1243 | * seektable. | ||
1244 | * | ||
1245 | * \param object A pointer to an existing SEEKTABLE object. | ||
1246 | * \assert | ||
1247 | * \code object != NULL \endcode | ||
1248 | * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode | ||
1249 | * \retval FLAC__bool | ||
1250 | * \c false if seek table is illegal, else \c true. | ||
1251 | */ | ||
1252 | FLAC_API FLAC__bool FLAC__metadata_object_seektable_is_legal(const FLAC__StreamMetadata *object); | ||
1253 | |||
1254 | /** Append a number of placeholder points to the end of a seek table. | ||
1255 | * | ||
1256 | * \note | ||
1257 | * As with the other ..._seektable_template_... functions, you should | ||
1258 | * call FLAC__metadata_object_seektable_template_sort() when finished | ||
1259 | * to make the seek table legal. | ||
1260 | * | ||
1261 | * \param object A pointer to an existing SEEKTABLE object. | ||
1262 | * \param num The number of placeholder points to append. | ||
1263 | * \assert | ||
1264 | * \code object != NULL \endcode | ||
1265 | * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode | ||
1266 | * \retval FLAC__bool | ||
1267 | * \c false if memory allocation fails, else \c true. | ||
1268 | */ | ||
1269 | FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_placeholders(FLAC__StreamMetadata *object, unsigned num); | ||
1270 | |||
1271 | /** Append a specific seek point template to the end of a seek table. | ||
1272 | * | ||
1273 | * \note | ||
1274 | * As with the other ..._seektable_template_... functions, you should | ||
1275 | * call FLAC__metadata_object_seektable_template_sort() when finished | ||
1276 | * to make the seek table legal. | ||
1277 | * | ||
1278 | * \param object A pointer to an existing SEEKTABLE object. | ||
1279 | * \param sample_number The sample number of the seek point template. | ||
1280 | * \assert | ||
1281 | * \code object != NULL \endcode | ||
1282 | * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode | ||
1283 | * \retval FLAC__bool | ||
1284 | * \c false if memory allocation fails, else \c true. | ||
1285 | */ | ||
1286 | FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_point(FLAC__StreamMetadata *object, FLAC__uint64 sample_number); | ||
1287 | |||
1288 | /** Append specific seek point templates to the end of a seek table. | ||
1289 | * | ||
1290 | * \note | ||
1291 | * As with the other ..._seektable_template_... functions, you should | ||
1292 | * call FLAC__metadata_object_seektable_template_sort() when finished | ||
1293 | * to make the seek table legal. | ||
1294 | * | ||
1295 | * \param object A pointer to an existing SEEKTABLE object. | ||
1296 | * \param sample_numbers An array of sample numbers for the seek points. | ||
1297 | * \param num The number of seek point templates to append. | ||
1298 | * \assert | ||
1299 | * \code object != NULL \endcode | ||
1300 | * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode | ||
1301 | * \retval FLAC__bool | ||
1302 | * \c false if memory allocation fails, else \c true. | ||
1303 | */ | ||
1304 | FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_points(FLAC__StreamMetadata *object, FLAC__uint64 sample_numbers[], unsigned num); | ||
1305 | |||
1306 | /** Append a set of evenly-spaced seek point templates to the end of a | ||
1307 | * seek table. | ||
1308 | * | ||
1309 | * \note | ||
1310 | * As with the other ..._seektable_template_... functions, you should | ||
1311 | * call FLAC__metadata_object_seektable_template_sort() when finished | ||
1312 | * to make the seek table legal. | ||
1313 | * | ||
1314 | * \param object A pointer to an existing SEEKTABLE object. | ||
1315 | * \param num The number of placeholder points to append. | ||
1316 | * \param total_samples The total number of samples to be encoded; | ||
1317 | * the seekpoints will be spaced approximately | ||
1318 | * \a total_samples / \a num samples apart. | ||
1319 | * \assert | ||
1320 | * \code object != NULL \endcode | ||
1321 | * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode | ||
1322 | * \retval FLAC__bool | ||
1323 | * \c false if memory allocation fails, else \c true. | ||
1324 | */ | ||
1325 | FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points(FLAC__StreamMetadata *object, unsigned num, FLAC__uint64 total_samples); | ||
1326 | |||
1327 | /** Sort a seek table's seek points according to the format specification, | ||
1328 | * removing duplicates. | ||
1329 | * | ||
1330 | * \param object A pointer to a seek table to be sorted. | ||
1331 | * \param compact If \c false, behaves like FLAC__format_seektable_sort(). | ||
1332 | * If \c true, duplicates are deleted and the seek table is | ||
1333 | * shrunk appropriately; the number of placeholder points | ||
1334 | * present in the seek table will be the same after the call | ||
1335 | * as before. | ||
1336 | * \assert | ||
1337 | * \code object != NULL \endcode | ||
1338 | * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode | ||
1339 | * \retval FLAC__bool | ||
1340 | * \c false if realloc() fails, else \c true. | ||
1341 | */ | ||
1342 | FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_sort(FLAC__StreamMetadata *object, FLAC__bool compact); | ||
1343 | |||
1344 | /** Sets the vendor string in a VORBIS_COMMENT block. | ||
1345 | * | ||
1346 | * For convenience, a trailing NUL is added to the entry if it doesn't have | ||
1347 | * one already. | ||
1348 | * | ||
1349 | * If \a copy is \c true, a copy of the entry is stored; otherwise, the object | ||
1350 | * takes ownership of the \c entry.entry pointer. | ||
1351 | * | ||
1352 | * \note If this function returns \c false, the caller still owns the | ||
1353 | * pointer. | ||
1354 | * | ||
1355 | * \param object A pointer to an existing VORBIS_COMMENT object. | ||
1356 | * \param entry The entry to set the vendor string to. | ||
1357 | * \param copy See above. | ||
1358 | * \assert | ||
1359 | * \code object != NULL \endcode | ||
1360 | * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode | ||
1361 | * \code (entry.entry != NULL && entry.length > 0) || | ||
1362 | * (entry.entry == NULL && entry.length == 0) \endcode | ||
1363 | * \retval FLAC__bool | ||
1364 | * \c false if memory allocation fails or \a entry does not comply with the | ||
1365 | * Vorbis comment specification, else \c true. | ||
1366 | */ | ||
1367 | FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_vendor_string(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy); | ||
1368 | |||
1369 | /** Resize the comment array. | ||
1370 | * | ||
1371 | * If the size shrinks, elements will truncated; if it grows, new empty | ||
1372 | * fields will be added to the end. | ||
1373 | * | ||
1374 | * \param object A pointer to an existing VORBIS_COMMENT object. | ||
1375 | * \param new_num_comments The desired length of the array; may be \c 0. | ||
1376 | * \assert | ||
1377 | * \code object != NULL \endcode | ||
1378 | * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode | ||
1379 | * \code (object->data.vorbis_comment.comments == NULL && object->data.vorbis_comment.num_comments == 0) || | ||
1380 | * (object->data.vorbis_comment.comments != NULL && object->data.vorbis_comment.num_comments > 0) \endcode | ||
1381 | * \retval FLAC__bool | ||
1382 | * \c false if memory allocation fails, else \c true. | ||
1383 | */ | ||
1384 | FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_resize_comments(FLAC__StreamMetadata *object, unsigned new_num_comments); | ||
1385 | |||
1386 | /** Sets a comment in a VORBIS_COMMENT block. | ||
1387 | * | ||
1388 | * For convenience, a trailing NUL is added to the entry if it doesn't have | ||
1389 | * one already. | ||
1390 | * | ||
1391 | * If \a copy is \c true, a copy of the entry is stored; otherwise, the object | ||
1392 | * takes ownership of the \c entry.entry pointer. | ||
1393 | * | ||
1394 | * \note If this function returns \c false, the caller still owns the | ||
1395 | * pointer. | ||
1396 | * | ||
1397 | * \param object A pointer to an existing VORBIS_COMMENT object. | ||
1398 | * \param comment_num Index into comment array to set. | ||
1399 | * \param entry The entry to set the comment to. | ||
1400 | * \param copy See above. | ||
1401 | * \assert | ||
1402 | * \code object != NULL \endcode | ||
1403 | * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode | ||
1404 | * \code comment_num < object->data.vorbis_comment.num_comments \endcode | ||
1405 | * \code (entry.entry != NULL && entry.length > 0) || | ||
1406 | * (entry.entry == NULL && entry.length == 0) \endcode | ||
1407 | * \retval FLAC__bool | ||
1408 | * \c false if memory allocation fails or \a entry does not comply with the | ||
1409 | * Vorbis comment specification, else \c true. | ||
1410 | */ | ||
1411 | FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy); | ||
1412 | |||
1413 | /** Insert a comment in a VORBIS_COMMENT block at the given index. | ||
1414 | * | ||
1415 | * For convenience, a trailing NUL is added to the entry if it doesn't have | ||
1416 | * one already. | ||
1417 | * | ||
1418 | * If \a copy is \c true, a copy of the entry is stored; otherwise, the object | ||
1419 | * takes ownership of the \c entry.entry pointer. | ||
1420 | * | ||
1421 | * \note If this function returns \c false, the caller still owns the | ||
1422 | * pointer. | ||
1423 | * | ||
1424 | * \param object A pointer to an existing VORBIS_COMMENT object. | ||
1425 | * \param comment_num The index at which to insert the comment. The comments | ||
1426 | * at and after \a comment_num move right one position. | ||
1427 | * To append a comment to the end, set \a comment_num to | ||
1428 | * \c object->data.vorbis_comment.num_comments . | ||
1429 | * \param entry The comment to insert. | ||
1430 | * \param copy See above. | ||
1431 | * \assert | ||
1432 | * \code object != NULL \endcode | ||
1433 | * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode | ||
1434 | * \code object->data.vorbis_comment.num_comments >= comment_num \endcode | ||
1435 | * \code (entry.entry != NULL && entry.length > 0) || | ||
1436 | * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode | ||
1437 | * \retval FLAC__bool | ||
1438 | * \c false if memory allocation fails or \a entry does not comply with the | ||
1439 | * Vorbis comment specification, else \c true. | ||
1440 | */ | ||
1441 | FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_insert_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy); | ||
1442 | |||
1443 | /** Appends a comment to a VORBIS_COMMENT block. | ||
1444 | * | ||
1445 | * For convenience, a trailing NUL is added to the entry if it doesn't have | ||
1446 | * one already. | ||
1447 | * | ||
1448 | * If \a copy is \c true, a copy of the entry is stored; otherwise, the object | ||
1449 | * takes ownership of the \c entry.entry pointer. | ||
1450 | * | ||
1451 | * \note If this function returns \c false, the caller still owns the | ||
1452 | * pointer. | ||
1453 | * | ||
1454 | * \param object A pointer to an existing VORBIS_COMMENT object. | ||
1455 | * \param entry The comment to insert. | ||
1456 | * \param copy See above. | ||
1457 | * \assert | ||
1458 | * \code object != NULL \endcode | ||
1459 | * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode | ||
1460 | * \code (entry.entry != NULL && entry.length > 0) || | ||
1461 | * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode | ||
1462 | * \retval FLAC__bool | ||
1463 | * \c false if memory allocation fails or \a entry does not comply with the | ||
1464 | * Vorbis comment specification, else \c true. | ||
1465 | */ | ||
1466 | FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_append_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy); | ||
1467 | |||
1468 | /** Replaces comments in a VORBIS_COMMENT block with a new one. | ||
1469 | * | ||
1470 | * For convenience, a trailing NUL is added to the entry if it doesn't have | ||
1471 | * one already. | ||
1472 | * | ||
1473 | * Depending on the the value of \a all, either all or just the first comment | ||
1474 | * whose field name(s) match the given entry's name will be replaced by the | ||
1475 | * given entry. If no comments match, \a entry will simply be appended. | ||
1476 | * | ||
1477 | * If \a copy is \c true, a copy of the entry is stored; otherwise, the object | ||
1478 | * takes ownership of the \c entry.entry pointer. | ||
1479 | * | ||
1480 | * \note If this function returns \c false, the caller still owns the | ||
1481 | * pointer. | ||
1482 | * | ||
1483 | * \param object A pointer to an existing VORBIS_COMMENT object. | ||
1484 | * \param entry The comment to insert. | ||
1485 | * \param all If \c true, all comments whose field name matches | ||
1486 | * \a entry's field name will be removed, and \a entry will | ||
1487 | * be inserted at the position of the first matching | ||
1488 | * comment. If \c false, only the first comment whose | ||
1489 | * field name matches \a entry's field name will be | ||
1490 | * replaced with \a entry. | ||
1491 | * \param copy See above. | ||
1492 | * \assert | ||
1493 | * \code object != NULL \endcode | ||
1494 | * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode | ||
1495 | * \code (entry.entry != NULL && entry.length > 0) || | ||
1496 | * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode | ||
1497 | * \retval FLAC__bool | ||
1498 | * \c false if memory allocation fails or \a entry does not comply with the | ||
1499 | * Vorbis comment specification, else \c true. | ||
1500 | */ | ||
1501 | FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_replace_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool all, FLAC__bool copy); | ||
1502 | |||
1503 | /** Delete a comment in a VORBIS_COMMENT block at the given index. | ||
1504 | * | ||
1505 | * \param object A pointer to an existing VORBIS_COMMENT object. | ||
1506 | * \param comment_num The index of the comment to delete. | ||
1507 | * \assert | ||
1508 | * \code object != NULL \endcode | ||
1509 | * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode | ||
1510 | * \code object->data.vorbis_comment.num_comments > comment_num \endcode | ||
1511 | * \retval FLAC__bool | ||
1512 | * \c false if realloc() fails, else \c true. | ||
1513 | */ | ||
1514 | FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_delete_comment(FLAC__StreamMetadata *object, unsigned comment_num); | ||
1515 | |||
1516 | /** Creates a Vorbis comment entry from NUL-terminated name and value strings. | ||
1517 | * | ||
1518 | * On return, the filled-in \a entry->entry pointer will point to malloc()ed | ||
1519 | * memory and shall be owned by the caller. For convenience the entry will | ||
1520 | * have a terminating NUL. | ||
1521 | * | ||
1522 | * \param entry A pointer to a Vorbis comment entry. The entry's | ||
1523 | * \c entry pointer should not point to allocated | ||
1524 | * memory as it will be overwritten. | ||
1525 | * \param field_name The field name in ASCII, \c NUL terminated. | ||
1526 | * \param field_value The field value in UTF-8, \c NUL terminated. | ||
1527 | * \assert | ||
1528 | * \code entry != NULL \endcode | ||
1529 | * \code field_name != NULL \endcode | ||
1530 | * \code field_value != NULL \endcode | ||
1531 | * \retval FLAC__bool | ||
1532 | * \c false if malloc() fails, or if \a field_name or \a field_value does | ||
1533 | * not comply with the Vorbis comment specification, else \c true. | ||
1534 | */ | ||
1535 | FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_from_name_value_pair(FLAC__StreamMetadata_VorbisComment_Entry *entry, const char *field_name, const char *field_value); | ||
1536 | |||
1537 | /** Splits a Vorbis comment entry into NUL-terminated name and value strings. | ||
1538 | * | ||
1539 | * The returned pointers to name and value will be allocated by malloc() | ||
1540 | * and shall be owned by the caller. | ||
1541 | * | ||
1542 | * \param entry An existing Vorbis comment entry. | ||
1543 | * \param field_name The address of where the returned pointer to the | ||
1544 | * field name will be stored. | ||
1545 | * \param field_value The address of where the returned pointer to the | ||
1546 | * field value will be stored. | ||
1547 | * \assert | ||
1548 | * \code (entry.entry != NULL && entry.length > 0) \endcode | ||
1549 | * \code memchr(entry.entry, '=', entry.length) != NULL \endcode | ||
1550 | * \code field_name != NULL \endcode | ||
1551 | * \code field_value != NULL \endcode | ||
1552 | * \retval FLAC__bool | ||
1553 | * \c false if memory allocation fails or \a entry does not comply with the | ||
1554 | * Vorbis comment specification, else \c true. | ||
1555 | */ | ||
1556 | FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_to_name_value_pair(const FLAC__StreamMetadata_VorbisComment_Entry entry, char **field_name, char **field_value); | ||
1557 | |||
1558 | /** Check if the given Vorbis comment entry's field name matches the given | ||
1559 | * field name. | ||
1560 | * | ||
1561 | * \param entry An existing Vorbis comment entry. | ||
1562 | * \param field_name The field name to check. | ||
1563 | * \param field_name_length The length of \a field_name, not including the | ||
1564 | * terminating \c NUL. | ||
1565 | * \assert | ||
1566 | * \code (entry.entry != NULL && entry.length > 0) \endcode | ||
1567 | * \retval FLAC__bool | ||
1568 | * \c true if the field names match, else \c false | ||
1569 | */ | ||
1570 | FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_matches(const FLAC__StreamMetadata_VorbisComment_Entry entry, const char *field_name, unsigned field_name_length); | ||
1571 | |||
1572 | /** Find a Vorbis comment with the given field name. | ||
1573 | * | ||
1574 | * The search begins at entry number \a offset; use an offset of 0 to | ||
1575 | * search from the beginning of the comment array. | ||
1576 | * | ||
1577 | * \param object A pointer to an existing VORBIS_COMMENT object. | ||
1578 | * \param offset The offset into the comment array from where to start | ||
1579 | * the search. | ||
1580 | * \param field_name The field name of the comment to find. | ||
1581 | * \assert | ||
1582 | * \code object != NULL \endcode | ||
1583 | * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode | ||
1584 | * \code field_name != NULL \endcode | ||
1585 | * \retval int | ||
1586 | * The offset in the comment array of the first comment whose field | ||
1587 | * name matches \a field_name, or \c -1 if no match was found. | ||
1588 | */ | ||
1589 | FLAC_API int FLAC__metadata_object_vorbiscomment_find_entry_from(const FLAC__StreamMetadata *object, unsigned offset, const char *field_name); | ||
1590 | |||
1591 | /** Remove first Vorbis comment matching the given field name. | ||
1592 | * | ||
1593 | * \param object A pointer to an existing VORBIS_COMMENT object. | ||
1594 | * \param field_name The field name of comment to delete. | ||
1595 | * \assert | ||
1596 | * \code object != NULL \endcode | ||
1597 | * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode | ||
1598 | * \retval int | ||
1599 | * \c -1 for memory allocation error, \c 0 for no matching entries, | ||
1600 | * \c 1 for one matching entry deleted. | ||
1601 | */ | ||
1602 | FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entry_matching(FLAC__StreamMetadata *object, const char *field_name); | ||
1603 | |||
1604 | /** Remove all Vorbis comments matching the given field name. | ||
1605 | * | ||
1606 | * \param object A pointer to an existing VORBIS_COMMENT object. | ||
1607 | * \param field_name The field name of comments to delete. | ||
1608 | * \assert | ||
1609 | * \code object != NULL \endcode | ||
1610 | * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode | ||
1611 | * \retval int | ||
1612 | * \c -1 for memory allocation error, \c 0 for no matching entries, | ||
1613 | * else the number of matching entries deleted. | ||
1614 | */ | ||
1615 | FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entries_matching(FLAC__StreamMetadata *object, const char *field_name); | ||
1616 | |||
1617 | /** Create a new CUESHEET track instance. | ||
1618 | * | ||
1619 | * The object will be "empty"; i.e. values and data pointers will be \c 0. | ||
1620 | * | ||
1621 | * \retval FLAC__StreamMetadata_CueSheet_Track* | ||
1622 | * \c NULL if there was an error allocating memory, else the new instance. | ||
1623 | */ | ||
1624 | FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_new(); | ||
1625 | |||
1626 | /** Create a copy of an existing CUESHEET track object. | ||
1627 | * | ||
1628 | * The copy is a "deep" copy, i.e. dynamically allocated data within the | ||
1629 | * object is also copied. The caller takes ownership of the new object and | ||
1630 | * is responsible for freeing it with | ||
1631 | * FLAC__metadata_object_cuesheet_track_delete(). | ||
1632 | * | ||
1633 | * \param object Pointer to object to copy. | ||
1634 | * \assert | ||
1635 | * \code object != NULL \endcode | ||
1636 | * \retval FLAC__StreamMetadata_CueSheet_Track* | ||
1637 | * \c NULL if there was an error allocating memory, else the new instance. | ||
1638 | */ | ||
1639 | FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_clone(const FLAC__StreamMetadata_CueSheet_Track *object); | ||
1640 | |||
1641 | /** Delete a CUESHEET track object | ||
1642 | * | ||
1643 | * \param object A pointer to an existing CUESHEET track object. | ||
1644 | * \assert | ||
1645 | * \code object != NULL \endcode | ||
1646 | */ | ||
1647 | FLAC_API void FLAC__metadata_object_cuesheet_track_delete(FLAC__StreamMetadata_CueSheet_Track *object); | ||
1648 | |||
1649 | /** Resize a track's index point array. | ||
1650 | * | ||
1651 | * If the size shrinks, elements will truncated; if it grows, new blank | ||
1652 | * indices will be added to the end. | ||
1653 | * | ||
1654 | * \param object A pointer to an existing CUESHEET object. | ||
1655 | * \param track_num The index of the track to modify. NOTE: this is not | ||
1656 | * necessarily the same as the track's \a number field. | ||
1657 | * \param new_num_indices The desired length of the array; may be \c 0. | ||
1658 | * \assert | ||
1659 | * \code object != NULL \endcode | ||
1660 | * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode | ||
1661 | * \code object->data.cue_sheet.num_tracks > track_num \endcode | ||
1662 | * \code (object->data.cue_sheet.tracks[track_num].indices == NULL && object->data.cue_sheet.tracks[track_num].num_indices == 0) || | ||
1663 | * (object->data.cue_sheet.tracks[track_num].indices != NULL && object->data.cue_sheet.tracks[track_num].num_indices > 0) \endcode | ||
1664 | * \retval FLAC__bool | ||
1665 | * \c false if memory allocation error, else \c true. | ||
1666 | */ | ||
1667 | FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_resize_indices(FLAC__StreamMetadata *object, unsigned track_num, unsigned new_num_indices); | ||
1668 | |||
1669 | /** Insert an index point in a CUESHEET track at the given index. | ||
1670 | * | ||
1671 | * \param object A pointer to an existing CUESHEET object. | ||
1672 | * \param track_num The index of the track to modify. NOTE: this is not | ||
1673 | * necessarily the same as the track's \a number field. | ||
1674 | * \param index_num The index into the track's index array at which to | ||
1675 | * insert the index point. NOTE: this is not necessarily | ||
1676 | * the same as the index point's \a number field. The | ||
1677 | * indices at and after \a index_num move right one | ||
1678 | * position. To append an index point to the end, set | ||
1679 | * \a index_num to | ||
1680 | * \c object->data.cue_sheet.tracks[track_num].num_indices . | ||
1681 | * \param index The index point to insert. | ||
1682 | * \assert | ||
1683 | * \code object != NULL \endcode | ||
1684 | * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode | ||
1685 | * \code object->data.cue_sheet.num_tracks > track_num \endcode | ||
1686 | * \code object->data.cue_sheet.tracks[track_num].num_indices >= index_num \endcode | ||
1687 | * \retval FLAC__bool | ||
1688 | * \c false if realloc() fails, else \c true. | ||
1689 | */ | ||
1690 | FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_insert_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num, FLAC__StreamMetadata_CueSheet_Index index); | ||
1691 | |||
1692 | /** Insert a blank index point in a CUESHEET track at the given index. | ||
1693 | * | ||
1694 | * A blank index point is one in which all field values are zero. | ||
1695 | * | ||
1696 | * \param object A pointer to an existing CUESHEET object. | ||
1697 | * \param track_num The index of the track to modify. NOTE: this is not | ||
1698 | * necessarily the same as the track's \a number field. | ||
1699 | * \param index_num The index into the track's index array at which to | ||
1700 | * insert the index point. NOTE: this is not necessarily | ||
1701 | * the same as the index point's \a number field. The | ||
1702 | * indices at and after \a index_num move right one | ||
1703 | * position. To append an index point to the end, set | ||
1704 | * \a index_num to | ||
1705 | * \c object->data.cue_sheet.tracks[track_num].num_indices . | ||
1706 | * \assert | ||
1707 | * \code object != NULL \endcode | ||
1708 | * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode | ||
1709 | * \code object->data.cue_sheet.num_tracks > track_num \endcode | ||
1710 | * \code object->data.cue_sheet.tracks[track_num].num_indices >= index_num \endcode | ||
1711 | * \retval FLAC__bool | ||
1712 | * \c false if realloc() fails, else \c true. | ||
1713 | */ | ||
1714 | FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_insert_blank_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num); | ||
1715 | |||
1716 | /** Delete an index point in a CUESHEET track at the given index. | ||
1717 | * | ||
1718 | * \param object A pointer to an existing CUESHEET object. | ||
1719 | * \param track_num The index into the track array of the track to | ||
1720 | * modify. NOTE: this is not necessarily the same | ||
1721 | * as the track's \a number field. | ||
1722 | * \param index_num The index into the track's index array of the index | ||
1723 | * to delete. NOTE: this is not necessarily the same | ||
1724 | * as the index's \a number field. | ||
1725 | * \assert | ||
1726 | * \code object != NULL \endcode | ||
1727 | * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode | ||
1728 | * \code object->data.cue_sheet.num_tracks > track_num \endcode | ||
1729 | * \code object->data.cue_sheet.tracks[track_num].num_indices > index_num \endcode | ||
1730 | * \retval FLAC__bool | ||
1731 | * \c false if realloc() fails, else \c true. | ||
1732 | */ | ||
1733 | FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_delete_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num); | ||
1734 | |||
1735 | /** Resize the track array. | ||
1736 | * | ||
1737 | * If the size shrinks, elements will truncated; if it grows, new blank | ||
1738 | * tracks will be added to the end. | ||
1739 | * | ||
1740 | * \param object A pointer to an existing CUESHEET object. | ||
1741 | * \param new_num_tracks The desired length of the array; may be \c 0. | ||
1742 | * \assert | ||
1743 | * \code object != NULL \endcode | ||
1744 | * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode | ||
1745 | * \code (object->data.cue_sheet.tracks == NULL && object->data.cue_sheet.num_tracks == 0) || | ||
1746 | * (object->data.cue_sheet.tracks != NULL && object->data.cue_sheet.num_tracks > 0) \endcode | ||
1747 | * \retval FLAC__bool | ||
1748 | * \c false if memory allocation error, else \c true. | ||
1749 | */ | ||
1750 | FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_resize_tracks(FLAC__StreamMetadata *object, unsigned new_num_tracks); | ||
1751 | |||
1752 | /** Sets a track in a CUESHEET block. | ||
1753 | * | ||
1754 | * If \a copy is \c true, a copy of the track is stored; otherwise, the object | ||
1755 | * takes ownership of the \a track pointer. | ||
1756 | * | ||
1757 | * \param object A pointer to an existing CUESHEET object. | ||
1758 | * \param track_num Index into track array to set. NOTE: this is not | ||
1759 | * necessarily the same as the track's \a number field. | ||
1760 | * \param track The track to set the track to. You may safely pass in | ||
1761 | * a const pointer if \a copy is \c true. | ||
1762 | * \param copy See above. | ||
1763 | * \assert | ||
1764 | * \code object != NULL \endcode | ||
1765 | * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode | ||
1766 | * \code track_num < object->data.cue_sheet.num_tracks \endcode | ||
1767 | * \code (track->indices != NULL && track->num_indices > 0) || | ||
1768 | * (track->indices == NULL && track->num_indices == 0) | ||
1769 | * \retval FLAC__bool | ||
1770 | * \c false if \a copy is \c true and malloc() fails, else \c true. | ||
1771 | */ | ||
1772 | FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_set_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy); | ||
1773 | |||
1774 | /** Insert a track in a CUESHEET block at the given index. | ||
1775 | * | ||
1776 | * If \a copy is \c true, a copy of the track is stored; otherwise, the object | ||
1777 | * takes ownership of the \a track pointer. | ||
1778 | * | ||
1779 | * \param object A pointer to an existing CUESHEET object. | ||
1780 | * \param track_num The index at which to insert the track. NOTE: this | ||
1781 | * is not necessarily the same as the track's \a number | ||
1782 | * field. The tracks at and after \a track_num move right | ||
1783 | * one position. To append a track to the end, set | ||
1784 | * \a track_num to \c object->data.cue_sheet.num_tracks . | ||
1785 | * \param track The track to insert. You may safely pass in a const | ||
1786 | * pointer if \a copy is \c true. | ||
1787 | * \param copy See above. | ||
1788 | * \assert | ||
1789 | * \code object != NULL \endcode | ||
1790 | * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode | ||
1791 | * \code object->data.cue_sheet.num_tracks >= track_num \endcode | ||
1792 | * \retval FLAC__bool | ||
1793 | * \c false if \a copy is \c true and malloc() fails, else \c true. | ||
1794 | */ | ||
1795 | FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy); | ||
1796 | |||
1797 | /** Insert a blank track in a CUESHEET block at the given index. | ||
1798 | * | ||
1799 | * A blank track is one in which all field values are zero. | ||
1800 | * | ||
1801 | * \param object A pointer to an existing CUESHEET object. | ||
1802 | * \param track_num The index at which to insert the track. NOTE: this | ||
1803 | * is not necessarily the same as the track's \a number | ||
1804 | * field. The tracks at and after \a track_num move right | ||
1805 | * one position. To append a track to the end, set | ||
1806 | * \a track_num to \c object->data.cue_sheet.num_tracks . | ||
1807 | * \assert | ||
1808 | * \code object != NULL \endcode | ||
1809 | * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode | ||
1810 | * \code object->data.cue_sheet.num_tracks >= track_num \endcode | ||
1811 | * \retval FLAC__bool | ||
1812 | * \c false if \a copy is \c true and malloc() fails, else \c true. | ||
1813 | */ | ||
1814 | FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_blank_track(FLAC__StreamMetadata *object, unsigned track_num); | ||
1815 | |||
1816 | /** Delete a track in a CUESHEET block at the given index. | ||
1817 | * | ||
1818 | * \param object A pointer to an existing CUESHEET object. | ||
1819 | * \param track_num The index into the track array of the track to | ||
1820 | * delete. NOTE: this is not necessarily the same | ||
1821 | * as the track's \a number field. | ||
1822 | * \assert | ||
1823 | * \code object != NULL \endcode | ||
1824 | * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode | ||
1825 | * \code object->data.cue_sheet.num_tracks > track_num \endcode | ||
1826 | * \retval FLAC__bool | ||
1827 | * \c false if realloc() fails, else \c true. | ||
1828 | */ | ||
1829 | FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_delete_track(FLAC__StreamMetadata *object, unsigned track_num); | ||
1830 | |||
1831 | /** Check a cue sheet to see if it conforms to the FLAC specification. | ||
1832 | * See the format specification for limits on the contents of the | ||
1833 | * cue sheet. | ||
1834 | * | ||
1835 | * \param object A pointer to an existing CUESHEET object. | ||
1836 | * \param check_cd_da_subset If \c true, check CUESHEET against more | ||
1837 | * stringent requirements for a CD-DA (audio) disc. | ||
1838 | * \param violation Address of a pointer to a string. If there is a | ||
1839 | * violation, a pointer to a string explanation of the | ||
1840 | * violation will be returned here. \a violation may be | ||
1841 | * \c NULL if you don't need the returned string. Do not | ||
1842 | * free the returned string; it will always point to static | ||
1843 | * data. | ||
1844 | * \assert | ||
1845 | * \code object != NULL \endcode | ||
1846 | * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode | ||
1847 | * \retval FLAC__bool | ||
1848 | * \c false if cue sheet is illegal, else \c true. | ||
1849 | */ | ||
1850 | FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_is_legal(const FLAC__StreamMetadata *object, FLAC__bool check_cd_da_subset, const char **violation); | ||
1851 | |||
1852 | /* \} */ | ||
1853 | |||
1854 | #ifdef __cplusplus | ||
1855 | } | ||
1856 | #endif | ||
1857 | |||
1858 | #endif | ||
diff --git a/apps/codecs/libFLAC/include/FLAC/ordinals.h b/apps/codecs/libFLAC/include/FLAC/ordinals.h new file mode 100644 index 0000000000..10bc25d5f1 --- /dev/null +++ b/apps/codecs/libFLAC/include/FLAC/ordinals.h | |||
@@ -0,0 +1,73 @@ | |||
1 | /* libFLAC - Free Lossless Audio Codec library | ||
2 | * Copyright (C) 2000,2001,2002,2003,2004,2005 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__ORDINALS_H | ||
33 | #define FLAC__ORDINALS_H | ||
34 | |||
35 | #ifndef _MSC_VER | ||
36 | #include <inttypes.h> | ||
37 | #endif | ||
38 | |||
39 | typedef signed char FLAC__int8; | ||
40 | typedef unsigned char FLAC__uint8; | ||
41 | |||
42 | #if defined _MSC_VER | ||
43 | typedef __int16 FLAC__int16; | ||
44 | typedef __int32 FLAC__int32; | ||
45 | typedef __int64 FLAC__int64; | ||
46 | typedef unsigned __int16 FLAC__uint16; | ||
47 | typedef unsigned __int32 FLAC__uint32; | ||
48 | typedef unsigned __int64 FLAC__uint64; | ||
49 | #else | ||
50 | typedef int16_t FLAC__int16; | ||
51 | typedef int32_t FLAC__int32; | ||
52 | typedef int64_t FLAC__int64; | ||
53 | typedef uint16_t FLAC__uint16; | ||
54 | typedef uint32_t FLAC__uint32; | ||
55 | typedef uint64_t FLAC__uint64; | ||
56 | #endif | ||
57 | |||
58 | typedef int FLAC__bool; | ||
59 | |||
60 | typedef FLAC__uint8 FLAC__byte; | ||
61 | |||
62 | #ifdef true | ||
63 | #undef true | ||
64 | #endif | ||
65 | #ifdef false | ||
66 | #undef false | ||
67 | #endif | ||
68 | #ifndef __cplusplus | ||
69 | #define true 1 | ||
70 | #define false 0 | ||
71 | #endif | ||
72 | |||
73 | #endif | ||
diff --git a/apps/codecs/libFLAC/include/FLAC/seekable_stream_decoder.h b/apps/codecs/libFLAC/include/FLAC/seekable_stream_decoder.h new file mode 100644 index 0000000000..dee5a89cef --- /dev/null +++ b/apps/codecs/libFLAC/include/FLAC/seekable_stream_decoder.h | |||
@@ -0,0 +1,931 @@ | |||
1 | /* libFLAC - Free Lossless Audio Codec library | ||
2 | * Copyright (C) 2000,2001,2002,2003,2004,2005 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__SEEKABLE_STREAM_DECODER_H | ||
33 | #define FLAC__SEEKABLE_STREAM_DECODER_H | ||
34 | |||
35 | #include "export.h" | ||
36 | #include "stream_decoder.h" | ||
37 | |||
38 | #ifdef __cplusplus | ||
39 | extern "C" { | ||
40 | #endif | ||
41 | |||
42 | |||
43 | /** \file include/FLAC/seekable_stream_decoder.h | ||
44 | * | ||
45 | * \brief | ||
46 | * This module contains the functions which implement the seekable stream | ||
47 | * decoder. | ||
48 | * | ||
49 | * See the detailed documentation in the | ||
50 | * \link flac_seekable_stream_decoder seekable stream decoder \endlink module. | ||
51 | */ | ||
52 | |||
53 | /** \defgroup flac_seekable_stream_decoder FLAC/seekable_stream_decoder.h: seekable stream decoder interface | ||
54 | * \ingroup flac_decoder | ||
55 | * | ||
56 | * \brief | ||
57 | * This module contains the functions which implement the seekable stream | ||
58 | * decoder. | ||
59 | * | ||
60 | * The basic usage of this decoder is as follows: | ||
61 | * - The program creates an instance of a decoder using | ||
62 | * FLAC__seekable_stream_decoder_new(). | ||
63 | * - The program overrides the default settings and sets callbacks for | ||
64 | * reading, writing, seeking, error reporting, and metadata reporting | ||
65 | * using FLAC__seekable_stream_decoder_set_*() functions. | ||
66 | * - The program initializes the instance to validate the settings and | ||
67 | * prepare for decoding using FLAC__seekable_stream_decoder_init(). | ||
68 | * - The program calls the FLAC__seekable_stream_decoder_process_*() | ||
69 | * functions to decode data, which subsequently calls the callbacks. | ||
70 | * - The program finishes the decoding with | ||
71 | * FLAC__seekable_stream_decoder_finish(), which flushes the input and | ||
72 | * output and resets the decoder to the uninitialized state. | ||
73 | * - The instance may be used again or deleted with | ||
74 | * FLAC__seekable_stream_decoder_delete(). | ||
75 | * | ||
76 | * The seekable stream decoder is a wrapper around the | ||
77 | * \link flac_stream_decoder stream decoder \endlink which also provides | ||
78 | * seeking capability. In addition to the Read/Write/Metadata/Error | ||
79 | * callbacks of the stream decoder, the user must also provide the following: | ||
80 | * | ||
81 | * - Seek callback - This function will be called when the decoder wants to | ||
82 | * seek to an absolute position in the stream. | ||
83 | * - Tell callback - This function will be called when the decoder wants to | ||
84 | * know the current absolute position of the stream. | ||
85 | * - Length callback - This function will be called when the decoder wants | ||
86 | * to know length of the stream. The seeking algorithm currently requires | ||
87 | * that the overall stream length be known. | ||
88 | * - EOF callback - This function will be called when the decoder wants to | ||
89 | * know if it is at the end of the stream. This could be synthesized from | ||
90 | * the tell and length callbacks but it may be more expensive that way, so | ||
91 | * there is a separate callback for it. | ||
92 | * | ||
93 | * Seeking is exposed through the | ||
94 | * FLAC__seekable_stream_decoder_seek_absolute() method. At any point after | ||
95 | * the seekable stream decoder has been initialized, the user can call this | ||
96 | * function to seek to an exact sample within the stream. Subsequently, the | ||
97 | * first time the write callback is called it will be passed a (possibly | ||
98 | * partial) block starting at that sample. | ||
99 | * | ||
100 | * The seekable stream decoder also provides MD5 signature checking. If | ||
101 | * this is turned on before initialization, | ||
102 | * FLAC__seekable_stream_decoder_finish() will report when the decoded MD5 | ||
103 | * signature does not match the one stored in the STREAMINFO block. MD5 | ||
104 | * checking is automatically turned off (until the next | ||
105 | * FLAC__seekable_stream_decoder_reset()) if there is no signature in the | ||
106 | * STREAMINFO block or when a seek is attempted. | ||
107 | * | ||
108 | * Make sure to read the detailed description of the | ||
109 | * \link flac_stream_decoder stream decoder module \endlink since the | ||
110 | * seekable stream decoder inherits much of its behavior. | ||
111 | * | ||
112 | * \note | ||
113 | * The "set" functions may only be called when the decoder is in the | ||
114 | * state FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED, i.e. after | ||
115 | * FLAC__seekable_stream_decoder_new() or | ||
116 | * FLAC__seekable_stream_decoder_finish(), but before | ||
117 | * FLAC__seekable_stream_decoder_init(). If this is the case they will | ||
118 | * return \c true, otherwise \c false. | ||
119 | * | ||
120 | * \note | ||
121 | * FLAC__stream_decoder_finish() resets all settings to the constructor | ||
122 | * defaults, including the callbacks. | ||
123 | * | ||
124 | * \{ | ||
125 | */ | ||
126 | |||
127 | |||
128 | /** State values for a FLAC__SeekableStreamDecoder | ||
129 | * | ||
130 | * The decoder's state can be obtained by calling FLAC__seekable_stream_decoder_get_state(). | ||
131 | */ | ||
132 | typedef enum { | ||
133 | |||
134 | FLAC__SEEKABLE_STREAM_DECODER_OK = 0, | ||
135 | /**< The decoder is in the normal OK state. */ | ||
136 | |||
137 | FLAC__SEEKABLE_STREAM_DECODER_SEEKING, | ||
138 | /**< The decoder is in the process of seeking. */ | ||
139 | |||
140 | FLAC__SEEKABLE_STREAM_DECODER_END_OF_STREAM, | ||
141 | /**< The decoder has reached the end of the stream. */ | ||
142 | |||
143 | FLAC__SEEKABLE_STREAM_DECODER_MEMORY_ALLOCATION_ERROR, | ||
144 | /**< An error occurred allocating memory. */ | ||
145 | |||
146 | FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR, | ||
147 | /**< An error occurred in the underlying stream decoder. */ | ||
148 | |||
149 | FLAC__SEEKABLE_STREAM_DECODER_READ_ERROR, | ||
150 | /**< The read callback returned an error. */ | ||
151 | |||
152 | FLAC__SEEKABLE_STREAM_DECODER_SEEK_ERROR, | ||
153 | /**< An error occurred while seeking or the seek or tell | ||
154 | * callback returned an error. | ||
155 | */ | ||
156 | |||
157 | FLAC__SEEKABLE_STREAM_DECODER_ALREADY_INITIALIZED, | ||
158 | /**< FLAC__seekable_stream_decoder_init() was called when the | ||
159 | * decoder was already initialized, usually because | ||
160 | * FLAC__seekable_stream_decoder_finish() was not called. | ||
161 | */ | ||
162 | |||
163 | FLAC__SEEKABLE_STREAM_DECODER_INVALID_CALLBACK, | ||
164 | /**< FLAC__seekable_stream_decoder_init() was called without all | ||
165 | * callbacks being set. | ||
166 | */ | ||
167 | |||
168 | FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED | ||
169 | /**< The decoder is in the uninitialized state. */ | ||
170 | |||
171 | } FLAC__SeekableStreamDecoderState; | ||
172 | |||
173 | /** Maps a FLAC__SeekableStreamDecoderState to a C string. | ||
174 | * | ||
175 | * Using a FLAC__SeekableStreamDecoderState as the index to this array | ||
176 | * will give the string equivalent. The contents should not be modified. | ||
177 | */ | ||
178 | extern FLAC_API const char * const FLAC__SeekableStreamDecoderStateString[]; | ||
179 | |||
180 | |||
181 | /** Return values for the FLAC__SeekableStreamDecoder read callback. | ||
182 | */ | ||
183 | typedef enum { | ||
184 | |||
185 | FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_OK, | ||
186 | /**< The read was OK and decoding can continue. */ | ||
187 | |||
188 | FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_ERROR | ||
189 | /**< An unrecoverable error occurred. The decoder will return from the process call. */ | ||
190 | |||
191 | } FLAC__SeekableStreamDecoderReadStatus; | ||
192 | |||
193 | /** Maps a FLAC__SeekableStreamDecoderReadStatus to a C string. | ||
194 | * | ||
195 | * Using a FLAC__SeekableStreamDecoderReadStatus as the index to this array | ||
196 | * will give the string equivalent. The contents should not be modified. | ||
197 | */ | ||
198 | extern FLAC_API const char * const FLAC__SeekableStreamDecoderReadStatusString[]; | ||
199 | |||
200 | |||
201 | /** Return values for the FLAC__SeekableStreamDecoder seek callback. | ||
202 | */ | ||
203 | typedef enum { | ||
204 | |||
205 | FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_OK, | ||
206 | /**< The seek was OK and decoding can continue. */ | ||
207 | |||
208 | FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_ERROR | ||
209 | /**< An unrecoverable error occurred. The decoder will return from the process call. */ | ||
210 | |||
211 | } FLAC__SeekableStreamDecoderSeekStatus; | ||
212 | |||
213 | /** Maps a FLAC__SeekableStreamDecoderSeekStatus to a C string. | ||
214 | * | ||
215 | * Using a FLAC__SeekableStreamDecoderSeekStatus as the index to this array | ||
216 | * will give the string equivalent. The contents should not be modified. | ||
217 | */ | ||
218 | extern FLAC_API const char * const FLAC__SeekableStreamDecoderSeekStatusString[]; | ||
219 | |||
220 | |||
221 | /** Return values for the FLAC__SeekableStreamDecoder tell callback. | ||
222 | */ | ||
223 | typedef enum { | ||
224 | |||
225 | FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_OK, | ||
226 | /**< The tell was OK and decoding can continue. */ | ||
227 | |||
228 | FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_ERROR | ||
229 | /**< An unrecoverable error occurred. The decoder will return from the process call. */ | ||
230 | |||
231 | } FLAC__SeekableStreamDecoderTellStatus; | ||
232 | |||
233 | /** Maps a FLAC__SeekableStreamDecoderTellStatus to a C string. | ||
234 | * | ||
235 | * Using a FLAC__SeekableStreamDecoderTellStatus as the index to this array | ||
236 | * will give the string equivalent. The contents should not be modified. | ||
237 | */ | ||
238 | extern FLAC_API const char * const FLAC__SeekableStreamDecoderTellStatusString[]; | ||
239 | |||
240 | |||
241 | /** Return values for the FLAC__SeekableStreamDecoder length callback. | ||
242 | */ | ||
243 | typedef enum { | ||
244 | |||
245 | FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_OK, | ||
246 | /**< The length call was OK and decoding can continue. */ | ||
247 | |||
248 | FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_ERROR | ||
249 | /**< An unrecoverable error occurred. The decoder will return from the process call. */ | ||
250 | |||
251 | } FLAC__SeekableStreamDecoderLengthStatus; | ||
252 | |||
253 | /** Maps a FLAC__SeekableStreamDecoderLengthStatus to a C string. | ||
254 | * | ||
255 | * Using a FLAC__SeekableStreamDecoderLengthStatus as the index to this array | ||
256 | * will give the string equivalent. The contents should not be modified. | ||
257 | */ | ||
258 | extern FLAC_API const char * const FLAC__SeekableStreamDecoderLengthStatusString[]; | ||
259 | |||
260 | |||
261 | /*********************************************************************** | ||
262 | * | ||
263 | * class FLAC__SeekableStreamDecoder : public FLAC__StreamDecoder | ||
264 | * | ||
265 | ***********************************************************************/ | ||
266 | |||
267 | struct FLAC__SeekableStreamDecoderProtected; | ||
268 | struct FLAC__SeekableStreamDecoderPrivate; | ||
269 | /** The opaque structure definition for the seekable stream decoder type. | ||
270 | * See the | ||
271 | * \link flac_seekable_stream_decoder seekable stream decoder module \endlink | ||
272 | * for a detailed description. | ||
273 | */ | ||
274 | typedef struct { | ||
275 | struct FLAC__SeekableStreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */ | ||
276 | struct FLAC__SeekableStreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */ | ||
277 | } FLAC__SeekableStreamDecoder; | ||
278 | |||
279 | /** Signature for the read callback. | ||
280 | * See FLAC__seekable_stream_decoder_set_read_callback() | ||
281 | * and FLAC__StreamDecoderReadCallback for more info. | ||
282 | * | ||
283 | * \param decoder The decoder instance calling the callback. | ||
284 | * \param buffer A pointer to a location for the callee to store | ||
285 | * data to be decoded. | ||
286 | * \param bytes A pointer to the size of the buffer. | ||
287 | * \param client_data The callee's client data set through | ||
288 | * FLAC__seekable_stream_decoder_set_client_data(). | ||
289 | * \retval FLAC__SeekableStreamDecoderReadStatus | ||
290 | * The callee's return status. | ||
291 | */ | ||
292 | typedef FLAC__SeekableStreamDecoderReadStatus (*FLAC__SeekableStreamDecoderReadCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data); | ||
293 | |||
294 | /** Signature for the seek callback. | ||
295 | * See FLAC__seekable_stream_decoder_set_seek_callback() for more info. | ||
296 | * | ||
297 | * \param decoder The decoder instance calling the callback. | ||
298 | * \param absolute_byte_offset The offset from the beginning of the stream | ||
299 | * to seek to. | ||
300 | * \param client_data The callee's client data set through | ||
301 | * FLAC__seekable_stream_decoder_set_client_data(). | ||
302 | * \retval FLAC__SeekableStreamDecoderSeekStatus | ||
303 | * The callee's return status. | ||
304 | */ | ||
305 | typedef FLAC__SeekableStreamDecoderSeekStatus (*FLAC__SeekableStreamDecoderSeekCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data); | ||
306 | |||
307 | /** Signature for the tell callback. | ||
308 | * See FLAC__seekable_stream_decoder_set_tell_callback() for more info. | ||
309 | * | ||
310 | * \param decoder The decoder instance calling the callback. | ||
311 | * \param absolute_byte_offset A pointer to storage for the current offset | ||
312 | * from the beginning of the stream. | ||
313 | * \param client_data The callee's client data set through | ||
314 | * FLAC__seekable_stream_decoder_set_client_data(). | ||
315 | * \retval FLAC__SeekableStreamDecoderTellStatus | ||
316 | * The callee's return status. | ||
317 | */ | ||
318 | typedef FLAC__SeekableStreamDecoderTellStatus (*FLAC__SeekableStreamDecoderTellCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data); | ||
319 | |||
320 | /** Signature for the length callback. | ||
321 | * See FLAC__seekable_stream_decoder_set_length_callback() for more info. | ||
322 | * | ||
323 | * \param decoder The decoder instance calling the callback. | ||
324 | * \param stream_length A pointer to storage for the length of the stream | ||
325 | * in bytes. | ||
326 | * \param client_data The callee's client data set through | ||
327 | * FLAC__seekable_stream_decoder_set_client_data(). | ||
328 | * \retval FLAC__SeekableStreamDecoderLengthStatus | ||
329 | * The callee's return status. | ||
330 | */ | ||
331 | typedef FLAC__SeekableStreamDecoderLengthStatus (*FLAC__SeekableStreamDecoderLengthCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data); | ||
332 | |||
333 | /** Signature for the EOF callback. | ||
334 | * See FLAC__seekable_stream_decoder_set_eof_callback() for more info. | ||
335 | * | ||
336 | * \param decoder The decoder instance calling the callback. | ||
337 | * \param client_data The callee's client data set through | ||
338 | * FLAC__seekable_stream_decoder_set_client_data(). | ||
339 | * \retval FLAC__bool | ||
340 | * \c true if the currently at the end of the stream, else \c false. | ||
341 | */ | ||
342 | typedef FLAC__bool (*FLAC__SeekableStreamDecoderEofCallback)(const FLAC__SeekableStreamDecoder *decoder, void *client_data); | ||
343 | |||
344 | /** Signature for the write callback. | ||
345 | * See FLAC__seekable_stream_decoder_set_write_callback() | ||
346 | * and FLAC__StreamDecoderWriteCallback for more info. | ||
347 | * | ||
348 | * \param decoder The decoder instance calling the callback. | ||
349 | * \param frame The description of the decoded frame. | ||
350 | * \param buffer An array of pointers to decoded channels of data. | ||
351 | * \param client_data The callee's client data set through | ||
352 | * FLAC__seekable_stream_decoder_set_client_data(). | ||
353 | * \retval FLAC__StreamDecoderWriteStatus | ||
354 | * The callee's return status. | ||
355 | */ | ||
356 | typedef FLAC__StreamDecoderWriteStatus (*FLAC__SeekableStreamDecoderWriteCallback)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data); | ||
357 | |||
358 | /** Signature for the metadata callback. | ||
359 | * See FLAC__seekable_stream_decoder_set_metadata_callback() | ||
360 | * and FLAC__StreamDecoderMetadataCallback for more info. | ||
361 | * | ||
362 | * \param decoder The decoder instance calling the callback. | ||
363 | * \param metadata The decoded metadata block. | ||
364 | * \param client_data The callee's client data set through | ||
365 | * FLAC__seekable_stream_decoder_set_client_data(). | ||
366 | */ | ||
367 | typedef void (*FLAC__SeekableStreamDecoderMetadataCallback)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data); | ||
368 | |||
369 | /** Signature for the error callback. | ||
370 | * See FLAC__seekable_stream_decoder_set_error_callback() | ||
371 | * and FLAC__StreamDecoderErrorCallback for more info. | ||
372 | * | ||
373 | * \param decoder The decoder instance calling the callback. | ||
374 | * \param status The error encountered by the decoder. | ||
375 | * \param client_data The callee's client data set through | ||
376 | * FLAC__seekable_stream_decoder_set_client_data(). | ||
377 | */ | ||
378 | typedef void (*FLAC__SeekableStreamDecoderErrorCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data); | ||
379 | |||
380 | |||
381 | /*********************************************************************** | ||
382 | * | ||
383 | * Class constructor/destructor | ||
384 | * | ||
385 | ***********************************************************************/ | ||
386 | |||
387 | /** Create a new seekable stream decoder instance. The instance is created | ||
388 | * with default settings; see the individual | ||
389 | * FLAC__seekable_stream_decoder_set_*() functions for each setting's | ||
390 | * default. | ||
391 | * | ||
392 | * \retval FLAC__SeekableStreamDecoder* | ||
393 | * \c NULL if there was an error allocating memory, else the new instance. | ||
394 | */ | ||
395 | FLAC_API FLAC__SeekableStreamDecoder *FLAC__seekable_stream_decoder_new(); | ||
396 | |||
397 | /** Free a decoder instance. Deletes the object pointed to by \a decoder. | ||
398 | * | ||
399 | * \param decoder A pointer to an existing decoder. | ||
400 | * \assert | ||
401 | * \code decoder != NULL \endcode | ||
402 | */ | ||
403 | FLAC_API void FLAC__seekable_stream_decoder_delete(FLAC__SeekableStreamDecoder *decoder); | ||
404 | |||
405 | |||
406 | /*********************************************************************** | ||
407 | * | ||
408 | * Public class method prototypes | ||
409 | * | ||
410 | ***********************************************************************/ | ||
411 | |||
412 | /** Set the "MD5 signature checking" flag. If \c true, the decoder will | ||
413 | * compute the MD5 signature of the unencoded audio data while decoding | ||
414 | * and compare it to the signature from the STREAMINFO block, if it | ||
415 | * exists, during FLAC__seekable_stream_decoder_finish(). | ||
416 | * | ||
417 | * MD5 signature checking will be turned off (until the next | ||
418 | * FLAC__seekable_stream_decoder_reset()) if there is no signature in | ||
419 | * the STREAMINFO block or when a seek is attempted. | ||
420 | * | ||
421 | * \default \c false | ||
422 | * \param decoder A decoder instance to set. | ||
423 | * \param value Flag value (see above). | ||
424 | * \assert | ||
425 | * \code decoder != NULL \endcode | ||
426 | * \retval FLAC__bool | ||
427 | * \c false if the decoder is already initialized, else \c true. | ||
428 | */ | ||
429 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_md5_checking(FLAC__SeekableStreamDecoder *decoder, FLAC__bool value); | ||
430 | |||
431 | /** Set the read callback. | ||
432 | * This is inherited from FLAC__StreamDecoder; see | ||
433 | * FLAC__stream_decoder_set_read_callback(). | ||
434 | * | ||
435 | * \note | ||
436 | * The callback is mandatory and must be set before initialization. | ||
437 | * | ||
438 | * \default \c NULL | ||
439 | * \param decoder A decoder instance to set. | ||
440 | * \param value See above. | ||
441 | * \assert | ||
442 | * \code decoder != NULL \endcode | ||
443 | * \code value != NULL \endcode | ||
444 | * \retval FLAC__bool | ||
445 | * \c false if the decoder is already initialized, else \c true. | ||
446 | */ | ||
447 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_read_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderReadCallback value); | ||
448 | |||
449 | /** Set the seek callback. | ||
450 | * The supplied function will be called when the decoder needs to seek | ||
451 | * the input stream. The decoder will pass the absolute byte offset | ||
452 | * to seek to, 0 meaning the beginning of the stream. | ||
453 | * | ||
454 | * \note | ||
455 | * The callback is mandatory and must be set before initialization. | ||
456 | * | ||
457 | * \default \c NULL | ||
458 | * \param decoder A decoder instance to set. | ||
459 | * \param value See above. | ||
460 | * \assert | ||
461 | * \code decoder != NULL \endcode | ||
462 | * \code value != NULL \endcode | ||
463 | * \retval FLAC__bool | ||
464 | * \c false if the decoder is already initialized, else \c true. | ||
465 | */ | ||
466 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_seek_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderSeekCallback value); | ||
467 | |||
468 | /** Set the tell callback. | ||
469 | * The supplied function will be called when the decoder wants to know | ||
470 | * the current position of the stream. The callback should return the | ||
471 | * byte offset from the beginning of the stream. | ||
472 | * | ||
473 | * \note | ||
474 | * The callback is mandatory and must be set before initialization. | ||
475 | * | ||
476 | * \default \c NULL | ||
477 | * \param decoder A decoder instance to set. | ||
478 | * \param value See above. | ||
479 | * \assert | ||
480 | * \code decoder != NULL \endcode | ||
481 | * \code value != NULL \endcode | ||
482 | * \retval FLAC__bool | ||
483 | * \c false if the decoder is already initialized, else \c true. | ||
484 | */ | ||
485 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_tell_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderTellCallback value); | ||
486 | |||
487 | /** Set the length callback. | ||
488 | * The supplied function will be called when the decoder wants to know | ||
489 | * the total length of the stream in bytes. | ||
490 | * | ||
491 | * \note | ||
492 | * The callback is mandatory and must be set before initialization. | ||
493 | * | ||
494 | * \default \c NULL | ||
495 | * \param decoder A decoder instance to set. | ||
496 | * \param value See above. | ||
497 | * \assert | ||
498 | * \code decoder != NULL \endcode | ||
499 | * \code value != NULL \endcode | ||
500 | * \retval FLAC__bool | ||
501 | * \c false if the decoder is already initialized, else \c true. | ||
502 | */ | ||
503 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_length_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderLengthCallback value); | ||
504 | |||
505 | /** Set the eof callback. | ||
506 | * The supplied function will be called when the decoder needs to know | ||
507 | * if the end of the stream has been reached. | ||
508 | * | ||
509 | * \note | ||
510 | * The callback is mandatory and must be set before initialization. | ||
511 | * | ||
512 | * \default \c NULL | ||
513 | * \param decoder A decoder instance to set. | ||
514 | * \param value See above. | ||
515 | * \assert | ||
516 | * \code decoder != NULL \endcode | ||
517 | * \code value != NULL \endcode | ||
518 | * \retval FLAC__bool | ||
519 | * \c false if the decoder is already initialized, else \c true. | ||
520 | */ | ||
521 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_eof_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderEofCallback value); | ||
522 | |||
523 | /** Set the write callback. | ||
524 | * This is inherited from FLAC__StreamDecoder; see | ||
525 | * FLAC__stream_decoder_set_write_callback(). | ||
526 | * | ||
527 | * \note | ||
528 | * The callback is mandatory and must be set before initialization. | ||
529 | * | ||
530 | * \default \c NULL | ||
531 | * \param decoder A decoder instance to set. | ||
532 | * \param value See above. | ||
533 | * \assert | ||
534 | * \code decoder != NULL \endcode | ||
535 | * \code value != NULL \endcode | ||
536 | * \retval FLAC__bool | ||
537 | * \c false if the decoder is already initialized, else \c true. | ||
538 | */ | ||
539 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_write_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderWriteCallback value); | ||
540 | |||
541 | /** Set the metadata callback. | ||
542 | * This is inherited from FLAC__StreamDecoder; see | ||
543 | * FLAC__stream_decoder_set_metadata_callback(). | ||
544 | * | ||
545 | * \note | ||
546 | * The callback is mandatory and must be set before initialization. | ||
547 | * | ||
548 | * \default \c NULL | ||
549 | * \param decoder A decoder instance to set. | ||
550 | * \param value See above. | ||
551 | * \assert | ||
552 | * \code decoder != NULL \endcode | ||
553 | * \code value != NULL \endcode | ||
554 | * \retval FLAC__bool | ||
555 | * \c false if the decoder is already initialized, else \c true. | ||
556 | */ | ||
557 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderMetadataCallback value); | ||
558 | |||
559 | /** Set the error callback. | ||
560 | * This is inherited from FLAC__StreamDecoder; see | ||
561 | * FLAC__stream_decoder_set_error_callback(). | ||
562 | * | ||
563 | * \note | ||
564 | * The callback is mandatory and must be set before initialization. | ||
565 | * | ||
566 | * \default \c NULL | ||
567 | * \param decoder A decoder instance to set. | ||
568 | * \param value See above. | ||
569 | * \assert | ||
570 | * \code decoder != NULL \endcode | ||
571 | * \code value != NULL \endcode | ||
572 | * \retval FLAC__bool | ||
573 | * \c false if the decoder is already initialized, else \c true. | ||
574 | */ | ||
575 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_error_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderErrorCallback value); | ||
576 | |||
577 | /** Set the client data to be passed back to callbacks. | ||
578 | * This value will be supplied to callbacks in their \a client_data | ||
579 | * argument. | ||
580 | * | ||
581 | * \default \c NULL | ||
582 | * \param decoder A decoder instance to set. | ||
583 | * \param value See above. | ||
584 | * \assert | ||
585 | * \code decoder != NULL \endcode | ||
586 | * \retval FLAC__bool | ||
587 | * \c false if the decoder is already initialized, else \c true. | ||
588 | */ | ||
589 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_client_data(FLAC__SeekableStreamDecoder *decoder, void *value); | ||
590 | |||
591 | /** This is inherited from FLAC__StreamDecoder; see | ||
592 | * FLAC__stream_decoder_set_metadata_respond(). | ||
593 | * | ||
594 | * \default By default, only the \c STREAMINFO block is returned via the | ||
595 | * metadata callback. | ||
596 | * \param decoder A decoder instance to set. | ||
597 | * \param type See above. | ||
598 | * \assert | ||
599 | * \code decoder != NULL \endcode | ||
600 | * \a type is valid | ||
601 | * \retval FLAC__bool | ||
602 | * \c false if the decoder is already initialized, else \c true. | ||
603 | */ | ||
604 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond(FLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type); | ||
605 | |||
606 | /** This is inherited from FLAC__StreamDecoder; see | ||
607 | * FLAC__stream_decoder_set_metadata_respond_application(). | ||
608 | * | ||
609 | * \default By default, only the \c STREAMINFO block is returned via the | ||
610 | * metadata callback. | ||
611 | * \param decoder A decoder instance to set. | ||
612 | * \param id See above. | ||
613 | * \assert | ||
614 | * \code decoder != NULL \endcode | ||
615 | * \code id != NULL \endcode | ||
616 | * \retval FLAC__bool | ||
617 | * \c false if the decoder is already initialized, else \c true. | ||
618 | */ | ||
619 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond_application(FLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]); | ||
620 | |||
621 | /** This is inherited from FLAC__StreamDecoder; see | ||
622 | * FLAC__stream_decoder_set_metadata_respond_all(). | ||
623 | * | ||
624 | * \default By default, only the \c STREAMINFO block is returned via the | ||
625 | * metadata callback. | ||
626 | * \param decoder A decoder instance to set. | ||
627 | * \assert | ||
628 | * \code decoder != NULL \endcode | ||
629 | * \retval FLAC__bool | ||
630 | * \c false if the decoder is already initialized, else \c true. | ||
631 | */ | ||
632 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond_all(FLAC__SeekableStreamDecoder *decoder); | ||
633 | |||
634 | /** This is inherited from FLAC__StreamDecoder; see | ||
635 | * FLAC__stream_decoder_set_metadata_ignore(). | ||
636 | * | ||
637 | * \default By default, only the \c STREAMINFO block is returned via the | ||
638 | * metadata callback. | ||
639 | * \param decoder A decoder instance to set. | ||
640 | * \param type See above. | ||
641 | * \assert | ||
642 | * \code decoder != NULL \endcode | ||
643 | * \a type is valid | ||
644 | * \retval FLAC__bool | ||
645 | * \c false if the decoder is already initialized, else \c true. | ||
646 | */ | ||
647 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore(FLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type); | ||
648 | |||
649 | /** This is inherited from FLAC__StreamDecoder; see | ||
650 | * FLAC__stream_decoder_set_metadata_ignore_application(). | ||
651 | * | ||
652 | * \default By default, only the \c STREAMINFO block is returned via the | ||
653 | * metadata callback. | ||
654 | * \param decoder A decoder instance to set. | ||
655 | * \param id See above. | ||
656 | * \assert | ||
657 | * \code decoder != NULL \endcode | ||
658 | * \code id != NULL \endcode | ||
659 | * \retval FLAC__bool | ||
660 | * \c false if the decoder is already initialized, else \c true. | ||
661 | */ | ||
662 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore_application(FLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]); | ||
663 | |||
664 | /** This is inherited from FLAC__StreamDecoder; see | ||
665 | * FLAC__stream_decoder_set_metadata_ignore_all(). | ||
666 | * | ||
667 | * \default By default, only the \c STREAMINFO block is returned via the | ||
668 | * metadata callback. | ||
669 | * \param decoder A decoder instance to set. | ||
670 | * \assert | ||
671 | * \code decoder != NULL \endcode | ||
672 | * \retval FLAC__bool | ||
673 | * \c false if the decoder is already initialized, else \c true. | ||
674 | */ | ||
675 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore_all(FLAC__SeekableStreamDecoder *decoder); | ||
676 | |||
677 | /** Get the current decoder state. | ||
678 | * | ||
679 | * \param decoder A decoder instance to query. | ||
680 | * \assert | ||
681 | * \code decoder != NULL \endcode | ||
682 | * \retval FLAC__SeekableStreamDecoderState | ||
683 | * The current decoder state. | ||
684 | */ | ||
685 | FLAC_API FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_get_state(const FLAC__SeekableStreamDecoder *decoder); | ||
686 | |||
687 | /** Get the state of the underlying stream decoder. | ||
688 | * Useful when the seekable stream decoder state is | ||
689 | * \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR. | ||
690 | * | ||
691 | * \param decoder A decoder instance to query. | ||
692 | * \assert | ||
693 | * \code decoder != NULL \endcode | ||
694 | * \retval FLAC__StreamDecoderState | ||
695 | * The stream decoder state. | ||
696 | */ | ||
697 | FLAC_API FLAC__StreamDecoderState FLAC__seekable_stream_decoder_get_stream_decoder_state(const FLAC__SeekableStreamDecoder *decoder); | ||
698 | |||
699 | /** Get the current decoder state as a C string. | ||
700 | * This version automatically resolves | ||
701 | * \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR by getting the | ||
702 | * stream decoder's state. | ||
703 | * | ||
704 | * \param decoder A decoder instance to query. | ||
705 | * \assert | ||
706 | * \code decoder != NULL \endcode | ||
707 | * \retval const char * | ||
708 | * The decoder state as a C string. Do not modify the contents. | ||
709 | */ | ||
710 | FLAC_API const char *FLAC__seekable_stream_decoder_get_resolved_state_string(const FLAC__SeekableStreamDecoder *decoder); | ||
711 | |||
712 | /** Get the "MD5 signature checking" flag. | ||
713 | * This is the value of the setting, not whether or not the decoder is | ||
714 | * currently checking the MD5 (remember, it can be turned off automatically | ||
715 | * by a seek). When the decoder is reset the flag will be restored to the | ||
716 | * value returned by this function. | ||
717 | * | ||
718 | * \param decoder A decoder instance to query. | ||
719 | * \assert | ||
720 | * \code decoder != NULL \endcode | ||
721 | * \retval FLAC__bool | ||
722 | * See above. | ||
723 | */ | ||
724 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_get_md5_checking(const FLAC__SeekableStreamDecoder *decoder); | ||
725 | |||
726 | /** This is inherited from FLAC__StreamDecoder; see | ||
727 | * FLAC__stream_decoder_get_channels(). | ||
728 | * | ||
729 | * \param decoder A decoder instance to query. | ||
730 | * \assert | ||
731 | * \code decoder != NULL \endcode | ||
732 | * \retval unsigned | ||
733 | * See above. | ||
734 | */ | ||
735 | FLAC_API unsigned FLAC__seekable_stream_decoder_get_channels(const FLAC__SeekableStreamDecoder *decoder); | ||
736 | |||
737 | /** This is inherited from FLAC__StreamDecoder; see | ||
738 | * FLAC__stream_decoder_get_channel_assignment(). | ||
739 | * | ||
740 | * \param decoder A decoder instance to query. | ||
741 | * \assert | ||
742 | * \code decoder != NULL \endcode | ||
743 | * \retval FLAC__ChannelAssignment | ||
744 | * See above. | ||
745 | */ | ||
746 | FLAC_API FLAC__ChannelAssignment FLAC__seekable_stream_decoder_get_channel_assignment(const FLAC__SeekableStreamDecoder *decoder); | ||
747 | |||
748 | /** This is inherited from FLAC__StreamDecoder; see | ||
749 | * FLAC__stream_decoder_get_bits_per_sample(). | ||
750 | * | ||
751 | * \param decoder A decoder instance to query. | ||
752 | * \assert | ||
753 | * \code decoder != NULL \endcode | ||
754 | * \retval unsigned | ||
755 | * See above. | ||
756 | */ | ||
757 | FLAC_API unsigned FLAC__seekable_stream_decoder_get_bits_per_sample(const FLAC__SeekableStreamDecoder *decoder); | ||
758 | |||
759 | /** This is inherited from FLAC__StreamDecoder; see | ||
760 | * FLAC__stream_decoder_get_sample_rate(). | ||
761 | * | ||
762 | * \param decoder A decoder instance to query. | ||
763 | * \assert | ||
764 | * \code decoder != NULL \endcode | ||
765 | * \retval unsigned | ||
766 | * See above. | ||
767 | */ | ||
768 | FLAC_API unsigned FLAC__seekable_stream_decoder_get_sample_rate(const FLAC__SeekableStreamDecoder *decoder); | ||
769 | |||
770 | /** This is inherited from FLAC__StreamDecoder; see | ||
771 | * FLAC__stream_decoder_get_blocksize(). | ||
772 | * | ||
773 | * \param decoder A decoder instance to query. | ||
774 | * \assert | ||
775 | * \code decoder != NULL \endcode | ||
776 | * \retval unsigned | ||
777 | * See above. | ||
778 | */ | ||
779 | FLAC_API unsigned FLAC__seekable_stream_decoder_get_blocksize(const FLAC__SeekableStreamDecoder *decoder); | ||
780 | |||
781 | /** Returns the decoder's current read position within the stream. | ||
782 | * The position is the byte offset from the start of the stream. | ||
783 | * Bytes before this position have been fully decoded. Note that | ||
784 | * there may still be undecoded bytes in the decoder's read FIFO. | ||
785 | * The returned position is correct even after a seek. | ||
786 | * | ||
787 | * \param decoder A decoder instance to query. | ||
788 | * \param position Address at which to return the desired position. | ||
789 | * \assert | ||
790 | * \code decoder != NULL \endcode | ||
791 | * \code position != NULL \endcode | ||
792 | * \retval FLAC__bool | ||
793 | * \c true if successful, \c false if there was an error from | ||
794 | * the 'tell' callback. | ||
795 | */ | ||
796 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_get_decode_position(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *position); | ||
797 | |||
798 | /** Initialize the decoder instance. | ||
799 | * Should be called after FLAC__seekable_stream_decoder_new() and | ||
800 | * FLAC__seekable_stream_decoder_set_*() but before any of the | ||
801 | * FLAC__seekable_stream_decoder_process_*() functions. Will set and return | ||
802 | * the decoder state, which will be FLAC__SEEKABLE_STREAM_DECODER_OK | ||
803 | * if initialization succeeded. | ||
804 | * | ||
805 | * \param decoder An uninitialized decoder instance. | ||
806 | * \assert | ||
807 | * \code decoder != NULL \endcode | ||
808 | * \retval FLAC__SeekableStreamDecoderState | ||
809 | * \c FLAC__SEEKABLE_STREAM_DECODER_OK if initialization was | ||
810 | * successful; see FLAC__SeekableStreamDecoderState for the meanings | ||
811 | * of other return values. | ||
812 | */ | ||
813 | FLAC_API FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_init(FLAC__SeekableStreamDecoder *decoder); | ||
814 | |||
815 | /** Finish the decoding process. | ||
816 | * Flushes the decoding buffer, releases resources, resets the decoder | ||
817 | * settings to their defaults, and returns the decoder state to | ||
818 | * FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED. | ||
819 | * | ||
820 | * In the event of a prematurely-terminated decode, it is not strictly | ||
821 | * necessary to call this immediately before | ||
822 | * FLAC__seekable_stream_decoder_delete() but it is good practice to match | ||
823 | * every FLAC__seekable_stream_decoder_init() with a | ||
824 | * FLAC__seekable_stream_decoder_finish(). | ||
825 | * | ||
826 | * \param decoder An uninitialized decoder instance. | ||
827 | * \assert | ||
828 | * \code decoder != NULL \endcode | ||
829 | * \retval FLAC__bool | ||
830 | * \c false if MD5 checking is on AND a STREAMINFO block was available | ||
831 | * AND the MD5 signature in the STREAMINFO block was non-zero AND the | ||
832 | * signature does not match the one computed by the decoder; else | ||
833 | * \c true. | ||
834 | */ | ||
835 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_finish(FLAC__SeekableStreamDecoder *decoder); | ||
836 | |||
837 | /** Flush the stream input. | ||
838 | * The decoder's input buffer will be cleared and the state set to | ||
839 | * \c FLAC__SEEKABLE_STREAM_DECODER_OK. This will also turn off MD5 | ||
840 | * checking. | ||
841 | * | ||
842 | * \param decoder A decoder instance. | ||
843 | * \assert | ||
844 | * \code decoder != NULL \endcode | ||
845 | * \retval FLAC__bool | ||
846 | * \c true if successful, else \c false if a memory allocation | ||
847 | * or stream decoder error occurs. | ||
848 | */ | ||
849 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_flush(FLAC__SeekableStreamDecoder *decoder); | ||
850 | |||
851 | /** Reset the decoding process. | ||
852 | * The decoder's input buffer will be cleared and the state set to | ||
853 | * \c FLAC__SEEKABLE_STREAM_DECODER_OK. This is similar to | ||
854 | * FLAC__seekable_stream_decoder_finish() except that the settings are | ||
855 | * preserved; there is no need to call FLAC__seekable_stream_decoder_init() | ||
856 | * before decoding again. MD5 checking will be restored to its original | ||
857 | * setting. | ||
858 | * | ||
859 | * \param decoder A decoder instance. | ||
860 | * \assert | ||
861 | * \code decoder != NULL \endcode | ||
862 | * \retval FLAC__bool | ||
863 | * \c true if successful, else \c false if a memory allocation | ||
864 | * or stream decoder error occurs. | ||
865 | */ | ||
866 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_reset(FLAC__SeekableStreamDecoder *decoder); | ||
867 | |||
868 | /** This is inherited from FLAC__StreamDecoder; see | ||
869 | * FLAC__stream_decoder_process_single(). | ||
870 | * | ||
871 | * \param decoder A decoder instance. | ||
872 | * \assert | ||
873 | * \code decoder != NULL \endcode | ||
874 | * \retval FLAC__bool | ||
875 | * See above. | ||
876 | */ | ||
877 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_single(FLAC__SeekableStreamDecoder *decoder); | ||
878 | |||
879 | /** This is inherited from FLAC__StreamDecoder; see | ||
880 | * FLAC__stream_decoder_process_until_end_of_metadata(). | ||
881 | * | ||
882 | * \param decoder A decoder instance. | ||
883 | * \assert | ||
884 | * \code decoder != NULL \endcode | ||
885 | * \retval FLAC__bool | ||
886 | * See above. | ||
887 | */ | ||
888 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_until_end_of_metadata(FLAC__SeekableStreamDecoder *decoder); | ||
889 | |||
890 | /** This is inherited from FLAC__StreamDecoder; see | ||
891 | * FLAC__stream_decoder_process_until_end_of_stream(). | ||
892 | * | ||
893 | * \param decoder A decoder instance. | ||
894 | * \assert | ||
895 | * \code decoder != NULL \endcode | ||
896 | * \retval FLAC__bool | ||
897 | * See above. | ||
898 | */ | ||
899 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_until_end_of_stream(FLAC__SeekableStreamDecoder *decoder); | ||
900 | |||
901 | /** This is inherited from FLAC__StreamDecoder; see | ||
902 | * FLAC__stream_decoder_skip_single_frame(). | ||
903 | * | ||
904 | * \param decoder A decoder instance. | ||
905 | * \assert | ||
906 | * \code decoder != NULL \endcode | ||
907 | * \retval FLAC__bool | ||
908 | * See above. | ||
909 | */ | ||
910 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_skip_single_frame(FLAC__SeekableStreamDecoder *decoder); | ||
911 | |||
912 | /** Flush the input and seek to an absolute sample. | ||
913 | * Decoding will resume at the given sample. Note that because of | ||
914 | * this, the next write callback may contain a partial block. | ||
915 | * | ||
916 | * \param decoder A decoder instance. | ||
917 | * \param sample The target sample number to seek to. | ||
918 | * \assert | ||
919 | * \code decoder != NULL \endcode | ||
920 | * \retval FLAC__bool | ||
921 | * \c true if successful, else \c false. | ||
922 | */ | ||
923 | FLAC_API FLAC__bool FLAC__seekable_stream_decoder_seek_absolute(FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 sample); | ||
924 | |||
925 | /* \} */ | ||
926 | |||
927 | #ifdef __cplusplus | ||
928 | } | ||
929 | #endif | ||
930 | |||
931 | #endif | ||
diff --git a/apps/codecs/libFLAC/include/FLAC/seekable_stream_encoder.h b/apps/codecs/libFLAC/include/FLAC/seekable_stream_encoder.h new file mode 100644 index 0000000000..4efeb427be --- /dev/null +++ b/apps/codecs/libFLAC/include/FLAC/seekable_stream_encoder.h | |||
@@ -0,0 +1,992 @@ | |||
1 | /* libFLAC - Free Lossless Audio Codec library | ||
2 | * Copyright (C) 2002,2003,2004,2005 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__SEEKABLE_STREAM_ENCODER_H | ||
33 | #define FLAC__SEEKABLE_STREAM_ENCODER_H | ||
34 | |||
35 | #include "export.h" | ||
36 | #include "stream_encoder.h" | ||
37 | |||
38 | #ifdef __cplusplus | ||
39 | extern "C" { | ||
40 | #endif | ||
41 | |||
42 | |||
43 | /** \file include/FLAC/seekable_stream_encoder.h | ||
44 | * | ||
45 | * \brief | ||
46 | * This module contains the functions which implement the seekable stream | ||
47 | * encoder. | ||
48 | * | ||
49 | * See the detailed documentation in the | ||
50 | * \link flac_seekable_stream_encoder seekable stream encoder \endlink module. | ||
51 | */ | ||
52 | |||
53 | /** \defgroup flac_seekable_stream_encoder FLAC/seekable_stream_encoder.h: seekable stream encoder interface | ||
54 | * \ingroup flac_encoder | ||
55 | * | ||
56 | * \brief | ||
57 | * This module contains the functions which implement the seekable stream | ||
58 | * encoder. | ||
59 | * | ||
60 | * The basic usage of this encoder is as follows: | ||
61 | * - The program creates an instance of an encoder using | ||
62 | * FLAC__seekable_stream_encoder_new(). | ||
63 | * - The program overrides the default settings and sets callbacks using | ||
64 | * FLAC__seekable_stream_encoder_set_*() functions. | ||
65 | * - The program initializes the instance to validate the settings and | ||
66 | * prepare for encoding using FLAC__seekable_stream_encoder_init(). | ||
67 | * - The program calls FLAC__seekable_stream_encoder_process() or | ||
68 | * FLAC__seekable_stream_encoder_process_interleaved() to encode data, which | ||
69 | * subsequently calls the callbacks when there is encoder data ready | ||
70 | * to be written. | ||
71 | * - The program finishes the encoding with FLAC__seekable_stream_encoder_finish(), | ||
72 | * which causes the encoder to encode any data still in its input pipe, | ||
73 | * rewrite the metadata with the final encoding statistics, and finally | ||
74 | * reset the encoder to the uninitialized state. | ||
75 | * - The instance may be used again or deleted with | ||
76 | * FLAC__seekable_stream_encoder_delete(). | ||
77 | * | ||
78 | * The seekable stream encoder is a wrapper around the | ||
79 | * \link flac_stream_encoder stream encoder \endlink with callbacks for | ||
80 | * seeking the output and reporting the output stream position. This | ||
81 | * allows the encoder to go back and rewrite some of the metadata after | ||
82 | * encoding if necessary, and provides the metadata callback of the stream | ||
83 | * encoder internally. However, you must provide seek and tell callbacks | ||
84 | * (see FLAC__seekable_stream_encoder_set_seek_callback() and | ||
85 | * FLAC__seekable_stream_encoder_set_tell_callback()). | ||
86 | * | ||
87 | * Make sure to read the detailed description of the | ||
88 | * \link flac_stream_encoder stream encoder module \endlink since the | ||
89 | * seekable stream encoder inherits much of its behavior. | ||
90 | * | ||
91 | * \note | ||
92 | * If you are writing the FLAC data to a file, make sure it is open | ||
93 | * for update (e.g. mode "w+" for stdio streams). This is because after | ||
94 | * the first encoding pass, the encoder will try to seek back to the | ||
95 | * beginning of the stream, to the STREAMINFO block, to write some data | ||
96 | * there. | ||
97 | * | ||
98 | * \note | ||
99 | * The "set" functions may only be called when the encoder is in the | ||
100 | * state FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED, i.e. after | ||
101 | * FLAC__seekable_stream_encoder_new() or FLAC__seekable_stream_encoder_finish(), but | ||
102 | * before FLAC__seekable_stream_encoder_init(). If this is the case they will | ||
103 | * return \c true, otherwise \c false. | ||
104 | * | ||
105 | * \note | ||
106 | * FLAC__seekable_stream_encoder_finish() resets all settings to the constructor | ||
107 | * defaults, including the callbacks. | ||
108 | * | ||
109 | * \{ | ||
110 | */ | ||
111 | |||
112 | |||
113 | /** State values for a FLAC__SeekableStreamEncoder | ||
114 | * | ||
115 | * The encoder's state can be obtained by calling FLAC__seekable_stream_encoder_get_state(). | ||
116 | */ | ||
117 | typedef enum { | ||
118 | |||
119 | FLAC__SEEKABLE_STREAM_ENCODER_OK = 0, | ||
120 | /**< The encoder is in the normal OK state. */ | ||
121 | |||
122 | FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR, | ||
123 | /**< An error occurred in the underlying stream encoder; | ||
124 | * check FLAC__seekable_stream_encoder_get_stream_encoder_state(). | ||
125 | */ | ||
126 | |||
127 | FLAC__SEEKABLE_STREAM_ENCODER_MEMORY_ALLOCATION_ERROR, | ||
128 | /**< Memory allocation failed. */ | ||
129 | |||
130 | FLAC__SEEKABLE_STREAM_ENCODER_WRITE_ERROR, | ||
131 | /**< The write callback returned an error. */ | ||
132 | |||
133 | FLAC__SEEKABLE_STREAM_ENCODER_READ_ERROR, | ||
134 | /**< The read callback returned an error. */ | ||
135 | |||
136 | FLAC__SEEKABLE_STREAM_ENCODER_SEEK_ERROR, | ||
137 | /**< The seek callback returned an error. */ | ||
138 | |||
139 | FLAC__SEEKABLE_STREAM_ENCODER_TELL_ERROR, | ||
140 | /**< The tell callback returned an error. */ | ||
141 | |||
142 | FLAC__SEEKABLE_STREAM_ENCODER_ALREADY_INITIALIZED, | ||
143 | /**< FLAC__seekable_stream_encoder_init() was called when the encoder was | ||
144 | * already initialized, usually because | ||
145 | * FLAC__seekable_stream_encoder_finish() was not called. | ||
146 | */ | ||
147 | |||
148 | FLAC__SEEKABLE_STREAM_ENCODER_INVALID_CALLBACK, | ||
149 | /**< FLAC__seekable_stream_encoder_init() was called without all | ||
150 | * callbacks being set. | ||
151 | */ | ||
152 | |||
153 | FLAC__SEEKABLE_STREAM_ENCODER_INVALID_SEEKTABLE, | ||
154 | /**< An invalid seek table was passed is the metadata to | ||
155 | * FLAC__seekable_stream_encoder_set_metadata(). | ||
156 | */ | ||
157 | |||
158 | FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED | ||
159 | /**< The encoder is in the uninitialized state. */ | ||
160 | |||
161 | } FLAC__SeekableStreamEncoderState; | ||
162 | |||
163 | /** Maps a FLAC__SeekableStreamEncoderState to a C string. | ||
164 | * | ||
165 | * Using a FLAC__SeekableStreamEncoderState as the index to this array | ||
166 | * will give the string equivalent. The contents should not be modified. | ||
167 | */ | ||
168 | extern FLAC_API const char * const FLAC__SeekableStreamEncoderStateString[]; | ||
169 | |||
170 | |||
171 | /** Return values for the FLAC__SeekableStreamEncoder seek callback. | ||
172 | */ | ||
173 | typedef enum { | ||
174 | |||
175 | FLAC__SEEKABLE_STREAM_ENCODER_SEEK_STATUS_OK, | ||
176 | /**< The seek was OK and encoding can continue. */ | ||
177 | |||
178 | FLAC__SEEKABLE_STREAM_ENCODER_SEEK_STATUS_ERROR | ||
179 | /**< An unrecoverable error occurred. The encoder will return from the process call. */ | ||
180 | |||
181 | } FLAC__SeekableStreamEncoderSeekStatus; | ||
182 | |||
183 | /** Maps a FLAC__SeekableStreamEncoderSeekStatus to a C string. | ||
184 | * | ||
185 | * Using a FLAC__SeekableStreamEncoderSeekStatus as the index to this array | ||
186 | * will give the string equivalent. The contents should not be modified. | ||
187 | */ | ||
188 | extern FLAC_API const char * const FLAC__SeekableStreamEncoderSeekStatusString[]; | ||
189 | |||
190 | |||
191 | /** Return values for the FLAC__SeekableStreamEncoder tell callback. | ||
192 | */ | ||
193 | typedef enum { | ||
194 | |||
195 | FLAC__SEEKABLE_STREAM_ENCODER_TELL_STATUS_OK, | ||
196 | /**< The tell was OK and encoding can continue. */ | ||
197 | |||
198 | FLAC__SEEKABLE_STREAM_ENCODER_TELL_STATUS_ERROR | ||
199 | /**< An unrecoverable error occurred. The encoder will return from the process call. */ | ||
200 | |||
201 | } FLAC__SeekableStreamEncoderTellStatus; | ||
202 | |||
203 | /** Maps a FLAC__SeekableStreamEncoderTellStatus to a C string. | ||
204 | * | ||
205 | * Using a FLAC__SeekableStreamEncoderTellStatus as the index to this array | ||
206 | * will give the string equivalent. The contents should not be modified. | ||
207 | */ | ||
208 | extern FLAC_API const char * const FLAC__SeekableStreamEncoderTellStatusString[]; | ||
209 | |||
210 | |||
211 | /*********************************************************************** | ||
212 | * | ||
213 | * class FLAC__SeekableStreamEncoder | ||
214 | * | ||
215 | ***********************************************************************/ | ||
216 | |||
217 | struct FLAC__SeekableStreamEncoderProtected; | ||
218 | struct FLAC__SeekableStreamEncoderPrivate; | ||
219 | /** The opaque structure definition for the seekable stream encoder type. | ||
220 | * See the \link flac_seekable_stream_encoder seekable stream encoder module \endlink | ||
221 | * for a detailed description. | ||
222 | */ | ||
223 | typedef struct { | ||
224 | struct FLAC__SeekableStreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */ | ||
225 | struct FLAC__SeekableStreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */ | ||
226 | } FLAC__SeekableStreamEncoder; | ||
227 | |||
228 | /** Signature for the seek callback. | ||
229 | * See FLAC__seekable_stream_encoder_set_seek_callback() for more info. | ||
230 | * | ||
231 | * \param encoder The encoder instance calling the callback. | ||
232 | * \param absolute_byte_offset The offset from the beginning of the stream | ||
233 | * to seek to. | ||
234 | * \param client_data The callee's client data set through | ||
235 | * FLAC__seekable_stream_encoder_set_client_data(). | ||
236 | * \retval FLAC__SeekableStreamEncoderSeekStatus | ||
237 | * The callee's return status. | ||
238 | */ | ||
239 | typedef FLAC__SeekableStreamEncoderSeekStatus (*FLAC__SeekableStreamEncoderSeekCallback)(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data); | ||
240 | |||
241 | /** Signature for the tell callback. | ||
242 | * See FLAC__seekable_stream_encoder_set_tell_callback() for more info. | ||
243 | * | ||
244 | * \warning | ||
245 | * The callback must return the true current byte offset of the output to | ||
246 | * which the encoder is writing. If you are buffering the output, make | ||
247 | * sure and take this into account. If you are writing directly to a | ||
248 | * FILE* from your write callback, ftell() is sufficient. If you are | ||
249 | * writing directly to a file descriptor from your write callback, you | ||
250 | * can use lseek(fd, SEEK_CUR, 0). The encoder may later seek back to | ||
251 | * these points to rewrite metadata after encoding. | ||
252 | * | ||
253 | * \param encoder The encoder instance calling the callback. | ||
254 | * \param absolute_byte_offset The address at which to store the current | ||
255 | * position of the output. | ||
256 | * \param client_data The callee's client data set through | ||
257 | * FLAC__seekable_stream_encoder_set_client_data(). | ||
258 | * \retval FLAC__SeekableStreamEncoderTellStatus | ||
259 | * The callee's return status. | ||
260 | */ | ||
261 | typedef FLAC__SeekableStreamEncoderTellStatus (*FLAC__SeekableStreamEncoderTellCallback)(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data); | ||
262 | |||
263 | /** Signature for the write callback. | ||
264 | * See FLAC__seekable_stream_encoder_set_write_callback() | ||
265 | * and FLAC__StreamEncoderWriteCallback for more info. | ||
266 | * | ||
267 | * \param encoder The encoder instance calling the callback. | ||
268 | * \param buffer An array of encoded data of length \a bytes. | ||
269 | * \param bytes The byte length of \a buffer. | ||
270 | * \param samples The number of samples encoded by \a buffer. | ||
271 | * \c 0 has a special meaning; see | ||
272 | * FLAC__stream_encoder_set_write_callback(). | ||
273 | * \param current_frame The number of current frame being encoded. | ||
274 | * \param client_data The callee's client data set through | ||
275 | * FLAC__seekable_stream_encoder_set_client_data(). | ||
276 | * \retval FLAC__StreamEncoderWriteStatus | ||
277 | * The callee's return status. | ||
278 | */ | ||
279 | typedef FLAC__StreamEncoderWriteStatus (*FLAC__SeekableStreamEncoderWriteCallback)(const FLAC__SeekableStreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data); | ||
280 | |||
281 | |||
282 | /*********************************************************************** | ||
283 | * | ||
284 | * Class constructor/destructor | ||
285 | * | ||
286 | ***********************************************************************/ | ||
287 | |||
288 | /** Create a new seekable stream encoder instance. The instance is created with | ||
289 | * default settings; see the individual FLAC__seekable_stream_encoder_set_*() | ||
290 | * functions for each setting's default. | ||
291 | * | ||
292 | * \retval FLAC__SeekableStreamEncoder* | ||
293 | * \c NULL if there was an error allocating memory, else the new instance. | ||
294 | */ | ||
295 | FLAC_API FLAC__SeekableStreamEncoder *FLAC__seekable_stream_encoder_new(); | ||
296 | |||
297 | /** Free an encoder instance. Deletes the object pointed to by \a encoder. | ||
298 | * | ||
299 | * \param encoder A pointer to an existing encoder. | ||
300 | * \assert | ||
301 | * \code encoder != NULL \endcode | ||
302 | */ | ||
303 | FLAC_API void FLAC__seekable_stream_encoder_delete(FLAC__SeekableStreamEncoder *encoder); | ||
304 | |||
305 | /*********************************************************************** | ||
306 | * | ||
307 | * Public class method prototypes | ||
308 | * | ||
309 | ***********************************************************************/ | ||
310 | |||
311 | /** This is inherited from FLAC__StreamEncoder; see | ||
312 | * FLAC__stream_encoder_set_verify(). | ||
313 | * | ||
314 | * \default \c true | ||
315 | * \param encoder An encoder instance to set. | ||
316 | * \param value See above. | ||
317 | * \assert | ||
318 | * \code encoder != NULL \endcode | ||
319 | * \retval FLAC__bool | ||
320 | * \c false if the encoder is already initialized, else \c true. | ||
321 | */ | ||
322 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_verify(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value); | ||
323 | |||
324 | /** This is inherited from FLAC__StreamEncoder; see | ||
325 | * FLAC__stream_encoder_set_streamable_subset(). | ||
326 | * | ||
327 | * \default \c true | ||
328 | * \param encoder An encoder instance to set. | ||
329 | * \param value See above. | ||
330 | * \assert | ||
331 | * \code encoder != NULL \endcode | ||
332 | * \retval FLAC__bool | ||
333 | * \c false if the encoder is already initialized, else \c true. | ||
334 | */ | ||
335 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_streamable_subset(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value); | ||
336 | |||
337 | /** This is inherited from FLAC__StreamEncoder; see | ||
338 | * FLAC__stream_encoder_set_do_mid_side_stereo(). | ||
339 | * | ||
340 | * \default \c false | ||
341 | * \param encoder An encoder instance to set. | ||
342 | * \param value See above. | ||
343 | * \assert | ||
344 | * \code encoder != NULL \endcode | ||
345 | * \retval FLAC__bool | ||
346 | * \c false if the encoder is already initialized, else \c true. | ||
347 | */ | ||
348 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_do_mid_side_stereo(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value); | ||
349 | |||
350 | /** This is inherited from FLAC__StreamEncoder; see | ||
351 | * FLAC__stream_encoder_set_loose_mid_side_stereo(). | ||
352 | * | ||
353 | * \default \c false | ||
354 | * \param encoder An encoder instance to set. | ||
355 | * \param value See above. | ||
356 | * \assert | ||
357 | * \code encoder != NULL \endcode | ||
358 | * \retval FLAC__bool | ||
359 | * \c false if the encoder is already initialized, else \c true. | ||
360 | */ | ||
361 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_loose_mid_side_stereo(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value); | ||
362 | |||
363 | /** This is inherited from FLAC__StreamEncoder; see | ||
364 | * FLAC__stream_encoder_set_channels(). | ||
365 | * | ||
366 | * \default \c 2 | ||
367 | * \param encoder An encoder instance to set. | ||
368 | * \param value See above. | ||
369 | * \assert | ||
370 | * \code encoder != NULL \endcode | ||
371 | * \retval FLAC__bool | ||
372 | * \c false if the encoder is already initialized, else \c true. | ||
373 | */ | ||
374 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_channels(FLAC__SeekableStreamEncoder *encoder, unsigned value); | ||
375 | |||
376 | /** This is inherited from FLAC__StreamEncoder; see | ||
377 | * FLAC__stream_encoder_set_bits_per_sample(). | ||
378 | * | ||
379 | * \warning | ||
380 | * Do not feed the encoder data that is wider than the value you | ||
381 | * set here or you will generate an invalid stream. | ||
382 | * | ||
383 | * \default \c 16 | ||
384 | * \param encoder An encoder instance to set. | ||
385 | * \param value See above. | ||
386 | * \assert | ||
387 | * \code encoder != NULL \endcode | ||
388 | * \retval FLAC__bool | ||
389 | * \c false if the encoder is already initialized, else \c true. | ||
390 | */ | ||
391 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_bits_per_sample(FLAC__SeekableStreamEncoder *encoder, unsigned value); | ||
392 | |||
393 | /** This is inherited from FLAC__StreamEncoder; see | ||
394 | * FLAC__stream_encoder_set_sample_rate(). | ||
395 | * | ||
396 | * \default \c 44100 | ||
397 | * \param encoder An encoder instance to set. | ||
398 | * \param value See above. | ||
399 | * \assert | ||
400 | * \code encoder != NULL \endcode | ||
401 | * \retval FLAC__bool | ||
402 | * \c false if the encoder is already initialized, else \c true. | ||
403 | */ | ||
404 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_sample_rate(FLAC__SeekableStreamEncoder *encoder, unsigned value); | ||
405 | |||
406 | /** This is inherited from FLAC__StreamEncoder; see | ||
407 | * FLAC__stream_encoder_set_blocksize(). | ||
408 | * | ||
409 | * \default \c 1152 | ||
410 | * \param encoder An encoder instance to set. | ||
411 | * \param value See above. | ||
412 | * \assert | ||
413 | * \code encoder != NULL \endcode | ||
414 | * \retval FLAC__bool | ||
415 | * \c false if the encoder is already initialized, else \c true. | ||
416 | */ | ||
417 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_blocksize(FLAC__SeekableStreamEncoder *encoder, unsigned value); | ||
418 | |||
419 | /** This is inherited from FLAC__StreamEncoder; see | ||
420 | * FLAC__stream_encoder_set_max_lpc_order(). | ||
421 | * | ||
422 | * \default \c 0 | ||
423 | * \param encoder An encoder instance to set. | ||
424 | * \param value See above. | ||
425 | * \assert | ||
426 | * \code encoder != NULL \endcode | ||
427 | * \retval FLAC__bool | ||
428 | * \c false if the encoder is already initialized, else \c true. | ||
429 | */ | ||
430 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_max_lpc_order(FLAC__SeekableStreamEncoder *encoder, unsigned value); | ||
431 | |||
432 | /** This is inherited from FLAC__StreamEncoder; see | ||
433 | * FLAC__stream_encoder_set_qlp_coeff_precision(). | ||
434 | * | ||
435 | * \note | ||
436 | * In the current implementation, qlp_coeff_precision + bits_per_sample must | ||
437 | * be less than 32. | ||
438 | * | ||
439 | * \default \c 0 | ||
440 | * \param encoder An encoder instance to set. | ||
441 | * \param value See above. | ||
442 | * \assert | ||
443 | * \code encoder != NULL \endcode | ||
444 | * \retval FLAC__bool | ||
445 | * \c false if the encoder is already initialized, else \c true. | ||
446 | */ | ||
447 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_qlp_coeff_precision(FLAC__SeekableStreamEncoder *encoder, unsigned value); | ||
448 | |||
449 | /** This is inherited from FLAC__StreamEncoder; see | ||
450 | * FLAC__stream_encoder_set_do_qlp_coeff_prec_search(). | ||
451 | * | ||
452 | * \default \c false | ||
453 | * \param encoder An encoder instance to set. | ||
454 | * \param value See above. | ||
455 | * \assert | ||
456 | * \code encoder != NULL \endcode | ||
457 | * \retval FLAC__bool | ||
458 | * \c false if the encoder is already initialized, else \c true. | ||
459 | */ | ||
460 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value); | ||
461 | |||
462 | /** This is inherited from FLAC__StreamEncoder; see | ||
463 | * FLAC__stream_encoder_set_do_escape_coding(). | ||
464 | * | ||
465 | * \default \c false | ||
466 | * \param encoder An encoder instance to set. | ||
467 | * \param value See above. | ||
468 | * \assert | ||
469 | * \code encoder != NULL \endcode | ||
470 | * \retval FLAC__bool | ||
471 | * \c false if the encoder is already initialized, else \c true. | ||
472 | */ | ||
473 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_do_escape_coding(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value); | ||
474 | |||
475 | /** This is inherited from FLAC__StreamEncoder; see | ||
476 | * FLAC__stream_encoder_set_do_exhaustive_model_search(). | ||
477 | * | ||
478 | * \default \c false | ||
479 | * \param encoder An encoder instance to set. | ||
480 | * \param value See above. | ||
481 | * \assert | ||
482 | * \code encoder != NULL \endcode | ||
483 | * \retval FLAC__bool | ||
484 | * \c false if the encoder is already initialized, else \c true. | ||
485 | */ | ||
486 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_do_exhaustive_model_search(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value); | ||
487 | |||
488 | /** This is inherited from FLAC__StreamEncoder; see | ||
489 | * FLAC__stream_encoder_set_min_residual_partition_order(). | ||
490 | * | ||
491 | * \default \c 0 | ||
492 | * \param encoder An encoder instance to set. | ||
493 | * \param value See above. | ||
494 | * \assert | ||
495 | * \code encoder != NULL \endcode | ||
496 | * \retval FLAC__bool | ||
497 | * \c false if the encoder is already initialized, else \c true. | ||
498 | */ | ||
499 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_min_residual_partition_order(FLAC__SeekableStreamEncoder *encoder, unsigned value); | ||
500 | |||
501 | /** This is inherited from FLAC__StreamEncoder; see | ||
502 | * FLAC__stream_encoder_set_max_residual_partition_order(). | ||
503 | * | ||
504 | * \default \c 0 | ||
505 | * \param encoder An encoder instance to set. | ||
506 | * \param value See above. | ||
507 | * \assert | ||
508 | * \code encoder != NULL \endcode | ||
509 | * \retval FLAC__bool | ||
510 | * \c false if the encoder is already initialized, else \c true. | ||
511 | */ | ||
512 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_max_residual_partition_order(FLAC__SeekableStreamEncoder *encoder, unsigned value); | ||
513 | |||
514 | /** This is inherited from FLAC__StreamEncoder; see | ||
515 | * FLAC__stream_encoder_set_rice_parameter_search_dist(). | ||
516 | * | ||
517 | * \default \c 0 | ||
518 | * \param encoder An encoder instance to set. | ||
519 | * \param value See above. | ||
520 | * \assert | ||
521 | * \code encoder != NULL \endcode | ||
522 | * \retval FLAC__bool | ||
523 | * \c false if the encoder is already initialized, else \c true. | ||
524 | */ | ||
525 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_rice_parameter_search_dist(FLAC__SeekableStreamEncoder *encoder, unsigned value); | ||
526 | |||
527 | /** This is inherited from FLAC__StreamEncoder; see | ||
528 | * FLAC__stream_encoder_set_total_samples_estimate(). | ||
529 | * | ||
530 | * \default \c 0 | ||
531 | * \param encoder An encoder instance to set. | ||
532 | * \param value See above. | ||
533 | * \assert | ||
534 | * \code encoder != NULL \endcode | ||
535 | * \retval FLAC__bool | ||
536 | * \c false if the encoder is already initialized, else \c true. | ||
537 | */ | ||
538 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_total_samples_estimate(FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 value); | ||
539 | |||
540 | /** This is inherited from FLAC__StreamEncoder; see | ||
541 | * FLAC__stream_encoder_set_metadata(). | ||
542 | * | ||
543 | * \note | ||
544 | * SEEKTABLE blocks are handled specially. Since you will not know | ||
545 | * the values for the seek point stream offsets, you should pass in | ||
546 | * a SEEKTABLE 'template', that is, a SEEKTABLE object with the | ||
547 | * required sample numbers (or placeholder points), with \c 0 for the | ||
548 | * \a frame_samples and \a stream_offset fields for each point. While | ||
549 | * encoding, the encoder will fill them in for you and when encoding | ||
550 | * is finished, it will seek back and write the real values into the | ||
551 | * SEEKTABLE block in the stream. There are helper routines for | ||
552 | * manipulating seektable template blocks; see metadata.h: | ||
553 | * FLAC__metadata_object_seektable_template_*(). | ||
554 | * | ||
555 | * \note | ||
556 | * The encoder instance \b will modify the first \c SEEKTABLE block | ||
557 | * as it transforms the template to a valid seektable while encoding, | ||
558 | * but it is still up to the caller to free all metadata blocks after | ||
559 | * encoding. | ||
560 | * | ||
561 | * \default \c NULL, 0 | ||
562 | * \param encoder An encoder instance to set. | ||
563 | * \param metadata See above. | ||
564 | * \param num_blocks See above. | ||
565 | * \assert | ||
566 | * \code encoder != NULL \endcode | ||
567 | * \retval FLAC__bool | ||
568 | * \c false if the encoder is already initialized, else \c true. | ||
569 | */ | ||
570 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_metadata(FLAC__SeekableStreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks); | ||
571 | |||
572 | /** Set the seek callback. | ||
573 | * The supplied function will be called when the encoder needs to seek | ||
574 | * the output stream. The encoder will pass the absolute byte offset | ||
575 | * to seek to, 0 meaning the beginning of the stream. | ||
576 | * | ||
577 | * \note | ||
578 | * The callback is mandatory and must be set before initialization. | ||
579 | * | ||
580 | * \default \c NULL | ||
581 | * \param encoder An encoder instance to set. | ||
582 | * \param value See above. | ||
583 | * \assert | ||
584 | * \code encoder != NULL \endcode | ||
585 | * \code value != NULL \endcode | ||
586 | * \retval FLAC__bool | ||
587 | * \c false if the encoder is already initialized, else \c true. | ||
588 | */ | ||
589 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_seek_callback(FLAC__SeekableStreamEncoder *encoder, FLAC__SeekableStreamEncoderSeekCallback value); | ||
590 | |||
591 | /** Set the tell callback. | ||
592 | * The supplied function will be called when the encoder needs to know | ||
593 | * the current position of the output stream. | ||
594 | * | ||
595 | * \note | ||
596 | * The callback is mandatory and must be set before initialization. | ||
597 | * | ||
598 | * \default \c NULL | ||
599 | * \param encoder An encoder instance to set. | ||
600 | * \param value See above. | ||
601 | * \assert | ||
602 | * \code encoder != NULL \endcode | ||
603 | * \code value != NULL \endcode | ||
604 | * \retval FLAC__bool | ||
605 | * \c false if the encoder is already initialized, else \c true. | ||
606 | */ | ||
607 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_tell_callback(FLAC__SeekableStreamEncoder *encoder, FLAC__SeekableStreamEncoderTellCallback value); | ||
608 | |||
609 | /** Set the write callback. | ||
610 | * This is inherited from FLAC__StreamEncoder; see | ||
611 | * FLAC__stream_encoder_set_write_callback(). | ||
612 | * | ||
613 | * \note | ||
614 | * The callback is mandatory and must be set before initialization. | ||
615 | * | ||
616 | * \default \c NULL | ||
617 | * \param encoder An encoder instance to set. | ||
618 | * \param value See above. | ||
619 | * \assert | ||
620 | * \code encoder != NULL \endcode | ||
621 | * \code value != NULL \endcode | ||
622 | * \retval FLAC__bool | ||
623 | * \c false if the encoder is already initialized, else \c true. | ||
624 | */ | ||
625 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_write_callback(FLAC__SeekableStreamEncoder *encoder, FLAC__SeekableStreamEncoderWriteCallback value); | ||
626 | |||
627 | /** Set the client data to be passed back to callbacks. | ||
628 | * This value will be supplied to callbacks in their \a client_data | ||
629 | * argument. | ||
630 | * | ||
631 | * \default \c NULL | ||
632 | * \param encoder An encoder instance to set. | ||
633 | * \param value See above. | ||
634 | * \assert | ||
635 | * \code encoder != NULL \endcode | ||
636 | * \retval FLAC__bool | ||
637 | * \c false if the encoder is already initialized, else \c true. | ||
638 | */ | ||
639 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_client_data(FLAC__SeekableStreamEncoder *encoder, void *value); | ||
640 | |||
641 | /** Get the current encoder state. | ||
642 | * | ||
643 | * \param encoder An encoder instance to query. | ||
644 | * \assert | ||
645 | * \code encoder != NULL \endcode | ||
646 | * \retval FLAC__SeekableStreamEncoderState | ||
647 | * The current encoder state. | ||
648 | */ | ||
649 | FLAC_API FLAC__SeekableStreamEncoderState FLAC__seekable_stream_encoder_get_state(const FLAC__SeekableStreamEncoder *encoder); | ||
650 | |||
651 | /** Get the state of the underlying stream encoder. | ||
652 | * Useful when the seekable stream encoder state is | ||
653 | * \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR. | ||
654 | * | ||
655 | * \param encoder An encoder instance to query. | ||
656 | * \assert | ||
657 | * \code encoder != NULL \endcode | ||
658 | * \retval FLAC__StreamEncoderState | ||
659 | * The stream encoder state. | ||
660 | */ | ||
661 | FLAC_API FLAC__StreamEncoderState FLAC__seekable_stream_encoder_get_stream_encoder_state(const FLAC__SeekableStreamEncoder *encoder); | ||
662 | |||
663 | /** Get the state of the underlying stream encoder's verify decoder. | ||
664 | * Useful when the seekable stream encoder state is | ||
665 | * \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and the | ||
666 | * stream encoder state is \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR. | ||
667 | * | ||
668 | * \param encoder An encoder instance to query. | ||
669 | * \assert | ||
670 | * \code encoder != NULL \endcode | ||
671 | * \retval FLAC__StreamDecoderState | ||
672 | * The stream encoder state. | ||
673 | */ | ||
674 | FLAC_API FLAC__StreamDecoderState FLAC__seekable_stream_encoder_get_verify_decoder_state(const FLAC__SeekableStreamEncoder *encoder); | ||
675 | |||
676 | /** Get the current encoder state as a C string. | ||
677 | * This version automatically resolves | ||
678 | * \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR by getting the | ||
679 | * stream encoder's state. | ||
680 | * | ||
681 | * \param encoder A encoder instance to query. | ||
682 | * \assert | ||
683 | * \code encoder != NULL \endcode | ||
684 | * \retval const char * | ||
685 | * The encoder state as a C string. Do not modify the contents. | ||
686 | */ | ||
687 | FLAC_API const char *FLAC__seekable_stream_encoder_get_resolved_state_string(const FLAC__SeekableStreamEncoder *encoder); | ||
688 | |||
689 | /** Get relevant values about the nature of a verify decoder error. | ||
690 | * Inherited from FLAC__stream_encoder_get_verify_decoder_error_stats(). | ||
691 | * Useful when the seekable stream encoder state is | ||
692 | * \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and the | ||
693 | * stream encoder state is | ||
694 | * \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR. | ||
695 | * | ||
696 | * \param encoder An encoder instance to query. | ||
697 | * \param absolute_sample The absolute sample number of the mismatch. | ||
698 | * \param frame_number The number of the frame in which the mismatch occurred. | ||
699 | * \param channel The channel in which the mismatch occurred. | ||
700 | * \param sample The number of the sample (relative to the frame) in | ||
701 | * which the mismatch occurred. | ||
702 | * \param expected The expected value for the sample in question. | ||
703 | * \param got The actual value returned by the decoder. | ||
704 | * \assert | ||
705 | * \code encoder != NULL \endcode | ||
706 | */ | ||
707 | FLAC_API void FLAC__seekable_stream_encoder_get_verify_decoder_error_stats(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got); | ||
708 | |||
709 | /** Get the "verify" flag. | ||
710 | * This is inherited from FLAC__StreamEncoder; see | ||
711 | * FLAC__stream_encoder_get_verify(). | ||
712 | * | ||
713 | * \param encoder An encoder instance to query. | ||
714 | * \assert | ||
715 | * \code encoder != NULL \endcode | ||
716 | * \retval FLAC__bool | ||
717 | * See FLAC__seekable_stream_encoder_set_verify(). | ||
718 | */ | ||
719 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_verify(const FLAC__SeekableStreamEncoder *encoder); | ||
720 | |||
721 | /** Get the "streamable subset" flag. | ||
722 | * This is inherited from FLAC__StreamEncoder; see | ||
723 | * FLAC__stream_encoder_get_streamable_subset(). | ||
724 | * | ||
725 | * \param encoder An encoder instance to query. | ||
726 | * \assert | ||
727 | * \code encoder != NULL \endcode | ||
728 | * \retval FLAC__bool | ||
729 | * See FLAC__seekable_stream_encoder_set_streamable_subset(). | ||
730 | */ | ||
731 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_streamable_subset(const FLAC__SeekableStreamEncoder *encoder); | ||
732 | |||
733 | /** Get the "mid/side stereo coding" flag. | ||
734 | * This is inherited from FLAC__StreamEncoder; see | ||
735 | * FLAC__stream_encoder_get_do_mid_side_stereo(). | ||
736 | * | ||
737 | * \param encoder An encoder instance to query. | ||
738 | * \assert | ||
739 | * \code encoder != NULL \endcode | ||
740 | * \retval FLAC__bool | ||
741 | * See FLAC__seekable_stream_encoder_get_do_mid_side_stereo(). | ||
742 | */ | ||
743 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_mid_side_stereo(const FLAC__SeekableStreamEncoder *encoder); | ||
744 | |||
745 | /** Get the "adaptive mid/side switching" flag. | ||
746 | * This is inherited from FLAC__StreamEncoder; see | ||
747 | * FLAC__stream_encoder_get_loose_mid_side_stereo(). | ||
748 | * | ||
749 | * \param encoder An encoder instance to query. | ||
750 | * \assert | ||
751 | * \code encoder != NULL \endcode | ||
752 | * \retval FLAC__bool | ||
753 | * See FLAC__seekable_stream_encoder_set_loose_mid_side_stereo(). | ||
754 | */ | ||
755 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_loose_mid_side_stereo(const FLAC__SeekableStreamEncoder *encoder); | ||
756 | |||
757 | /** Get the number of input channels being processed. | ||
758 | * This is inherited from FLAC__StreamEncoder; see | ||
759 | * FLAC__stream_encoder_get_channels(). | ||
760 | * | ||
761 | * \param encoder An encoder instance to query. | ||
762 | * \assert | ||
763 | * \code encoder != NULL \endcode | ||
764 | * \retval unsigned | ||
765 | * See FLAC__seekable_stream_encoder_set_channels(). | ||
766 | */ | ||
767 | FLAC_API unsigned FLAC__seekable_stream_encoder_get_channels(const FLAC__SeekableStreamEncoder *encoder); | ||
768 | |||
769 | /** Get the input sample resolution setting. | ||
770 | * This is inherited from FLAC__StreamEncoder; see | ||
771 | * FLAC__stream_encoder_get_bits_per_sample(). | ||
772 | * | ||
773 | * \param encoder An encoder instance to query. | ||
774 | * \assert | ||
775 | * \code encoder != NULL \endcode | ||
776 | * \retval unsigned | ||
777 | * See FLAC__seekable_stream_encoder_set_bits_per_sample(). | ||
778 | */ | ||
779 | FLAC_API unsigned FLAC__seekable_stream_encoder_get_bits_per_sample(const FLAC__SeekableStreamEncoder *encoder); | ||
780 | |||
781 | /** Get the input sample rate setting. | ||
782 | * This is inherited from FLAC__StreamEncoder; see | ||
783 | * FLAC__stream_encoder_get_sample_rate(). | ||
784 | * | ||
785 | * \param encoder An encoder instance to query. | ||
786 | * \assert | ||
787 | * \code encoder != NULL \endcode | ||
788 | * \retval unsigned | ||
789 | * See FLAC__seekable_stream_encoder_set_sample_rate(). | ||
790 | */ | ||
791 | FLAC_API unsigned FLAC__seekable_stream_encoder_get_sample_rate(const FLAC__SeekableStreamEncoder *encoder); | ||
792 | |||
793 | /** Get the blocksize setting. | ||
794 | * This is inherited from FLAC__StreamEncoder; see | ||
795 | * FLAC__stream_encoder_get_blocksize(). | ||
796 | * | ||
797 | * \param encoder An encoder instance to query. | ||
798 | * \assert | ||
799 | * \code encoder != NULL \endcode | ||
800 | * \retval unsigned | ||
801 | * See FLAC__seekable_stream_encoder_set_blocksize(). | ||
802 | */ | ||
803 | FLAC_API unsigned FLAC__seekable_stream_encoder_get_blocksize(const FLAC__SeekableStreamEncoder *encoder); | ||
804 | |||
805 | /** Get the maximum LPC order setting. | ||
806 | * This is inherited from FLAC__StreamEncoder; see | ||
807 | * FLAC__stream_encoder_get_max_lpc_order(). | ||
808 | * | ||
809 | * \param encoder An encoder instance to query. | ||
810 | * \assert | ||
811 | * \code encoder != NULL \endcode | ||
812 | * \retval unsigned | ||
813 | * See FLAC__seekable_stream_encoder_set_max_lpc_order(). | ||
814 | */ | ||
815 | FLAC_API unsigned FLAC__seekable_stream_encoder_get_max_lpc_order(const FLAC__SeekableStreamEncoder *encoder); | ||
816 | |||
817 | /** Get the quantized linear predictor coefficient precision setting. | ||
818 | * This is inherited from FLAC__StreamEncoder; see | ||
819 | * FLAC__stream_encoder_get_qlp_coeff_precision(). | ||
820 | * | ||
821 | * \param encoder An encoder instance to query. | ||
822 | * \assert | ||
823 | * \code encoder != NULL \endcode | ||
824 | * \retval unsigned | ||
825 | * See FLAC__seekable_stream_encoder_set_qlp_coeff_precision(). | ||
826 | */ | ||
827 | FLAC_API unsigned FLAC__seekable_stream_encoder_get_qlp_coeff_precision(const FLAC__SeekableStreamEncoder *encoder); | ||
828 | |||
829 | /** Get the qlp coefficient precision search flag. | ||
830 | * This is inherited from FLAC__StreamEncoder; see | ||
831 | * FLAC__stream_encoder_get_do_qlp_coeff_prec_search(). | ||
832 | * | ||
833 | * \param encoder An encoder instance to query. | ||
834 | * \assert | ||
835 | * \code encoder != NULL \endcode | ||
836 | * \retval FLAC__bool | ||
837 | * See FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search(). | ||
838 | */ | ||
839 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search(const FLAC__SeekableStreamEncoder *encoder); | ||
840 | |||
841 | /** Get the "escape coding" flag. | ||
842 | * This is inherited from FLAC__StreamEncoder; see | ||
843 | * FLAC__stream_encoder_get_do_escape_coding(). | ||
844 | * | ||
845 | * \param encoder An encoder instance to query. | ||
846 | * \assert | ||
847 | * \code encoder != NULL \endcode | ||
848 | * \retval FLAC__bool | ||
849 | * See FLAC__seekable_stream_encoder_set_do_escape_coding(). | ||
850 | */ | ||
851 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_escape_coding(const FLAC__SeekableStreamEncoder *encoder); | ||
852 | |||
853 | /** Get the exhaustive model search flag. | ||
854 | * This is inherited from FLAC__StreamEncoder; see | ||
855 | * FLAC__stream_encoder_get_do_exhaustive_model_search(). | ||
856 | * | ||
857 | * \param encoder An encoder instance to query. | ||
858 | * \assert | ||
859 | * \code encoder != NULL \endcode | ||
860 | * \retval FLAC__bool | ||
861 | * See FLAC__seekable_stream_encoder_set_do_exhaustive_model_search(). | ||
862 | */ | ||
863 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_exhaustive_model_search(const FLAC__SeekableStreamEncoder *encoder); | ||
864 | |||
865 | /** Get the minimum residual partition order setting. | ||
866 | * This is inherited from FLAC__StreamEncoder; see | ||
867 | * FLAC__stream_encoder_get_min_residual_partition_order(). | ||
868 | * | ||
869 | * \param encoder An encoder instance to query. | ||
870 | * \assert | ||
871 | * \code encoder != NULL \endcode | ||
872 | * \retval unsigned | ||
873 | * See FLAC__seekable_stream_encoder_set_min_residual_partition_order(). | ||
874 | */ | ||
875 | FLAC_API unsigned FLAC__seekable_stream_encoder_get_min_residual_partition_order(const FLAC__SeekableStreamEncoder *encoder); | ||
876 | |||
877 | /** Get maximum residual partition order setting. | ||
878 | * This is inherited from FLAC__StreamEncoder; see | ||
879 | * FLAC__stream_encoder_get_max_residual_partition_order(). | ||
880 | * | ||
881 | * \param encoder An encoder instance to query. | ||
882 | * \assert | ||
883 | * \code encoder != NULL \endcode | ||
884 | * \retval unsigned | ||
885 | * See FLAC__seekable_stream_encoder_set_max_residual_partition_order(). | ||
886 | */ | ||
887 | FLAC_API unsigned FLAC__seekable_stream_encoder_get_max_residual_partition_order(const FLAC__SeekableStreamEncoder *encoder); | ||
888 | |||
889 | /** Get the Rice parameter search distance setting. | ||
890 | * This is inherited from FLAC__StreamEncoder; see | ||
891 | * FLAC__stream_encoder_get_rice_parameter_search_dist(). | ||
892 | * | ||
893 | * \param encoder An encoder instance to query. | ||
894 | * \assert | ||
895 | * \code encoder != NULL \endcode | ||
896 | * \retval unsigned | ||
897 | * See FLAC__seekable_stream_encoder_set_rice_parameter_search_dist(). | ||
898 | */ | ||
899 | FLAC_API unsigned FLAC__seekable_stream_encoder_get_rice_parameter_search_dist(const FLAC__SeekableStreamEncoder *encoder); | ||
900 | |||
901 | /** Get the previously set estimate of the total samples to be encoded. | ||
902 | * This is inherited from FLAC__StreamEncoder; see | ||
903 | * FLAC__stream_encoder_get_total_samples_estimate(). | ||
904 | * | ||
905 | * \param encoder An encoder instance to query. | ||
906 | * \assert | ||
907 | * \code encoder != NULL \endcode | ||
908 | * \retval FLAC__uint64 | ||
909 | * See FLAC__seekable_stream_encoder_set_total_samples_estimate(). | ||
910 | */ | ||
911 | FLAC_API FLAC__uint64 FLAC__seekable_stream_encoder_get_total_samples_estimate(const FLAC__SeekableStreamEncoder *encoder); | ||
912 | |||
913 | /** Initialize the encoder instance. | ||
914 | * Should be called after FLAC__seekable_stream_encoder_new() and | ||
915 | * FLAC__seekable_stream_encoder_set_*() but before FLAC__seekable_stream_encoder_process() | ||
916 | * or FLAC__seekable_stream_encoder_process_interleaved(). Will set and return | ||
917 | * the encoder state, which will be FLAC__SEEKABLE_STREAM_ENCODER_OK if | ||
918 | * initialization succeeded. | ||
919 | * | ||
920 | * The call to FLAC__seekable_stream_encoder_init() currently will also immediately | ||
921 | * call the write callback with the \c fLaC signature and all the encoded | ||
922 | * metadata. | ||
923 | * | ||
924 | * \param encoder An uninitialized encoder instance. | ||
925 | * \assert | ||
926 | * \code encoder != NULL \endcode | ||
927 | * \retval FLAC__SeekableStreamEncoderState | ||
928 | * \c FLAC__SEEKABLE_STREAM_ENCODER_OK if initialization was successful; see | ||
929 | * FLAC__SeekableStreamEncoderState for the meanings of other return values. | ||
930 | */ | ||
931 | FLAC_API FLAC__SeekableStreamEncoderState FLAC__seekable_stream_encoder_init(FLAC__SeekableStreamEncoder *encoder); | ||
932 | |||
933 | /** Finish the encoding process. | ||
934 | * Flushes the encoding buffer, releases resources, resets the encoder | ||
935 | * settings to their defaults, and returns the encoder state to | ||
936 | * FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED. | ||
937 | * | ||
938 | * In the event of a prematurely-terminated encode, it is not strictly | ||
939 | * necessary to call this immediately before FLAC__seekable_stream_encoder_delete() | ||
940 | * but it is good practice to match every FLAC__seekable_stream_encoder_init() | ||
941 | * with a FLAC__seekable_stream_encoder_finish(). | ||
942 | * | ||
943 | * \param encoder An uninitialized encoder instance. | ||
944 | * \assert | ||
945 | * \code encoder != NULL \endcode | ||
946 | */ | ||
947 | FLAC_API void FLAC__seekable_stream_encoder_finish(FLAC__SeekableStreamEncoder *encoder); | ||
948 | |||
949 | /** Submit data for encoding. | ||
950 | * This is inherited from FLAC__StreamEncoder; see | ||
951 | * FLAC__stream_encoder_process(). | ||
952 | * | ||
953 | * \param encoder An initialized encoder instance in the OK state. | ||
954 | * \param buffer An array of pointers to each channel's signal. | ||
955 | * \param samples The number of samples in one channel. | ||
956 | * \assert | ||
957 | * \code encoder != NULL \endcode | ||
958 | * \code FLAC__seekable_stream_encoder_get_state(encoder) == FLAC__SEEKABLE_STREAM_ENCODER_OK \endcode | ||
959 | * \retval FLAC__bool | ||
960 | * \c true if successful, else \c false; in this case, check the | ||
961 | * encoder state with FLAC__seekable_stream_encoder_get_state() to see what | ||
962 | * went wrong. | ||
963 | */ | ||
964 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_process(FLAC__SeekableStreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples); | ||
965 | |||
966 | /** Submit data for encoding. | ||
967 | * This is inherited from FLAC__StreamEncoder; see | ||
968 | * FLAC__stream_encoder_process_interleaved(). | ||
969 | * | ||
970 | * \param encoder An initialized encoder instance in the OK state. | ||
971 | * \param buffer An array of channel-interleaved data (see above). | ||
972 | * \param samples The number of samples in one channel, the same as for | ||
973 | * FLAC__seekable_stream_encoder_process(). For example, if | ||
974 | * encoding two channels, \c 1000 \a samples corresponds | ||
975 | * to a \a buffer of 2000 values. | ||
976 | * \assert | ||
977 | * \code encoder != NULL \endcode | ||
978 | * \code FLAC__seekable_stream_encoder_get_state(encoder) == FLAC__SEEKABLE_STREAM_ENCODER_OK \endcode | ||
979 | * \retval FLAC__bool | ||
980 | * \c true if successful, else \c false; in this case, check the | ||
981 | * encoder state with FLAC__seekable_stream_encoder_get_state() to see what | ||
982 | * went wrong. | ||
983 | */ | ||
984 | FLAC_API FLAC__bool FLAC__seekable_stream_encoder_process_interleaved(FLAC__SeekableStreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples); | ||
985 | |||
986 | /* \} */ | ||
987 | |||
988 | #ifdef __cplusplus | ||
989 | } | ||
990 | #endif | ||
991 | |||
992 | #endif | ||
diff --git a/apps/codecs/libFLAC/include/FLAC/stream_decoder.h b/apps/codecs/libFLAC/include/FLAC/stream_decoder.h new file mode 100644 index 0000000000..6cd59d42a9 --- /dev/null +++ b/apps/codecs/libFLAC/include/FLAC/stream_decoder.h | |||
@@ -0,0 +1,873 @@ | |||
1 | /* libFLAC - Free Lossless Audio Codec library | ||
2 | * Copyright (C) 2000,2001,2002,2003,2004,2005 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__STREAM_DECODER_H | ||
33 | #define FLAC__STREAM_DECODER_H | ||
34 | |||
35 | #include "export.h" | ||
36 | #include "format.h" | ||
37 | |||
38 | #ifdef __cplusplus | ||
39 | extern "C" { | ||
40 | #endif | ||
41 | |||
42 | |||
43 | /** \file include/FLAC/stream_decoder.h | ||
44 | * | ||
45 | * \brief | ||
46 | * This module contains the functions which implement the stream | ||
47 | * decoder. | ||
48 | * | ||
49 | * See the detailed documentation in the | ||
50 | * \link flac_stream_decoder stream decoder \endlink module. | ||
51 | */ | ||
52 | |||
53 | /** \defgroup flac_decoder FLAC/ *_decoder.h: decoder interfaces | ||
54 | * \ingroup flac | ||
55 | * | ||
56 | * \brief | ||
57 | * This module describes the three decoder layers provided by libFLAC. | ||
58 | * | ||
59 | * For decoding FLAC streams, libFLAC provides three layers of access. The | ||
60 | * lowest layer is non-seekable stream-level decoding, the next is seekable | ||
61 | * stream-level decoding, and the highest layer is file-level decoding. The | ||
62 | * interfaces are described in the \link flac_stream_decoder stream decoder | ||
63 | * \endlink, \link flac_seekable_stream_decoder seekable stream decoder | ||
64 | * \endlink, and \link flac_file_decoder file decoder \endlink modules | ||
65 | * respectively. Typically you will choose the highest layer that your input | ||
66 | * source will support. | ||
67 | * | ||
68 | * The stream decoder relies on callbacks for all input and output and has no | ||
69 | * provisions for seeking. The seekable stream decoder wraps the stream | ||
70 | * decoder and exposes functions for seeking. However, you must provide | ||
71 | * extra callbacks for seek-related operations on your stream, like seek and | ||
72 | * tell. The file decoder wraps the seekable stream decoder and supplies | ||
73 | * most of the callbacks internally, simplifying the processing of standard | ||
74 | * files. | ||
75 | */ | ||
76 | |||
77 | /** \defgroup flac_stream_decoder FLAC/stream_decoder.h: stream decoder interface | ||
78 | * \ingroup flac_decoder | ||
79 | * | ||
80 | * \brief | ||
81 | * This module contains the functions which implement the stream | ||
82 | * decoder. | ||
83 | * | ||
84 | * The basic usage of this decoder is as follows: | ||
85 | * - The program creates an instance of a decoder using | ||
86 | * FLAC__stream_decoder_new(). | ||
87 | * - The program overrides the default settings and sets callbacks for | ||
88 | * reading, writing, error reporting, and metadata reporting using | ||
89 | * FLAC__stream_decoder_set_*() functions. | ||
90 | * - The program initializes the instance to validate the settings and | ||
91 | * prepare for decoding using FLAC__stream_decoder_init(). | ||
92 | * - The program calls the FLAC__stream_decoder_process_*() functions | ||
93 | * to decode data, which subsequently calls the callbacks. | ||
94 | * - The program finishes the decoding with FLAC__stream_decoder_finish(), | ||
95 | * which flushes the input and output and resets the decoder to the | ||
96 | * uninitialized state. | ||
97 | * - The instance may be used again or deleted with | ||
98 | * FLAC__stream_decoder_delete(). | ||
99 | * | ||
100 | * In more detail, the program will create a new instance by calling | ||
101 | * FLAC__stream_decoder_new(), then call FLAC__stream_decoder_set_*() | ||
102 | * functions to set the callbacks and client data, and call | ||
103 | * FLAC__stream_decoder_init(). The required callbacks are: | ||
104 | * | ||
105 | * - Read callback - This function will be called when the decoder needs | ||
106 | * more input data. The address of the buffer to be filled is supplied, | ||
107 | * along with the number of bytes the buffer can hold. The callback may | ||
108 | * choose to supply less data and modify the byte count but must be careful | ||
109 | * not to overflow the buffer. The callback then returns a status code | ||
110 | * chosen from FLAC__StreamDecoderReadStatus. | ||
111 | * - Write callback - This function will be called when the decoder has | ||
112 | * decoded a single frame of data. The decoder will pass the frame | ||
113 | * metadata as well as an array of pointers (one for each channel) | ||
114 | * pointing to the decoded audio. | ||
115 | * - Metadata callback - This function will be called when the decoder has | ||
116 | * decoded a metadata block. In a valid FLAC file there will always be | ||
117 | * one STREAMINFO block, followed by zero or more other metadata | ||
118 | * blocks. These will be supplied by the decoder in the same order as | ||
119 | * they appear in the stream and always before the first audio frame | ||
120 | * (i.e. write callback). The metadata block that is passed in must not | ||
121 | * be modified, and it doesn't live beyond the callback, so you should | ||
122 | * make a copy of it with FLAC__metadata_object_clone() if you will need | ||
123 | * it elsewhere. Since metadata blocks can potentially be large, by | ||
124 | * default the decoder only calls the metadata callback for the STREAMINFO | ||
125 | * block; you can instruct the decoder to pass or filter other blocks with | ||
126 | * FLAC__stream_decoder_set_metadata_*() calls. | ||
127 | * - Error callback - This function will be called whenever an error occurs | ||
128 | * during decoding. | ||
129 | * | ||
130 | * Once the decoder is initialized, your program will call one of several | ||
131 | * functions to start the decoding process: | ||
132 | * | ||
133 | * - FLAC__stream_decoder_process_single() - Tells the decoder to process at | ||
134 | * most one metadata block or audio frame and return, calling either the | ||
135 | * metadata callback or write callback, respectively, once. If the decoder | ||
136 | * loses sync it will return with only the error callback being called. | ||
137 | * - FLAC__stream_decoder_process_until_end_of_metadata() - Tells the decoder | ||
138 | * to process the stream from the current location and stop upon reaching | ||
139 | * the first audio frame. The user will get one metadata, write, or error | ||
140 | * callback per metadata block, audio frame, or sync error, respectively. | ||
141 | * - FLAC__stream_decoder_process_until_end_of_stream() - Tells the decoder | ||
142 | * to process the stream from the current location until the read callback | ||
143 | * returns FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM or | ||
144 | * FLAC__STREAM_DECODER_READ_STATUS_ABORT. The user will get one metadata, | ||
145 | * write, or error callback per metadata block, audio frame, or sync error, | ||
146 | * respectively. | ||
147 | * | ||
148 | * When the decoder has finished decoding (normally or through an abort), | ||
149 | * the instance is finished by calling FLAC__stream_decoder_finish(), which | ||
150 | * ensures the decoder is in the correct state and frees memory. Then the | ||
151 | * instance may be deleted with FLAC__stream_decoder_delete() or initialized | ||
152 | * again to decode another stream. | ||
153 | * | ||
154 | * Note that the stream decoder has no real concept of stream position, it | ||
155 | * just converts data. To seek within a stream the callbacks have only to | ||
156 | * flush the decoder using FLAC__stream_decoder_flush() and start feeding | ||
157 | * data from the new position through the read callback. The seekable | ||
158 | * stream decoder does just this. | ||
159 | * | ||
160 | * The FLAC__stream_decoder_set_metadata_*() functions deserve special | ||
161 | * attention. By default, the decoder only calls the metadata_callback for | ||
162 | * the STREAMINFO block. These functions allow you to tell the decoder | ||
163 | * explicitly which blocks to parse and return via the metadata_callback | ||
164 | * and/or which to skip. Use a FLAC__stream_decoder_set_metadata_respond_all(), | ||
165 | * FLAC__stream_decoder_set_metadata_ignore() ... or FLAC__stream_decoder_set_metadata_ignore_all(), | ||
166 | * FLAC__stream_decoder_set_metadata_respond() ... sequence to exactly specify which | ||
167 | * blocks to return. Remember that some metadata blocks can be big so | ||
168 | * filtering out the ones you don't use can reduce the memory requirements | ||
169 | * of the decoder. Also note the special forms | ||
170 | * FLAC__stream_decoder_set_metadata_respond_application(id) and | ||
171 | * FLAC__stream_decoder_set_metadata_ignore_application(id) for filtering APPLICATION | ||
172 | * blocks based on the application ID. | ||
173 | * | ||
174 | * STREAMINFO and SEEKTABLE blocks are always parsed and used internally, but | ||
175 | * they still can legally be filtered from the metadata_callback. | ||
176 | * | ||
177 | * \note | ||
178 | * The "set" functions may only be called when the decoder is in the | ||
179 | * state FLAC__STREAM_DECODER_UNINITIALIZED, i.e. after | ||
180 | * FLAC__stream_decoder_new() or FLAC__stream_decoder_finish(), but | ||
181 | * before FLAC__stream_decoder_init(). If this is the case they will | ||
182 | * return \c true, otherwise \c false. | ||
183 | * | ||
184 | * \note | ||
185 | * FLAC__stream_decoder_finish() resets all settings to the constructor | ||
186 | * defaults, including the callbacks. | ||
187 | * | ||
188 | * \{ | ||
189 | */ | ||
190 | |||
191 | |||
192 | /** State values for a FLAC__StreamDecoder | ||
193 | * | ||
194 | * The decoder's state can be obtained by calling FLAC__stream_decoder_get_state(). | ||
195 | */ | ||
196 | typedef enum { | ||
197 | |||
198 | FLAC__STREAM_DECODER_SEARCH_FOR_METADATA = 0, | ||
199 | /**< The decoder is ready to search for metadata. */ | ||
200 | |||
201 | FLAC__STREAM_DECODER_READ_METADATA, | ||
202 | /**< The decoder is ready to or is in the process of reading metadata. */ | ||
203 | |||
204 | FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC, | ||
205 | /**< The decoder is ready to or is in the process of searching for the frame sync code. */ | ||
206 | |||
207 | FLAC__STREAM_DECODER_READ_FRAME, | ||
208 | /**< The decoder is ready to or is in the process of reading a frame. */ | ||
209 | |||
210 | FLAC__STREAM_DECODER_END_OF_STREAM, | ||
211 | /**< The decoder has reached the end of the stream. */ | ||
212 | |||
213 | FLAC__STREAM_DECODER_ABORTED, | ||
214 | /**< The decoder was aborted by the read callback. */ | ||
215 | |||
216 | FLAC__STREAM_DECODER_UNPARSEABLE_STREAM, | ||
217 | /**< The decoder encountered reserved fields in use in the stream. */ | ||
218 | |||
219 | FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR, | ||
220 | /**< An error occurred allocating memory. */ | ||
221 | |||
222 | FLAC__STREAM_DECODER_ALREADY_INITIALIZED, | ||
223 | /**< FLAC__stream_decoder_init() was called when the decoder was | ||
224 | * already initialized, usually because | ||
225 | * FLAC__stream_decoder_finish() was not called. | ||
226 | */ | ||
227 | |||
228 | FLAC__STREAM_DECODER_INVALID_CALLBACK, | ||
229 | /**< FLAC__stream_decoder_init() was called without all callbacks being set. */ | ||
230 | |||
231 | FLAC__STREAM_DECODER_UNINITIALIZED | ||
232 | /**< The decoder is in the uninitialized state. */ | ||
233 | |||
234 | } FLAC__StreamDecoderState; | ||
235 | |||
236 | /** Maps a FLAC__StreamDecoderState to a C string. | ||
237 | * | ||
238 | * Using a FLAC__StreamDecoderState as the index to this array | ||
239 | * will give the string equivalent. The contents should not be modified. | ||
240 | */ | ||
241 | extern FLAC_API const char * const FLAC__StreamDecoderStateString[]; | ||
242 | |||
243 | |||
244 | /** Return values for the FLAC__StreamDecoder read callback. | ||
245 | */ | ||
246 | typedef enum { | ||
247 | |||
248 | FLAC__STREAM_DECODER_READ_STATUS_CONTINUE, | ||
249 | /**< The read was OK and decoding can continue. */ | ||
250 | |||
251 | FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM, | ||
252 | /**< The read was attempted at the end of the stream. */ | ||
253 | |||
254 | FLAC__STREAM_DECODER_READ_STATUS_ABORT | ||
255 | /**< An unrecoverable error occurred. The decoder will return from the process call. */ | ||
256 | |||
257 | } FLAC__StreamDecoderReadStatus; | ||
258 | |||
259 | /** Maps a FLAC__StreamDecoderReadStatus to a C string. | ||
260 | * | ||
261 | * Using a FLAC__StreamDecoderReadStatus as the index to this array | ||
262 | * will give the string equivalent. The contents should not be modified. | ||
263 | */ | ||
264 | extern FLAC_API const char * const FLAC__StreamDecoderReadStatusString[]; | ||
265 | |||
266 | |||
267 | /** Return values for the FLAC__StreamDecoder write callback. | ||
268 | */ | ||
269 | typedef enum { | ||
270 | |||
271 | FLAC__STREAM_DECODER_WRITE_STATUS_CONTINUE, | ||
272 | /**< The write was OK and decoding can continue. */ | ||
273 | |||
274 | FLAC__STREAM_DECODER_WRITE_STATUS_ABORT | ||
275 | /**< An unrecoverable error occurred. The decoder will return from the process call. */ | ||
276 | |||
277 | } FLAC__StreamDecoderWriteStatus; | ||
278 | |||
279 | /** Maps a FLAC__StreamDecoderWriteStatus to a C string. | ||
280 | * | ||
281 | * Using a FLAC__StreamDecoderWriteStatus as the index to this array | ||
282 | * will give the string equivalent. The contents should not be modified. | ||
283 | */ | ||
284 | extern FLAC_API const char * const FLAC__StreamDecoderWriteStatusString[]; | ||
285 | |||
286 | |||
287 | /** Possible values passed in to the FLAC__StreamDecoder error callback. | ||
288 | */ | ||
289 | typedef enum { | ||
290 | |||
291 | FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC, | ||
292 | /**< An error in the stream caused the decoder to lose synchronization. */ | ||
293 | |||
294 | FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER, | ||
295 | /**< The decoder encountered a corrupted frame header. */ | ||
296 | |||
297 | FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH | ||
298 | /**< The frame's data did not match the CRC in the footer. */ | ||
299 | |||
300 | } FLAC__StreamDecoderErrorStatus; | ||
301 | |||
302 | /** Maps a FLAC__StreamDecoderErrorStatus to a C string. | ||
303 | * | ||
304 | * Using a FLAC__StreamDecoderErrorStatus as the index to this array | ||
305 | * will give the string equivalent. The contents should not be modified. | ||
306 | */ | ||
307 | extern FLAC_API const char * const FLAC__StreamDecoderErrorStatusString[]; | ||
308 | |||
309 | |||
310 | /*********************************************************************** | ||
311 | * | ||
312 | * class FLAC__StreamDecoder | ||
313 | * | ||
314 | ***********************************************************************/ | ||
315 | |||
316 | struct FLAC__StreamDecoderProtected; | ||
317 | struct FLAC__StreamDecoderPrivate; | ||
318 | /** The opaque structure definition for the stream decoder type. | ||
319 | * See the \link flac_stream_decoder stream decoder module \endlink | ||
320 | * for a detailed description. | ||
321 | */ | ||
322 | typedef struct { | ||
323 | struct FLAC__StreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */ | ||
324 | struct FLAC__StreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */ | ||
325 | } FLAC__StreamDecoder; | ||
326 | |||
327 | /** Signature for the read callback. | ||
328 | * See FLAC__stream_decoder_set_read_callback() for more info. | ||
329 | * | ||
330 | * \param decoder The decoder instance calling the callback. | ||
331 | * \param buffer A pointer to a location for the callee to store | ||
332 | * data to be decoded. | ||
333 | * \param bytes A pointer to the size of the buffer. On entry | ||
334 | * to the callback, it contains the maximum number | ||
335 | * of bytes that may be stored in \a buffer. The | ||
336 | * callee must set it to the actual number of bytes | ||
337 | * stored (0 in case of error or end-of-stream) before | ||
338 | * returning. | ||
339 | * \param client_data The callee's client data set through | ||
340 | * FLAC__stream_decoder_set_client_data(). | ||
341 | * \retval FLAC__StreamDecoderReadStatus | ||
342 | * The callee's return status. | ||
343 | */ | ||
344 | typedef FLAC__StreamDecoderReadStatus (*FLAC__StreamDecoderReadCallback)(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data); | ||
345 | |||
346 | /** Signature for the write callback. | ||
347 | * See FLAC__stream_decoder_set_write_callback() for more info. | ||
348 | * | ||
349 | * \param decoder The decoder instance calling the callback. | ||
350 | * \param frame The description of the decoded frame. See | ||
351 | * FLAC__Frame. | ||
352 | * \param buffer An array of pointers to decoded channels of data. | ||
353 | * Each pointer will point to an array of signed | ||
354 | * samples of length \a frame->header.blocksize. | ||
355 | * Currently, the channel order has no meaning | ||
356 | * except for stereo streams; in this case channel | ||
357 | * 0 is left and 1 is right. | ||
358 | * \param client_data The callee's client data set through | ||
359 | * FLAC__stream_decoder_set_client_data(). | ||
360 | * \retval FLAC__StreamDecoderWriteStatus | ||
361 | * The callee's return status. | ||
362 | */ | ||
363 | typedef FLAC__StreamDecoderWriteStatus (*FLAC__StreamDecoderWriteCallback)(const FLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data); | ||
364 | |||
365 | /** Signature for the metadata callback. | ||
366 | * See FLAC__stream_decoder_set_metadata_callback() for more info. | ||
367 | * | ||
368 | * \param decoder The decoder instance calling the callback. | ||
369 | * \param metadata The decoded metadata block. | ||
370 | * \param client_data The callee's client data set through | ||
371 | * FLAC__stream_decoder_set_client_data(). | ||
372 | */ | ||
373 | typedef void (*FLAC__StreamDecoderMetadataCallback)(const FLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data); | ||
374 | |||
375 | /** Signature for the error callback. | ||
376 | * See FLAC__stream_decoder_set_error_callback() for more info. | ||
377 | * | ||
378 | * \param decoder The decoder instance calling the callback. | ||
379 | * \param status The error encountered by the decoder. | ||
380 | * \param client_data The callee's client data set through | ||
381 | * FLAC__stream_decoder_set_client_data(). | ||
382 | */ | ||
383 | typedef void (*FLAC__StreamDecoderErrorCallback)(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data); | ||
384 | |||
385 | |||
386 | /*********************************************************************** | ||
387 | * | ||
388 | * Class constructor/destructor | ||
389 | * | ||
390 | ***********************************************************************/ | ||
391 | |||
392 | /** Create a new stream decoder instance. The instance is created with | ||
393 | * default settings; see the individual FLAC__stream_decoder_set_*() | ||
394 | * functions for each setting's default. | ||
395 | * | ||
396 | * \retval FLAC__StreamDecoder* | ||
397 | * \c NULL if there was an error allocating memory, else the new instance. | ||
398 | */ | ||
399 | FLAC_API FLAC__StreamDecoder *FLAC__stream_decoder_new(); | ||
400 | |||
401 | /** Free a decoder instance. Deletes the object pointed to by \a decoder. | ||
402 | * | ||
403 | * \param decoder A pointer to an existing decoder. | ||
404 | * \assert | ||
405 | * \code decoder != NULL \endcode | ||
406 | */ | ||
407 | FLAC_API void FLAC__stream_decoder_delete(FLAC__StreamDecoder *decoder); | ||
408 | |||
409 | |||
410 | /*********************************************************************** | ||
411 | * | ||
412 | * Public class method prototypes | ||
413 | * | ||
414 | ***********************************************************************/ | ||
415 | |||
416 | /** Set the read callback. | ||
417 | * The supplied function will be called when the decoder needs more input | ||
418 | * data. The address of the buffer to be filled is supplied, along with | ||
419 | * the number of bytes the buffer can hold. The callback may choose to | ||
420 | * supply less data and modify the byte count but must be careful not to | ||
421 | * overflow the buffer. The callback then returns a status code chosen | ||
422 | * from FLAC__StreamDecoderReadStatus. | ||
423 | * | ||
424 | * \note | ||
425 | * The callback is mandatory and must be set before initialization. | ||
426 | * | ||
427 | * \default \c NULL | ||
428 | * \param decoder A decoder instance to set. | ||
429 | * \param value See above. | ||
430 | * \assert | ||
431 | * \code decoder != NULL \endcode | ||
432 | * \code value != NULL \endcode | ||
433 | * \retval FLAC__bool | ||
434 | * \c false if the decoder is already initialized, else \c true. | ||
435 | */ | ||
436 | FLAC_API FLAC__bool FLAC__stream_decoder_set_read_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderReadCallback value); | ||
437 | |||
438 | /** Set the write callback. | ||
439 | * The supplied function will be called when the decoder has decoded a | ||
440 | * single frame of data. The decoder will pass the frame metadata as | ||
441 | * well as an array of pointers (one for each channel) pointing to the | ||
442 | * decoded audio. | ||
443 | * | ||
444 | * \note | ||
445 | * The callback is mandatory and must be set before initialization. | ||
446 | * | ||
447 | * \default \c NULL | ||
448 | * \param decoder A decoder instance to set. | ||
449 | * \param value See above. | ||
450 | * \assert | ||
451 | * \code decoder != NULL \endcode | ||
452 | * \code value != NULL \endcode | ||
453 | * \retval FLAC__bool | ||
454 | * \c false if the decoder is already initialized, else \c true. | ||
455 | */ | ||
456 | FLAC_API FLAC__bool FLAC__stream_decoder_set_write_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderWriteCallback value); | ||
457 | |||
458 | /** Set the metadata callback. | ||
459 | * The supplied function will be called when the decoder has decoded a metadata | ||
460 | * block. In a valid FLAC file there will always be one STREAMINFO block, | ||
461 | * followed by zero or more other metadata blocks. These will be supplied | ||
462 | * by the decoder in the same order as they appear in the stream and always | ||
463 | * before the first audio frame (i.e. write callback). The metadata block | ||
464 | * that is passed in must not be modified, and it doesn't live beyond the | ||
465 | * callback, so you should make a copy of it with | ||
466 | * FLAC__metadata_object_clone() if you will need it elsewhere. Since | ||
467 | * metadata blocks can potentially be large, by default the decoder only | ||
468 | * calls the metadata callback for the STREAMINFO block; you can instruct | ||
469 | * the decoder to pass or filter other blocks with | ||
470 | * FLAC__stream_decoder_set_metadata_*() calls. | ||
471 | * | ||
472 | * \note | ||
473 | * The callback is mandatory and must be set before initialization. | ||
474 | * | ||
475 | * \default \c NULL | ||
476 | * \param decoder A decoder instance to set. | ||
477 | * \param value See above. | ||
478 | * \assert | ||
479 | * \code decoder != NULL \endcode | ||
480 | * \code value != NULL \endcode | ||
481 | * \retval FLAC__bool | ||
482 | * \c false if the decoder is already initialized, else \c true. | ||
483 | */ | ||
484 | FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderMetadataCallback value); | ||
485 | |||
486 | /** Set the error callback. | ||
487 | * The supplied function will be called whenever an error occurs during | ||
488 | * decoding. | ||
489 | * | ||
490 | * \note | ||
491 | * The callback is mandatory and must be set before initialization. | ||
492 | * | ||
493 | * \default \c NULL | ||
494 | * \param decoder A decoder instance to set. | ||
495 | * \param value See above. | ||
496 | * \assert | ||
497 | * \code decoder != NULL \endcode | ||
498 | * \code value != NULL \endcode | ||
499 | * \retval FLAC__bool | ||
500 | * \c false if the decoder is already initialized, else \c true. | ||
501 | */ | ||
502 | FLAC_API FLAC__bool FLAC__stream_decoder_set_error_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorCallback value); | ||
503 | |||
504 | /** Set the client data to be passed back to callbacks. | ||
505 | * This value will be supplied to callbacks in their \a client_data | ||
506 | * argument. | ||
507 | * | ||
508 | * \default \c NULL | ||
509 | * \param decoder A decoder instance to set. | ||
510 | * \param value See above. | ||
511 | * \assert | ||
512 | * \code decoder != NULL \endcode | ||
513 | * \retval FLAC__bool | ||
514 | * \c false if the decoder is already initialized, else \c true. | ||
515 | */ | ||
516 | FLAC_API FLAC__bool FLAC__stream_decoder_set_client_data(FLAC__StreamDecoder *decoder, void *value); | ||
517 | |||
518 | /** Direct the decoder to pass on all metadata blocks of type \a type. | ||
519 | * | ||
520 | * \default By default, only the \c STREAMINFO block is returned via the | ||
521 | * metadata callback. | ||
522 | * \param decoder A decoder instance to set. | ||
523 | * \param type See above. | ||
524 | * \assert | ||
525 | * \code decoder != NULL \endcode | ||
526 | * \a type is valid | ||
527 | * \retval FLAC__bool | ||
528 | * \c false if the decoder is already initialized, else \c true. | ||
529 | */ | ||
530 | FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond(FLAC__StreamDecoder *decoder, FLAC__MetadataType type); | ||
531 | |||
532 | /** Direct the decoder to pass on all APPLICATION metadata blocks of the | ||
533 | * given \a id. | ||
534 | * | ||
535 | * \default By default, only the \c STREAMINFO block is returned via the | ||
536 | * metadata callback. | ||
537 | * \param decoder A decoder instance to set. | ||
538 | * \param id See above. | ||
539 | * \assert | ||
540 | * \code decoder != NULL \endcode | ||
541 | * \code id != NULL \endcode | ||
542 | * \retval FLAC__bool | ||
543 | * \c false if the decoder is already initialized, else \c true. | ||
544 | */ | ||
545 | FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]); | ||
546 | |||
547 | /** Direct the decoder to pass on all metadata blocks of any type. | ||
548 | * | ||
549 | * \default By default, only the \c STREAMINFO block is returned via the | ||
550 | * metadata callback. | ||
551 | * \param decoder A decoder instance to set. | ||
552 | * \assert | ||
553 | * \code decoder != NULL \endcode | ||
554 | * \retval FLAC__bool | ||
555 | * \c false if the decoder is already initialized, else \c true. | ||
556 | */ | ||
557 | FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_all(FLAC__StreamDecoder *decoder); | ||
558 | |||
559 | /** Direct the decoder to filter out all metadata blocks of type \a type. | ||
560 | * | ||
561 | * \default By default, only the \c STREAMINFO block is returned via the | ||
562 | * metadata callback. | ||
563 | * \param decoder A decoder instance to set. | ||
564 | * \param type See above. | ||
565 | * \assert | ||
566 | * \code decoder != NULL \endcode | ||
567 | * \a type is valid | ||
568 | * \retval FLAC__bool | ||
569 | * \c false if the decoder is already initialized, else \c true. | ||
570 | */ | ||
571 | FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore(FLAC__StreamDecoder *decoder, FLAC__MetadataType type); | ||
572 | |||
573 | /** Direct the decoder to filter out all APPLICATION metadata blocks of | ||
574 | * the given \a id. | ||
575 | * | ||
576 | * \default By default, only the \c STREAMINFO block is returned via the | ||
577 | * metadata callback. | ||
578 | * \param decoder A decoder instance to set. | ||
579 | * \param id See above. | ||
580 | * \assert | ||
581 | * \code decoder != NULL \endcode | ||
582 | * \code id != NULL \endcode | ||
583 | * \retval FLAC__bool | ||
584 | * \c false if the decoder is already initialized, else \c true. | ||
585 | */ | ||
586 | FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]); | ||
587 | |||
588 | /** Direct the decoder to filter out all metadata blocks of any type. | ||
589 | * | ||
590 | * \default By default, only the \c STREAMINFO block is returned via the | ||
591 | * metadata callback. | ||
592 | * \param decoder A decoder instance to set. | ||
593 | * \assert | ||
594 | * \code decoder != NULL \endcode | ||
595 | * \retval FLAC__bool | ||
596 | * \c false if the decoder is already initialized, else \c true. | ||
597 | */ | ||
598 | FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_all(FLAC__StreamDecoder *decoder); | ||
599 | |||
600 | /** Get the current decoder state. | ||
601 | * | ||
602 | * \param decoder A decoder instance to query. | ||
603 | * \assert | ||
604 | * \code decoder != NULL \endcode | ||
605 | * \retval FLAC__StreamDecoderState | ||
606 | * The current decoder state. | ||
607 | */ | ||
608 | FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_get_state(const FLAC__StreamDecoder *decoder); | ||
609 | |||
610 | /** Get the current decoder state as a C string. | ||
611 | * | ||
612 | * \param decoder A decoder instance to query. | ||
613 | * \assert | ||
614 | * \code decoder != NULL \endcode | ||
615 | * \retval const char * | ||
616 | * The decoder state as a C string. Do not modify the contents. | ||
617 | */ | ||
618 | FLAC_API const char *FLAC__stream_decoder_get_resolved_state_string(const FLAC__StreamDecoder *decoder); | ||
619 | |||
620 | /** Get the current number of channels in the stream being decoded. | ||
621 | * Will only be valid after decoding has started and will contain the | ||
622 | * value from the most recently decoded frame header. | ||
623 | * | ||
624 | * \param decoder A decoder instance to query. | ||
625 | * \assert | ||
626 | * \code decoder != NULL \endcode | ||
627 | * \retval unsigned | ||
628 | * See above. | ||
629 | */ | ||
630 | FLAC_API unsigned FLAC__stream_decoder_get_channels(const FLAC__StreamDecoder *decoder); | ||
631 | |||
632 | /** Get the current channel assignment in the stream being decoded. | ||
633 | * Will only be valid after decoding has started and will contain the | ||
634 | * value from the most recently decoded frame header. | ||
635 | * | ||
636 | * \param decoder A decoder instance to query. | ||
637 | * \assert | ||
638 | * \code decoder != NULL \endcode | ||
639 | * \retval FLAC__ChannelAssignment | ||
640 | * See above. | ||
641 | */ | ||
642 | FLAC_API FLAC__ChannelAssignment FLAC__stream_decoder_get_channel_assignment(const FLAC__StreamDecoder *decoder); | ||
643 | |||
644 | /** Get the current sample resolution in the stream being decoded. | ||
645 | * Will only be valid after decoding has started and will contain the | ||
646 | * value from the most recently decoded frame header. | ||
647 | * | ||
648 | * \param decoder A decoder instance to query. | ||
649 | * \assert | ||
650 | * \code decoder != NULL \endcode | ||
651 | * \retval unsigned | ||
652 | * See above. | ||
653 | */ | ||
654 | FLAC_API unsigned FLAC__stream_decoder_get_bits_per_sample(const FLAC__StreamDecoder *decoder); | ||
655 | |||
656 | /** Get the current sample rate in Hz of the stream being decoded. | ||
657 | * Will only be valid after decoding has started and will contain the | ||
658 | * value from the most recently decoded frame header. | ||
659 | * | ||
660 | * \param decoder A decoder instance to query. | ||
661 | * \assert | ||
662 | * \code decoder != NULL \endcode | ||
663 | * \retval unsigned | ||
664 | * See above. | ||
665 | */ | ||
666 | FLAC_API unsigned FLAC__stream_decoder_get_sample_rate(const FLAC__StreamDecoder *decoder); | ||
667 | |||
668 | /** Get the current blocksize of the stream being decoded. | ||
669 | * Will only be valid after decoding has started and will contain the | ||
670 | * value from the most recently decoded frame header. | ||
671 | * | ||
672 | * \param decoder A decoder instance to query. | ||
673 | * \assert | ||
674 | * \code decoder != NULL \endcode | ||
675 | * \retval unsigned | ||
676 | * See above. | ||
677 | */ | ||
678 | FLAC_API unsigned FLAC__stream_decoder_get_blocksize(const FLAC__StreamDecoder *decoder); | ||
679 | |||
680 | /** Initialize the decoder instance. | ||
681 | * Should be called after FLAC__stream_decoder_new() and | ||
682 | * FLAC__stream_decoder_set_*() but before any of the | ||
683 | * FLAC__stream_decoder_process_*() functions. Will set and return the | ||
684 | * decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA | ||
685 | * if initialization succeeded. | ||
686 | * | ||
687 | * \param decoder An uninitialized decoder instance. | ||
688 | * \assert | ||
689 | * \code decoder != NULL \endcode | ||
690 | * \retval FLAC__StreamDecoderState | ||
691 | * \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA if initialization was | ||
692 | * successful; see FLAC__StreamDecoderState for the meanings of other | ||
693 | * return values. | ||
694 | */ | ||
695 | FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_init(FLAC__StreamDecoder *decoder); | ||
696 | |||
697 | /** Finish the decoding process. | ||
698 | * Flushes the decoding buffer, releases resources, resets the decoder | ||
699 | * settings to their defaults, and returns the decoder state to | ||
700 | * FLAC__STREAM_DECODER_UNINITIALIZED. | ||
701 | * | ||
702 | * In the event of a prematurely-terminated decode, it is not strictly | ||
703 | * necessary to call this immediately before FLAC__stream_decoder_delete() | ||
704 | * but it is good practice to match every FLAC__stream_decoder_init() | ||
705 | * with a FLAC__stream_decoder_finish(). | ||
706 | * | ||
707 | * \param decoder An uninitialized decoder instance. | ||
708 | * \assert | ||
709 | * \code decoder != NULL \endcode | ||
710 | */ | ||
711 | FLAC_API void FLAC__stream_decoder_finish(FLAC__StreamDecoder *decoder); | ||
712 | |||
713 | /** Flush the stream input. | ||
714 | * The decoder's input buffer will be cleared and the state set to | ||
715 | * \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC. | ||
716 | * | ||
717 | * \param decoder A decoder instance. | ||
718 | * \assert | ||
719 | * \code decoder != NULL \endcode | ||
720 | * \retval FLAC__bool | ||
721 | * \c true if successful, else \c false if a memory allocation | ||
722 | * error occurs. | ||
723 | */ | ||
724 | FLAC_API FLAC__bool FLAC__stream_decoder_flush(FLAC__StreamDecoder *decoder); | ||
725 | |||
726 | /** Reset the decoding process. | ||
727 | * The decoder's input buffer will be cleared and the state set to | ||
728 | * \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA. This is similar to | ||
729 | * FLAC__stream_decoder_finish() except that the settings are | ||
730 | * preserved; there is no need to call FLAC__stream_decoder_init() | ||
731 | * before decoding again. | ||
732 | * | ||
733 | * \param decoder A decoder instance. | ||
734 | * \assert | ||
735 | * \code decoder != NULL \endcode | ||
736 | * \retval FLAC__bool | ||
737 | * \c true if successful, else \c false if a memory allocation | ||
738 | * error occurs. | ||
739 | */ | ||
740 | FLAC_API FLAC__bool FLAC__stream_decoder_reset(FLAC__StreamDecoder *decoder); | ||
741 | |||
742 | /** Decode one metadata block or audio frame. | ||
743 | * This version instructs the decoder to decode a either a single metadata | ||
744 | * block or a single frame and stop, unless the callbacks return a fatal | ||
745 | * error or the read callback returns | ||
746 | * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM. | ||
747 | * | ||
748 | * As the decoder needs more input it will call the read callback. | ||
749 | * Depending on what was decoded, the metadata or write callback will be | ||
750 | * called with the decoded metadata block or audio frame, unless an error | ||
751 | * occurred. If the decoder loses sync it will call the error callback | ||
752 | * instead. | ||
753 | * | ||
754 | * Unless there is a fatal read error or end of stream, this function | ||
755 | * will return once one whole frame is decoded. In other words, if the | ||
756 | * stream is not synchronized or points to a corrupt frame header, the | ||
757 | * decoder will continue to try and resync until it gets to a valid | ||
758 | * frame, then decode one frame, then return. If the decoder points to | ||
759 | * frame whose frame CRC in the frame footer does not match the | ||
760 | * computed frame CRC, this function will issue a | ||
761 | * FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH error to the | ||
762 | * error callback, and return, having decoded one complete, although | ||
763 | * corrupt, frame. (Such corrupted frames are sent as silence of the | ||
764 | * correct length to the write callback.) | ||
765 | * | ||
766 | * \param decoder An initialized decoder instance. | ||
767 | * \assert | ||
768 | * \code decoder != NULL \endcode | ||
769 | * \retval FLAC__bool | ||
770 | * \c false if any read or write error occurred (except | ||
771 | * \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true; | ||
772 | * in any case, check the decoder state with | ||
773 | * FLAC__stream_decoder_get_state() to see what went wrong or to | ||
774 | * check for lost synchronization (a sign of stream corruption). | ||
775 | */ | ||
776 | FLAC_API FLAC__bool FLAC__stream_decoder_process_single(FLAC__StreamDecoder *decoder); | ||
777 | |||
778 | /** Decode until the end of the metadata. | ||
779 | * This version instructs the decoder to decode from the current position | ||
780 | * and continue until all the metadata has been read, or until the | ||
781 | * callbacks return a fatal error or the read callback returns | ||
782 | * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM. | ||
783 | * | ||
784 | * As the decoder needs more input it will call the read callback. | ||
785 | * As each metadata block is decoded, the metadata callback will be called | ||
786 | * with the decoded metadata. If the decoder loses sync it will call the | ||
787 | * error callback. | ||
788 | * | ||
789 | * \param decoder An initialized decoder instance. | ||
790 | * \assert | ||
791 | * \code decoder != NULL \endcode | ||
792 | * \retval FLAC__bool | ||
793 | * \c false if any read or write error occurred (except | ||
794 | * \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true; | ||
795 | * in any case, check the decoder state with | ||
796 | * FLAC__stream_decoder_get_state() to see what went wrong or to | ||
797 | * check for lost synchronization (a sign of stream corruption). | ||
798 | */ | ||
799 | FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_metadata(FLAC__StreamDecoder *decoder); | ||
800 | |||
801 | /** Decode until the end of the stream. | ||
802 | * This version instructs the decoder to decode from the current position | ||
803 | * and continue until the end of stream (the read callback returns | ||
804 | * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM), or until the | ||
805 | * callbacks return a fatal error. | ||
806 | * | ||
807 | * As the decoder needs more input it will call the read callback. | ||
808 | * As each metadata block and frame is decoded, the metadata or write | ||
809 | * callback will be called with the decoded metadata or frame. If the | ||
810 | * decoder loses sync it will call the error callback. | ||
811 | * | ||
812 | * \param decoder An initialized decoder instance. | ||
813 | * \assert | ||
814 | * \code decoder != NULL \endcode | ||
815 | * \retval FLAC__bool | ||
816 | * \c false if any read or write error occurred (except | ||
817 | * \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true; | ||
818 | * in any case, check the decoder state with | ||
819 | * FLAC__stream_decoder_get_state() to see what went wrong or to | ||
820 | * check for lost synchronization (a sign of stream corruption). | ||
821 | */ | ||
822 | FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_stream(FLAC__StreamDecoder *decoder); | ||
823 | |||
824 | /** Skip one audio frame. | ||
825 | * This version instructs the decoder to 'skip' a single frame and stop, | ||
826 | * unless the callbacks return a fatal error or the read callback returns | ||
827 | * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM. | ||
828 | * | ||
829 | * The decoding flow is the same as what occurs when | ||
830 | * FLAC__stream_decoder_process_single() is called to process an audio | ||
831 | * frame, except that this function does not decode the parsed data into | ||
832 | * PCM or call the write callback. The integrity of the frame is still | ||
833 | * checked the same way as in the other process functions. | ||
834 | * | ||
835 | * This function will return once one whole frame is skipped, in the | ||
836 | * same way that FLAC__stream_decoder_process_single() will return once | ||
837 | * one whole frame is decoded. | ||
838 | * | ||
839 | * This function, when used from the higher FLAC__SeekableStreamDecoder | ||
840 | * layer, can be used in more quickly determining FLAC frame boundaries | ||
841 | * when decoding of the actual data is not needed, for example when an | ||
842 | * application is separating a FLAC stream into frames for editing or | ||
843 | * storing in a container. To do this, the application can use | ||
844 | * FLAC__seekable_stream_decoder_skip_single_frame() to quickly advance | ||
845 | * to the next frame, then use | ||
846 | * FLAC__seekable_stream_decoder_get_decode_position() to find the new | ||
847 | * frame boundary. | ||
848 | * | ||
849 | * This function should only be called when the stream has advanced | ||
850 | * past all the metadata, otherwise it will return \c false. | ||
851 | * | ||
852 | * \param decoder An initialized decoder instance not in a metadata | ||
853 | * state. | ||
854 | * \assert | ||
855 | * \code decoder != NULL \endcode | ||
856 | * \retval FLAC__bool | ||
857 | * \c false if any read or write error occurred (except | ||
858 | * \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), or if the decoder | ||
859 | * is in the FLAC__STREAM_DECODER_SEARCH_FOR_METADATA or | ||
860 | * FLAC__STREAM_DECODER_READ_METADATA state, else \c true; | ||
861 | * in any case, check the decoder state with | ||
862 | * FLAC__stream_decoder_get_state() to see what went wrong or to | ||
863 | * check for lost synchronization (a sign of stream corruption). | ||
864 | */ | ||
865 | FLAC_API FLAC__bool FLAC__stream_decoder_skip_single_frame(FLAC__StreamDecoder *decoder); | ||
866 | |||
867 | /* \} */ | ||
868 | |||
869 | #ifdef __cplusplus | ||
870 | } | ||
871 | #endif | ||
872 | |||
873 | #endif | ||
diff --git a/apps/codecs/libFLAC/include/FLAC/stream_encoder.h b/apps/codecs/libFLAC/include/FLAC/stream_encoder.h new file mode 100644 index 0000000000..0ac18a365d --- /dev/null +++ b/apps/codecs/libFLAC/include/FLAC/stream_encoder.h | |||
@@ -0,0 +1,1064 @@ | |||
1 | /* libFLAC - Free Lossless Audio Codec library | ||
2 | * Copyright (C) 2000,2001,2002,2003,2004,2005 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__STREAM_ENCODER_H | ||
33 | #define FLAC__STREAM_ENCODER_H | ||
34 | |||
35 | #include "export.h" | ||
36 | #include "format.h" | ||
37 | #include "stream_decoder.h" | ||
38 | |||
39 | #ifdef __cplusplus | ||
40 | extern "C" { | ||
41 | #endif | ||
42 | |||
43 | |||
44 | /** \file include/FLAC/stream_encoder.h | ||
45 | * | ||
46 | * \brief | ||
47 | * This module contains the functions which implement the stream | ||
48 | * encoder. | ||
49 | * | ||
50 | * See the detailed documentation in the | ||
51 | * \link flac_stream_encoder stream encoder \endlink module. | ||
52 | */ | ||
53 | |||
54 | /** \defgroup flac_encoder FLAC/ *_encoder.h: encoder interfaces | ||
55 | * \ingroup flac | ||
56 | * | ||
57 | * \brief | ||
58 | * This module describes the two encoder layers provided by libFLAC. | ||
59 | * | ||
60 | * For encoding FLAC streams, libFLAC provides three layers of access. The | ||
61 | * lowest layer is non-seekable stream-level encoding, the next is seekable | ||
62 | * stream-level encoding, and the highest layer is file-level encoding. The | ||
63 | * interfaces are described in the \link flac_stream_encoder stream encoder | ||
64 | * \endlink, \link flac_seekable_stream_encoder seekable stream encoder | ||
65 | * \endlink, and \link flac_file_encoder file encoder \endlink modules | ||
66 | * respectively. Typically you will choose the highest layer that your input | ||
67 | * source will support. | ||
68 | * The stream encoder relies on callbacks for writing the data and | ||
69 | * metadata. The file encoder provides these callbacks internally and you | ||
70 | * need only supply the filename. | ||
71 | * | ||
72 | * The stream encoder relies on callbacks for writing the data and has no | ||
73 | * provisions for seeking the output. The seekable stream encoder wraps | ||
74 | * the stream encoder and also automaticallay handles the writing back of | ||
75 | * metadata discovered while encoding. However, you must provide extra | ||
76 | * callbacks for seek-related operations on your output, like seek and | ||
77 | * tell. The file encoder wraps the seekable stream encoder and supplies | ||
78 | * all of the callbacks internally, simplifying the processing of standard | ||
79 | * files. The only callback exposed is for progress reporting, and that | ||
80 | * is optional. | ||
81 | */ | ||
82 | |||
83 | /** \defgroup flac_stream_encoder FLAC/stream_encoder.h: stream encoder interface | ||
84 | * \ingroup flac_encoder | ||
85 | * | ||
86 | * \brief | ||
87 | * This module contains the functions which implement the stream | ||
88 | * encoder. | ||
89 | * | ||
90 | * The basic usage of this encoder is as follows: | ||
91 | * - The program creates an instance of an encoder using | ||
92 | * FLAC__stream_encoder_new(). | ||
93 | * - The program overrides the default settings and sets callbacks using | ||
94 | * FLAC__stream_encoder_set_*() functions. | ||
95 | * - The program initializes the instance to validate the settings and | ||
96 | * prepare for encoding using FLAC__stream_encoder_init(). | ||
97 | * - The program calls FLAC__stream_encoder_process() or | ||
98 | * FLAC__stream_encoder_process_interleaved() to encode data, which | ||
99 | * subsequently calls the callbacks when there is encoder data ready | ||
100 | * to be written. | ||
101 | * - The program finishes the encoding with FLAC__stream_encoder_finish(), | ||
102 | * which causes the encoder to encode any data still in its input pipe, | ||
103 | * call the metadata callback with the final encoding statistics, and | ||
104 | * finally reset the encoder to the uninitialized state. | ||
105 | * - The instance may be used again or deleted with | ||
106 | * FLAC__stream_encoder_delete(). | ||
107 | * | ||
108 | * In more detail, the stream encoder functions similarly to the | ||
109 | * \link flac_stream_decoder stream decoder \endlink, but has fewer | ||
110 | * callbacks and more options. Typically the user will create a new | ||
111 | * instance by calling FLAC__stream_encoder_new(), then set the necessary | ||
112 | * parameters and callbacks with FLAC__stream_encoder_set_*(), and | ||
113 | * initialize it by calling FLAC__stream_encoder_init(). | ||
114 | * | ||
115 | * Unlike the decoders, the stream encoder has many options that can | ||
116 | * affect the speed and compression ratio. When setting these parameters | ||
117 | * you should have some basic knowledge of the format (see the | ||
118 | * <A HREF="../documentation.html#format">user-level documentation</A> | ||
119 | * or the <A HREF="../format.html">formal description</A>). The | ||
120 | * FLAC__stream_encoder_set_*() functions themselves do not validate the | ||
121 | * values as many are interdependent. The FLAC__stream_encoder_init() | ||
122 | * function will do this, so make sure to pay attention to the state | ||
123 | * returned by FLAC__stream_encoder_init() to make sure that it is | ||
124 | * FLAC__STREAM_ENCODER_OK. Any parameters that are not set before | ||
125 | * FLAC__stream_encoder_init() will take on the defaults from the | ||
126 | * constructor. | ||
127 | * | ||
128 | * The user must provide function pointers for the following callbacks: | ||
129 | * | ||
130 | * - Write callback - This function is called by the encoder anytime there | ||
131 | * is raw encoded data to write. It may include metadata mixed with | ||
132 | * encoded audio frames and the data is not guaranteed to be aligned on | ||
133 | * frame or metadata block boundaries. | ||
134 | * - Metadata callback - This function is called once at the end of | ||
135 | * encoding with the populated STREAMINFO structure. This is so file | ||
136 | * encoders can seek back to the beginning of the file and write the | ||
137 | * STREAMINFO block with the correct statistics after encoding (like | ||
138 | * minimum/maximum frame size). | ||
139 | * | ||
140 | * The call to FLAC__stream_encoder_init() currently will also immediately | ||
141 | * call the write callback several times, once with the \c fLaC signature, | ||
142 | * and once for each encoded metadata block. | ||
143 | * | ||
144 | * After initializing the instance, the user may feed audio data to the | ||
145 | * encoder in one of two ways: | ||
146 | * | ||
147 | * - Channel separate, through FLAC__stream_encoder_process() - The user | ||
148 | * will pass an array of pointers to buffers, one for each channel, to | ||
149 | * the encoder, each of the same length. The samples need not be | ||
150 | * block-aligned. | ||
151 | * - Channel interleaved, through | ||
152 | * FLAC__stream_encoder_process_interleaved() - The user will pass a single | ||
153 | * pointer to data that is channel-interleaved (i.e. channel0_sample0, | ||
154 | * channel1_sample0, ... , channelN_sample0, channel0_sample1, ...). | ||
155 | * Again, the samples need not be block-aligned but they must be | ||
156 | * sample-aligned, i.e. the first value should be channel0_sample0 and | ||
157 | * the last value channelN_sampleM. | ||
158 | * | ||
159 | * When the user is finished encoding data, it calls | ||
160 | * FLAC__stream_encoder_finish(), which causes the encoder to encode any | ||
161 | * data still in its input pipe, and call the metadata callback with the | ||
162 | * final encoding statistics. Then the instance may be deleted with | ||
163 | * FLAC__stream_encoder_delete() or initialized again to encode another | ||
164 | * stream. | ||
165 | * | ||
166 | * For programs that write their own metadata, but that do not know the | ||
167 | * actual metadata until after encoding, it is advantageous to instruct | ||
168 | * the encoder to write a PADDING block of the correct size, so that | ||
169 | * instead of rewriting the whole stream after encoding, the program can | ||
170 | * just overwrite the PADDING block. If only the maximum size of the | ||
171 | * metadata is known, the program can write a slightly larger padding | ||
172 | * block, then split it after encoding. | ||
173 | * | ||
174 | * Make sure you understand how lengths are calculated. All FLAC metadata | ||
175 | * blocks have a 4 byte header which contains the type and length. This | ||
176 | * length does not include the 4 bytes of the header. See the format page | ||
177 | * for the specification of metadata blocks and their lengths. | ||
178 | * | ||
179 | * \note | ||
180 | * The "set" functions may only be called when the encoder is in the | ||
181 | * state FLAC__STREAM_ENCODER_UNINITIALIZED, i.e. after | ||
182 | * FLAC__stream_encoder_new() or FLAC__stream_encoder_finish(), but | ||
183 | * before FLAC__stream_encoder_init(). If this is the case they will | ||
184 | * return \c true, otherwise \c false. | ||
185 | * | ||
186 | * \note | ||
187 | * FLAC__stream_encoder_finish() resets all settings to the constructor | ||
188 | * defaults, including the callbacks. | ||
189 | * | ||
190 | * \{ | ||
191 | */ | ||
192 | |||
193 | |||
194 | /** State values for a FLAC__StreamEncoder | ||
195 | * | ||
196 | * The encoder's state can be obtained by calling FLAC__stream_encoder_get_state(). | ||
197 | */ | ||
198 | typedef enum { | ||
199 | |||
200 | FLAC__STREAM_ENCODER_OK = 0, | ||
201 | /**< The encoder is in the normal OK state. */ | ||
202 | |||
203 | FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR, | ||
204 | /**< An error occurred in the underlying verify stream decoder; | ||
205 | * check FLAC__stream_encoder_get_verify_decoder_state(). | ||
206 | */ | ||
207 | |||
208 | FLAC__STREAM_ENCODER_VERIFY_MISMATCH_IN_AUDIO_DATA, | ||
209 | /**< The verify decoder detected a mismatch between the original | ||
210 | * audio signal and the decoded audio signal. | ||
211 | */ | ||
212 | |||
213 | FLAC__STREAM_ENCODER_INVALID_CALLBACK, | ||
214 | /**< The encoder was initialized before setting all the required callbacks. */ | ||
215 | |||
216 | FLAC__STREAM_ENCODER_INVALID_NUMBER_OF_CHANNELS, | ||
217 | /**< The encoder has an invalid setting for number of channels. */ | ||
218 | |||
219 | FLAC__STREAM_ENCODER_INVALID_BITS_PER_SAMPLE, | ||
220 | /**< The encoder has an invalid setting for bits-per-sample. | ||
221 | * FLAC supports 4-32 bps but the reference encoder currently supports | ||
222 | * only up to 24 bps. | ||
223 | */ | ||
224 | |||
225 | FLAC__STREAM_ENCODER_INVALID_SAMPLE_RATE, | ||
226 | /**< The encoder has an invalid setting for the input sample rate. */ | ||
227 | |||
228 | FLAC__STREAM_ENCODER_INVALID_BLOCK_SIZE, | ||
229 | /**< The encoder has an invalid setting for the block size. */ | ||
230 | |||
231 | FLAC__STREAM_ENCODER_INVALID_MAX_LPC_ORDER, | ||
232 | /**< The encoder has an invalid setting for the maximum LPC order. */ | ||
233 | |||
234 | FLAC__STREAM_ENCODER_INVALID_QLP_COEFF_PRECISION, | ||
235 | /**< The encoder has an invalid setting for the precision of the quantized linear predictor coefficients. */ | ||
236 | |||
237 | FLAC__STREAM_ENCODER_MID_SIDE_CHANNELS_MISMATCH, | ||
238 | /**< Mid/side coding was specified but the number of channels is not equal to 2. */ | ||
239 | |||
240 | FLAC__STREAM_ENCODER_MID_SIDE_SAMPLE_SIZE_MISMATCH, | ||
241 | /**< Deprecated. */ | ||
242 | |||
243 | FLAC__STREAM_ENCODER_ILLEGAL_MID_SIDE_FORCE, | ||
244 | /**< Loose mid/side coding was specified but mid/side coding was not. */ | ||
245 | |||
246 | FLAC__STREAM_ENCODER_BLOCK_SIZE_TOO_SMALL_FOR_LPC_ORDER, | ||
247 | /**< The specified block size is less than the maximum LPC order. */ | ||
248 | |||
249 | FLAC__STREAM_ENCODER_NOT_STREAMABLE, | ||
250 | /**< The encoder is bound to the "streamable subset" but other settings violate it. */ | ||
251 | |||
252 | FLAC__STREAM_ENCODER_FRAMING_ERROR, | ||
253 | /**< An error occurred while writing the stream; usually, the write_callback returned an error. */ | ||
254 | |||
255 | FLAC__STREAM_ENCODER_INVALID_METADATA, | ||
256 | /**< The metadata input to the encoder is invalid, in one of the following ways: | ||
257 | * - FLAC__stream_encoder_set_metadata() was called with a null pointer but a block count > 0 | ||
258 | * - One of the metadata blocks contains an undefined type | ||
259 | * - It contains an illegal CUESHEET as checked by FLAC__format_cuesheet_is_legal() | ||
260 | * - It contains an illegal SEEKTABLE as checked by FLAC__format_seektable_is_legal() | ||
261 | * - It contains more than one SEEKTABLE block or more than one VORBIS_COMMENT block | ||
262 | */ | ||
263 | |||
264 | FLAC__STREAM_ENCODER_FATAL_ERROR_WHILE_ENCODING, | ||
265 | /**< An error occurred while writing the stream; usually, the write_callback returned an error. */ | ||
266 | |||
267 | FLAC__STREAM_ENCODER_FATAL_ERROR_WHILE_WRITING, | ||
268 | /**< The write_callback returned an error. */ | ||
269 | |||
270 | FLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR, | ||
271 | /**< Memory allocation failed. */ | ||
272 | |||
273 | FLAC__STREAM_ENCODER_ALREADY_INITIALIZED, | ||
274 | /**< FLAC__stream_encoder_init() was called when the encoder was | ||
275 | * already initialized, usually because | ||
276 | * FLAC__stream_encoder_finish() was not called. | ||
277 | */ | ||
278 | |||
279 | FLAC__STREAM_ENCODER_UNINITIALIZED | ||
280 | /**< The encoder is in the uninitialized state. */ | ||
281 | |||
282 | } FLAC__StreamEncoderState; | ||
283 | |||
284 | /** Maps a FLAC__StreamEncoderState to a C string. | ||
285 | * | ||
286 | * Using a FLAC__StreamEncoderState as the index to this array | ||
287 | * will give the string equivalent. The contents should not be modified. | ||
288 | */ | ||
289 | extern FLAC_API const char * const FLAC__StreamEncoderStateString[]; | ||
290 | |||
291 | /** Return values for the FLAC__StreamEncoder write callback. | ||
292 | */ | ||
293 | typedef enum { | ||
294 | |||
295 | FLAC__STREAM_ENCODER_WRITE_STATUS_OK = 0, | ||
296 | /**< The write was OK and encoding can continue. */ | ||
297 | |||
298 | FLAC__STREAM_ENCODER_WRITE_STATUS_FATAL_ERROR | ||
299 | /**< An unrecoverable error occurred. The encoder will return from the process call. */ | ||
300 | |||
301 | } FLAC__StreamEncoderWriteStatus; | ||
302 | |||
303 | /** Maps a FLAC__StreamEncoderWriteStatus to a C string. | ||
304 | * | ||
305 | * Using a FLAC__StreamEncoderWriteStatus as the index to this array | ||
306 | * will give the string equivalent. The contents should not be modified. | ||
307 | */ | ||
308 | extern FLAC_API const char * const FLAC__StreamEncoderWriteStatusString[]; | ||
309 | |||
310 | |||
311 | /*********************************************************************** | ||
312 | * | ||
313 | * class FLAC__StreamEncoder | ||
314 | * | ||
315 | ***********************************************************************/ | ||
316 | |||
317 | struct FLAC__StreamEncoderProtected; | ||
318 | struct FLAC__StreamEncoderPrivate; | ||
319 | /** The opaque structure definition for the stream encoder type. | ||
320 | * See the \link flac_stream_encoder stream encoder module \endlink | ||
321 | * for a detailed description. | ||
322 | */ | ||
323 | typedef struct { | ||
324 | struct FLAC__StreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */ | ||
325 | struct FLAC__StreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */ | ||
326 | } FLAC__StreamEncoder; | ||
327 | |||
328 | /** Signature for the write callback. | ||
329 | * See FLAC__stream_encoder_set_write_callback() for more info. | ||
330 | * | ||
331 | * \param encoder The encoder instance calling the callback. | ||
332 | * \param buffer An array of encoded data of length \a bytes. | ||
333 | * \param bytes The byte length of \a buffer. | ||
334 | * \param samples The number of samples encoded by \a buffer. | ||
335 | * \c 0 has a special meaning; see | ||
336 | * FLAC__stream_encoder_set_write_callback(). | ||
337 | * \param current_frame The number of the current frame being encoded. | ||
338 | * \param client_data The callee's client data set through | ||
339 | * FLAC__stream_encoder_set_client_data(). | ||
340 | * \retval FLAC__StreamEncoderWriteStatus | ||
341 | * The callee's return status. | ||
342 | */ | ||
343 | typedef FLAC__StreamEncoderWriteStatus (*FLAC__StreamEncoderWriteCallback)(const FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data); | ||
344 | |||
345 | /** Signature for the metadata callback. | ||
346 | * See FLAC__stream_encoder_set_metadata_callback() for more info. | ||
347 | * | ||
348 | * \param encoder The encoder instance calling the callback. | ||
349 | * \param metadata The final populated STREAMINFO block. | ||
350 | * \param client_data The callee's client data set through | ||
351 | * FLAC__stream_encoder_set_client_data(). | ||
352 | */ | ||
353 | typedef void (*FLAC__StreamEncoderMetadataCallback)(const FLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data); | ||
354 | |||
355 | |||
356 | /*********************************************************************** | ||
357 | * | ||
358 | * Class constructor/destructor | ||
359 | * | ||
360 | ***********************************************************************/ | ||
361 | |||
362 | /** Create a new stream encoder instance. The instance is created with | ||
363 | * default settings; see the individual FLAC__stream_encoder_set_*() | ||
364 | * functions for each setting's default. | ||
365 | * | ||
366 | * \retval FLAC__StreamEncoder* | ||
367 | * \c NULL if there was an error allocating memory, else the new instance. | ||
368 | */ | ||
369 | FLAC_API FLAC__StreamEncoder *FLAC__stream_encoder_new(); | ||
370 | |||
371 | /** Free an encoder instance. Deletes the object pointed to by \a encoder. | ||
372 | * | ||
373 | * \param encoder A pointer to an existing encoder. | ||
374 | * \assert | ||
375 | * \code encoder != NULL \endcode | ||
376 | */ | ||
377 | FLAC_API void FLAC__stream_encoder_delete(FLAC__StreamEncoder *encoder); | ||
378 | |||
379 | |||
380 | /*********************************************************************** | ||
381 | * | ||
382 | * Public class method prototypes | ||
383 | * | ||
384 | ***********************************************************************/ | ||
385 | |||
386 | /** Set the "verify" flag. If \c true, the encoder will verify it's own | ||
387 | * encoded output by feeding it through an internal decoder and comparing | ||
388 | * the original signal against the decoded signal. If a mismatch occurs, | ||
389 | * the process call will return \c false. Note that this will slow the | ||
390 | * encoding process by the extra time required for decoding and comparison. | ||
391 | * | ||
392 | * \default \c false | ||
393 | * \param encoder An encoder instance to set. | ||
394 | * \param value Flag value (see above). | ||
395 | * \assert | ||
396 | * \code encoder != NULL \endcode | ||
397 | * \retval FLAC__bool | ||
398 | * \c false if the encoder is already initialized, else \c true. | ||
399 | */ | ||
400 | FLAC_API FLAC__bool FLAC__stream_encoder_set_verify(FLAC__StreamEncoder *encoder, FLAC__bool value); | ||
401 | |||
402 | /** Set the "streamable subset" flag. If \c true, the encoder will comply | ||
403 | * with the subset (see the format specification) and will check the | ||
404 | * settings during FLAC__stream_encoder_init() to see if all settings | ||
405 | * comply. If \c false, the settings may take advantage of the full | ||
406 | * range that the format allows. | ||
407 | * | ||
408 | * Make sure you know what it entails before setting this to \c false. | ||
409 | * | ||
410 | * \default \c true | ||
411 | * \param encoder An encoder instance to set. | ||
412 | * \param value Flag value (see above). | ||
413 | * \assert | ||
414 | * \code encoder != NULL \endcode | ||
415 | * \retval FLAC__bool | ||
416 | * \c false if the encoder is already initialized, else \c true. | ||
417 | */ | ||
418 | FLAC_API FLAC__bool FLAC__stream_encoder_set_streamable_subset(FLAC__StreamEncoder *encoder, FLAC__bool value); | ||
419 | |||
420 | /** Set to \c true to enable mid-side encoding on stereo input. The | ||
421 | * number of channels must be 2. Set to \c false to use only | ||
422 | * independent channel coding. | ||
423 | * | ||
424 | * \default \c false | ||
425 | * \param encoder An encoder instance to set. | ||
426 | * \param value Flag value (see above). | ||
427 | * \assert | ||
428 | * \code encoder != NULL \endcode | ||
429 | * \retval FLAC__bool | ||
430 | * \c false if the encoder is already initialized, else \c true. | ||
431 | */ | ||
432 | FLAC_API FLAC__bool FLAC__stream_encoder_set_do_mid_side_stereo(FLAC__StreamEncoder *encoder, FLAC__bool value); | ||
433 | |||
434 | /** Set to \c true to enable adaptive switching between mid-side and | ||
435 | * left-right encoding on stereo input. The number of channels must | ||
436 | * be 2. Set to \c false to use exhaustive searching. In either | ||
437 | * case, the mid/side stereo setting must be \c true. | ||
438 | * | ||
439 | * \default \c false | ||
440 | * \param encoder An encoder instance to set. | ||
441 | * \param value Flag value (see above). | ||
442 | * \assert | ||
443 | * \code encoder != NULL \endcode | ||
444 | * \retval FLAC__bool | ||
445 | * \c false if the encoder is already initialized, else \c true. | ||
446 | */ | ||
447 | FLAC_API FLAC__bool FLAC__stream_encoder_set_loose_mid_side_stereo(FLAC__StreamEncoder *encoder, FLAC__bool value); | ||
448 | |||
449 | /** Set the number of channels to be encoded. | ||
450 | * | ||
451 | * \default \c 2 | ||
452 | * \param encoder An encoder instance to set. | ||
453 | * \param value See above. | ||
454 | * \assert | ||
455 | * \code encoder != NULL \endcode | ||
456 | * \retval FLAC__bool | ||
457 | * \c false if the encoder is already initialized, else \c true. | ||
458 | */ | ||
459 | FLAC_API FLAC__bool FLAC__stream_encoder_set_channels(FLAC__StreamEncoder *encoder, unsigned value); | ||
460 | |||
461 | /** Set the sample resolution of the input to be encoded. | ||
462 | * | ||
463 | * \warning | ||
464 | * Do not feed the encoder data that is wider than the value you | ||
465 | * set here or you will generate an invalid stream. | ||
466 | * | ||
467 | * \default \c 16 | ||
468 | * \param encoder An encoder instance to set. | ||
469 | * \param value See above. | ||
470 | * \assert | ||
471 | * \code encoder != NULL \endcode | ||
472 | * \retval FLAC__bool | ||
473 | * \c false if the encoder is already initialized, else \c true. | ||
474 | */ | ||
475 | FLAC_API FLAC__bool FLAC__stream_encoder_set_bits_per_sample(FLAC__StreamEncoder *encoder, unsigned value); | ||
476 | |||
477 | /** Set the sample rate (in Hz) of the input to be encoded. | ||
478 | * | ||
479 | * \default \c 44100 | ||
480 | * \param encoder An encoder instance to set. | ||
481 | * \param value See above. | ||
482 | * \assert | ||
483 | * \code encoder != NULL \endcode | ||
484 | * \retval FLAC__bool | ||
485 | * \c false if the encoder is already initialized, else \c true. | ||
486 | */ | ||
487 | FLAC_API FLAC__bool FLAC__stream_encoder_set_sample_rate(FLAC__StreamEncoder *encoder, unsigned value); | ||
488 | |||
489 | /** Set the blocksize to use while encoding. | ||
490 | * | ||
491 | * \default \c 1152 | ||
492 | * \param encoder An encoder instance to set. | ||
493 | * \param value See above. | ||
494 | * \assert | ||
495 | * \code encoder != NULL \endcode | ||
496 | * \retval FLAC__bool | ||
497 | * \c false if the encoder is already initialized, else \c true. | ||
498 | */ | ||
499 | FLAC_API FLAC__bool FLAC__stream_encoder_set_blocksize(FLAC__StreamEncoder *encoder, unsigned value); | ||
500 | |||
501 | /** Set the maximum LPC order, or \c 0 to use only the fixed predictors. | ||
502 | * | ||
503 | * \default \c 0 | ||
504 | * \param encoder An encoder instance to set. | ||
505 | * \param value See above. | ||
506 | * \assert | ||
507 | * \code encoder != NULL \endcode | ||
508 | * \retval FLAC__bool | ||
509 | * \c false if the encoder is already initialized, else \c true. | ||
510 | */ | ||
511 | FLAC_API FLAC__bool FLAC__stream_encoder_set_max_lpc_order(FLAC__StreamEncoder *encoder, unsigned value); | ||
512 | |||
513 | /** Set the precision, in bits, of the quantized linear predictor | ||
514 | * coefficients, or \c 0 to let the encoder select it based on the | ||
515 | * blocksize. | ||
516 | * | ||
517 | * \note | ||
518 | * In the current implementation, qlp_coeff_precision + bits_per_sample must | ||
519 | * be less than 32. | ||
520 | * | ||
521 | * \default \c 0 | ||
522 | * \param encoder An encoder instance to set. | ||
523 | * \param value See above. | ||
524 | * \assert | ||
525 | * \code encoder != NULL \endcode | ||
526 | * \retval FLAC__bool | ||
527 | * \c false if the encoder is already initialized, else \c true. | ||
528 | */ | ||
529 | FLAC_API FLAC__bool FLAC__stream_encoder_set_qlp_coeff_precision(FLAC__StreamEncoder *encoder, unsigned value); | ||
530 | |||
531 | /** Set to \c false to use only the specified quantized linear predictor | ||
532 | * coefficient precision, or \c true to search neighboring precision | ||
533 | * values and use the best one. | ||
534 | * | ||
535 | * \default \c false | ||
536 | * \param encoder An encoder instance to set. | ||
537 | * \param value See above. | ||
538 | * \assert | ||
539 | * \code encoder != NULL \endcode | ||
540 | * \retval FLAC__bool | ||
541 | * \c false if the encoder is already initialized, else \c true. | ||
542 | */ | ||
543 | FLAC_API FLAC__bool FLAC__stream_encoder_set_do_qlp_coeff_prec_search(FLAC__StreamEncoder *encoder, FLAC__bool value); | ||
544 | |||
545 | /** Deprecated. Setting this value has no effect. | ||
546 | * | ||
547 | * \default \c false | ||
548 | * \param encoder An encoder instance to set. | ||
549 | * \param value See above. | ||
550 | * \assert | ||
551 | * \code encoder != NULL \endcode | ||
552 | * \retval FLAC__bool | ||
553 | * \c false if the encoder is already initialized, else \c true. | ||
554 | */ | ||
555 | FLAC_API FLAC__bool FLAC__stream_encoder_set_do_escape_coding(FLAC__StreamEncoder *encoder, FLAC__bool value); | ||
556 | |||
557 | /** Set to \c false to let the encoder estimate the best model order | ||
558 | * based on the residual signal energy, or \c true to force the | ||
559 | * encoder to evaluate all order models and select the best. | ||
560 | * | ||
561 | * \default \c false | ||
562 | * \param encoder An encoder instance to set. | ||
563 | * \param value See above. | ||
564 | * \assert | ||
565 | * \code encoder != NULL \endcode | ||
566 | * \retval FLAC__bool | ||
567 | * \c false if the encoder is already initialized, else \c true. | ||
568 | */ | ||
569 | FLAC_API FLAC__bool FLAC__stream_encoder_set_do_exhaustive_model_search(FLAC__StreamEncoder *encoder, FLAC__bool value); | ||
570 | |||
571 | /** Set the minimum partition order to search when coding the residual. | ||
572 | * This is used in tandem with | ||
573 | * FLAC__stream_encoder_set_max_residual_partition_order(). | ||
574 | * | ||
575 | * The partition order determines the context size in the residual. | ||
576 | * The context size will be approximately <tt>blocksize / (2 ^ order)</tt>. | ||
577 | * | ||
578 | * Set both min and max values to \c 0 to force a single context, | ||
579 | * whose Rice parameter is based on the residual signal variance. | ||
580 | * Otherwise, set a min and max order, and the encoder will search | ||
581 | * all orders, using the mean of each context for its Rice parameter, | ||
582 | * and use the best. | ||
583 | * | ||
584 | * \default \c 0 | ||
585 | * \param encoder An encoder instance to set. | ||
586 | * \param value See above. | ||
587 | * \assert | ||
588 | * \code encoder != NULL \endcode | ||
589 | * \retval FLAC__bool | ||
590 | * \c false if the encoder is already initialized, else \c true. | ||
591 | */ | ||
592 | FLAC_API FLAC__bool FLAC__stream_encoder_set_min_residual_partition_order(FLAC__StreamEncoder *encoder, unsigned value); | ||
593 | |||
594 | /** Set the maximum partition order to search when coding the residual. | ||
595 | * This is used in tandem with | ||
596 | * FLAC__stream_encoder_set_min_residual_partition_order(). | ||
597 | * | ||
598 | * The partition order determines the context size in the residual. | ||
599 | * The context size will be approximately <tt>blocksize / (2 ^ order)</tt>. | ||
600 | * | ||
601 | * Set both min and max values to \c 0 to force a single context, | ||
602 | * whose Rice parameter is based on the residual signal variance. | ||
603 | * Otherwise, set a min and max order, and the encoder will search | ||
604 | * all orders, using the mean of each context for its Rice parameter, | ||
605 | * and use the best. | ||
606 | * | ||
607 | * \default \c 0 | ||
608 | * \param encoder An encoder instance to set. | ||
609 | * \param value See above. | ||
610 | * \assert | ||
611 | * \code encoder != NULL \endcode | ||
612 | * \retval FLAC__bool | ||
613 | * \c false if the encoder is already initialized, else \c true. | ||
614 | */ | ||
615 | FLAC_API FLAC__bool FLAC__stream_encoder_set_max_residual_partition_order(FLAC__StreamEncoder *encoder, unsigned value); | ||
616 | |||
617 | /** Deprecated. Setting this value has no effect. | ||
618 | * | ||
619 | * \default \c 0 | ||
620 | * \param encoder An encoder instance to set. | ||
621 | * \param value See above. | ||
622 | * \assert | ||
623 | * \code encoder != NULL \endcode | ||
624 | * \retval FLAC__bool | ||
625 | * \c false if the encoder is already initialized, else \c true. | ||
626 | */ | ||
627 | FLAC_API FLAC__bool FLAC__stream_encoder_set_rice_parameter_search_dist(FLAC__StreamEncoder *encoder, unsigned value); | ||
628 | |||
629 | /** Set an estimate of the total samples that will be encoded. | ||
630 | * This is merely an estimate and may be set to \c 0 if unknown. | ||
631 | * This value will be written to the STREAMINFO block before encoding, | ||
632 | * and can remove the need for the caller to rewrite the value later | ||
633 | * if the value is known before encoding. | ||
634 | * | ||
635 | * \default \c 0 | ||
636 | * \param encoder An encoder instance to set. | ||
637 | * \param value See above. | ||
638 | * \assert | ||
639 | * \code encoder != NULL \endcode | ||
640 | * \retval FLAC__bool | ||
641 | * \c false if the encoder is already initialized, else \c true. | ||
642 | */ | ||
643 | FLAC_API FLAC__bool FLAC__stream_encoder_set_total_samples_estimate(FLAC__StreamEncoder *encoder, FLAC__uint64 value); | ||
644 | |||
645 | /** Set the metadata blocks to be emitted to the stream before encoding. | ||
646 | * A value of \c NULL, \c 0 implies no metadata; otherwise, supply an | ||
647 | * array of pointers to metadata blocks. The array is non-const since | ||
648 | * the encoder may need to change the \a is_last flag inside them. | ||
649 | * Otherwise, the encoder will not modify or free the blocks. It is up | ||
650 | * to the caller to free the metadata blocks after encoding. | ||
651 | * | ||
652 | * \note | ||
653 | * The encoder stores only the \a metadata pointer; the passed-in array | ||
654 | * must survive at least until after FLAC__stream_encoder_init() returns. | ||
655 | * Do not modify the array or free the blocks until then. | ||
656 | * | ||
657 | * \note | ||
658 | * The STREAMINFO block is always written and no STREAMINFO block may | ||
659 | * occur in the supplied array. | ||
660 | * | ||
661 | * \note | ||
662 | * By default the encoder does not create a SEEKTABLE. If one is supplied | ||
663 | * in the \a metadata array it will be written verbatim. However by itself | ||
664 | * this is not very useful as the user will not know the stream offsets for | ||
665 | * the seekpoints ahead of time. You must use the seekable stream encoder | ||
666 | * to generate a legal seektable | ||
667 | * (see FLAC__seekable_stream_encoder_set_metadata()) | ||
668 | * | ||
669 | * \note | ||
670 | * A VORBIS_COMMENT block may be supplied. The vendor string in it | ||
671 | * will be ignored. libFLAC will use it's own vendor string. libFLAC | ||
672 | * will not modify the passed-in VORBIS_COMMENT's vendor string, it | ||
673 | * will simply write it's own into the stream. If no VORBIS_COMMENT | ||
674 | * block is present in the \a metadata array, libFLAC will write an | ||
675 | * empty one, containing only the vendor string. | ||
676 | * | ||
677 | * \default \c NULL, 0 | ||
678 | * \param encoder An encoder instance to set. | ||
679 | * \param metadata See above. | ||
680 | * \param num_blocks See above. | ||
681 | * \assert | ||
682 | * \code encoder != NULL \endcode | ||
683 | * \retval FLAC__bool | ||
684 | * \c false if the encoder is already initialized, else \c true. | ||
685 | */ | ||
686 | FLAC_API FLAC__bool FLAC__stream_encoder_set_metadata(FLAC__StreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks); | ||
687 | |||
688 | /** Set the write callback. | ||
689 | * The supplied function will be called by the encoder anytime there is raw | ||
690 | * encoded data ready to write. It may include metadata mixed with encoded | ||
691 | * audio frames and the data is not guaranteed to be aligned on frame or | ||
692 | * metadata block boundaries. | ||
693 | * | ||
694 | * The only duty of the callback is to write out the \a bytes worth of data | ||
695 | * in \a buffer to the current position in the output stream. The arguments | ||
696 | * \a samples and \a current_frame are purely informational. If \a samples | ||
697 | * is greater than \c 0, then \a current_frame will hold the current frame | ||
698 | * number that is being written; otherwise, the write callback is being called | ||
699 | * to write metadata. | ||
700 | * | ||
701 | * \note | ||
702 | * The callback is mandatory and must be set before initialization. | ||
703 | * | ||
704 | * \default \c NULL | ||
705 | * \param encoder An encoder instance to set. | ||
706 | * \param value See above. | ||
707 | * \assert | ||
708 | * \code encoder != NULL \endcode | ||
709 | * \code value != NULL \endcode | ||
710 | * \retval FLAC__bool | ||
711 | * \c false if the encoder is already initialized, else \c true. | ||
712 | */ | ||
713 | FLAC_API FLAC__bool FLAC__stream_encoder_set_write_callback(FLAC__StreamEncoder *encoder, FLAC__StreamEncoderWriteCallback value); | ||
714 | |||
715 | /** Set the metadata callback. | ||
716 | * The supplied function will be called once at the end of encoding with | ||
717 | * the populated STREAMINFO structure. This is so file encoders can seek | ||
718 | * back to the beginning of the file and write the STREAMINFO block with | ||
719 | * the correct statistics after encoding (like minimum/maximum frame size | ||
720 | * and total samples). | ||
721 | * | ||
722 | * \note | ||
723 | * The callback is mandatory and must be set before initialization. | ||
724 | * | ||
725 | * \default \c NULL | ||
726 | * \param encoder An encoder instance to set. | ||
727 | * \param value See above. | ||
728 | * \assert | ||
729 | * \code encoder != NULL \endcode | ||
730 | * \code value != NULL \endcode | ||
731 | * \retval FLAC__bool | ||
732 | * \c false if the encoder is already initialized, else \c true. | ||
733 | */ | ||
734 | FLAC_API FLAC__bool FLAC__stream_encoder_set_metadata_callback(FLAC__StreamEncoder *encoder, FLAC__StreamEncoderMetadataCallback value); | ||
735 | |||
736 | /** Set the client data to be passed back to callbacks. | ||
737 | * This value will be supplied to callbacks in their \a client_data | ||
738 | * argument. | ||
739 | * | ||
740 | * \default \c NULL | ||
741 | * \param encoder An encoder instance to set. | ||
742 | * \param value See above. | ||
743 | * \assert | ||
744 | * \code encoder != NULL \endcode | ||
745 | * \retval FLAC__bool | ||
746 | * \c false if the encoder is already initialized, else \c true. | ||
747 | */ | ||
748 | FLAC_API FLAC__bool FLAC__stream_encoder_set_client_data(FLAC__StreamEncoder *encoder, void *value); | ||
749 | |||
750 | /** Get the current encoder state. | ||
751 | * | ||
752 | * \param encoder An encoder instance to query. | ||
753 | * \assert | ||
754 | * \code encoder != NULL \endcode | ||
755 | * \retval FLAC__StreamEncoderState | ||
756 | * The current encoder state. | ||
757 | */ | ||
758 | FLAC_API FLAC__StreamEncoderState FLAC__stream_encoder_get_state(const FLAC__StreamEncoder *encoder); | ||
759 | |||
760 | /** Get the state of the verify stream decoder. | ||
761 | * Useful when the stream encoder state is | ||
762 | * \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR. | ||
763 | * | ||
764 | * \param encoder An encoder instance to query. | ||
765 | * \assert | ||
766 | * \code encoder != NULL \endcode | ||
767 | * \retval FLAC__StreamDecoderState | ||
768 | * The verify stream decoder state. | ||
769 | */ | ||
770 | FLAC_API FLAC__StreamDecoderState FLAC__stream_encoder_get_verify_decoder_state(const FLAC__StreamEncoder *encoder); | ||
771 | |||
772 | /** Get the current encoder state as a C string. | ||
773 | * This version automatically resolves | ||
774 | * \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR by getting the | ||
775 | * verify decoder's state. | ||
776 | * | ||
777 | * \param encoder A encoder instance to query. | ||
778 | * \assert | ||
779 | * \code encoder != NULL \endcode | ||
780 | * \retval const char * | ||
781 | * The encoder state as a C string. Do not modify the contents. | ||
782 | */ | ||
783 | FLAC_API const char *FLAC__stream_encoder_get_resolved_state_string(const FLAC__StreamEncoder *encoder); | ||
784 | |||
785 | /** Get relevant values about the nature of a verify decoder error. | ||
786 | * Useful when the stream encoder state is | ||
787 | * \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR. The arguments should | ||
788 | * be addresses in which the stats will be returned, or NULL if value | ||
789 | * is not desired. | ||
790 | * | ||
791 | * \param encoder An encoder instance to query. | ||
792 | * \param absolute_sample The absolute sample number of the mismatch. | ||
793 | * \param frame_number The number of the frame in which the mismatch occurred. | ||
794 | * \param channel The channel in which the mismatch occurred. | ||
795 | * \param sample The number of the sample (relative to the frame) in | ||
796 | * which the mismatch occurred. | ||
797 | * \param expected The expected value for the sample in question. | ||
798 | * \param got The actual value returned by the decoder. | ||
799 | * \assert | ||
800 | * \code encoder != NULL \endcode | ||
801 | */ | ||
802 | FLAC_API void FLAC__stream_encoder_get_verify_decoder_error_stats(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got); | ||
803 | |||
804 | /** Get the "verify" flag. | ||
805 | * | ||
806 | * \param encoder An encoder instance to query. | ||
807 | * \assert | ||
808 | * \code encoder != NULL \endcode | ||
809 | * \retval FLAC__bool | ||
810 | * See FLAC__stream_encoder_set_verify(). | ||
811 | */ | ||
812 | FLAC_API FLAC__bool FLAC__stream_encoder_get_verify(const FLAC__StreamEncoder *encoder); | ||
813 | |||
814 | /** Get the "streamable subset" flag. | ||
815 | * | ||
816 | * \param encoder An encoder instance to query. | ||
817 | * \assert | ||
818 | * \code encoder != NULL \endcode | ||
819 | * \retval FLAC__bool | ||
820 | * See FLAC__stream_encoder_set_streamable_subset(). | ||
821 | */ | ||
822 | FLAC_API FLAC__bool FLAC__stream_encoder_get_streamable_subset(const FLAC__StreamEncoder *encoder); | ||
823 | |||
824 | /** Get the "mid/side stereo coding" flag. | ||
825 | * | ||
826 | * \param encoder An encoder instance to query. | ||
827 | * \assert | ||
828 | * \code encoder != NULL \endcode | ||
829 | * \retval FLAC__bool | ||
830 | * See FLAC__stream_encoder_get_do_mid_side_stereo(). | ||
831 | */ | ||
832 | FLAC_API FLAC__bool FLAC__stream_encoder_get_do_mid_side_stereo(const FLAC__StreamEncoder *encoder); | ||
833 | |||
834 | /** Get the "adaptive mid/side switching" flag. | ||
835 | * | ||
836 | * \param encoder An encoder instance to query. | ||
837 | * \assert | ||
838 | * \code encoder != NULL \endcode | ||
839 | * \retval FLAC__bool | ||
840 | * See FLAC__stream_encoder_set_loose_mid_side_stereo(). | ||
841 | */ | ||
842 | FLAC_API FLAC__bool FLAC__stream_encoder_get_loose_mid_side_stereo(const FLAC__StreamEncoder *encoder); | ||
843 | |||
844 | /** Get the number of input channels being processed. | ||
845 | * | ||
846 | * \param encoder An encoder instance to query. | ||
847 | * \assert | ||
848 | * \code encoder != NULL \endcode | ||
849 | * \retval unsigned | ||
850 | * See FLAC__stream_encoder_set_channels(). | ||
851 | */ | ||
852 | FLAC_API unsigned FLAC__stream_encoder_get_channels(const FLAC__StreamEncoder *encoder); | ||
853 | |||
854 | /** Get the input sample resolution setting. | ||
855 | * | ||
856 | * \param encoder An encoder instance to query. | ||
857 | * \assert | ||
858 | * \code encoder != NULL \endcode | ||
859 | * \retval unsigned | ||
860 | * See FLAC__stream_encoder_set_bits_per_sample(). | ||
861 | */ | ||
862 | FLAC_API unsigned FLAC__stream_encoder_get_bits_per_sample(const FLAC__StreamEncoder *encoder); | ||
863 | |||
864 | /** Get the input sample rate setting. | ||
865 | * | ||
866 | * \param encoder An encoder instance to query. | ||
867 | * \assert | ||
868 | * \code encoder != NULL \endcode | ||
869 | * \retval unsigned | ||
870 | * See FLAC__stream_encoder_set_sample_rate(). | ||
871 | */ | ||
872 | FLAC_API unsigned FLAC__stream_encoder_get_sample_rate(const FLAC__StreamEncoder *encoder); | ||
873 | |||
874 | /** Get the blocksize setting. | ||
875 | * | ||
876 | * \param encoder An encoder instance to query. | ||
877 | * \assert | ||
878 | * \code encoder != NULL \endcode | ||
879 | * \retval unsigned | ||
880 | * See FLAC__stream_encoder_set_blocksize(). | ||
881 | */ | ||
882 | FLAC_API unsigned FLAC__stream_encoder_get_blocksize(const FLAC__StreamEncoder *encoder); | ||
883 | |||
884 | /** Get the maximum LPC order setting. | ||
885 | * | ||
886 | * \param encoder An encoder instance to query. | ||
887 | * \assert | ||
888 | * \code encoder != NULL \endcode | ||
889 | * \retval unsigned | ||
890 | * See FLAC__stream_encoder_set_max_lpc_order(). | ||
891 | */ | ||
892 | FLAC_API unsigned FLAC__stream_encoder_get_max_lpc_order(const FLAC__StreamEncoder *encoder); | ||
893 | |||
894 | /** Get the quantized linear predictor coefficient precision setting. | ||
895 | * | ||
896 | * \param encoder An encoder instance to query. | ||
897 | * \assert | ||
898 | * \code encoder != NULL \endcode | ||
899 | * \retval unsigned | ||
900 | * See FLAC__stream_encoder_set_qlp_coeff_precision(). | ||
901 | */ | ||
902 | FLAC_API unsigned FLAC__stream_encoder_get_qlp_coeff_precision(const FLAC__StreamEncoder *encoder); | ||
903 | |||
904 | /** Get the qlp coefficient precision search flag. | ||
905 | * | ||
906 | * \param encoder An encoder instance to query. | ||
907 | * \assert | ||
908 | * \code encoder != NULL \endcode | ||
909 | * \retval FLAC__bool | ||
910 | * See FLAC__stream_encoder_set_do_qlp_coeff_prec_search(). | ||
911 | */ | ||
912 | FLAC_API FLAC__bool FLAC__stream_encoder_get_do_qlp_coeff_prec_search(const FLAC__StreamEncoder *encoder); | ||
913 | |||
914 | /** Get the "escape coding" flag. | ||
915 | * | ||
916 | * \param encoder An encoder instance to query. | ||
917 | * \assert | ||
918 | * \code encoder != NULL \endcode | ||
919 | * \retval FLAC__bool | ||
920 | * See FLAC__stream_encoder_set_do_escape_coding(). | ||
921 | */ | ||
922 | FLAC_API FLAC__bool FLAC__stream_encoder_get_do_escape_coding(const FLAC__StreamEncoder *encoder); | ||
923 | |||
924 | /** Get the exhaustive model search flag. | ||
925 | * | ||
926 | * \param encoder An encoder instance to query. | ||
927 | * \assert | ||
928 | * \code encoder != NULL \endcode | ||
929 | * \retval FLAC__bool | ||
930 | * See FLAC__stream_encoder_set_do_exhaustive_model_search(). | ||
931 | */ | ||
932 | FLAC_API FLAC__bool FLAC__stream_encoder_get_do_exhaustive_model_search(const FLAC__StreamEncoder *encoder); | ||
933 | |||
934 | /** Get the minimum residual partition order setting. | ||
935 | * | ||
936 | * \param encoder An encoder instance to query. | ||
937 | * \assert | ||
938 | * \code encoder != NULL \endcode | ||
939 | * \retval unsigned | ||
940 | * See FLAC__stream_encoder_set_min_residual_partition_order(). | ||
941 | */ | ||
942 | FLAC_API unsigned FLAC__stream_encoder_get_min_residual_partition_order(const FLAC__StreamEncoder *encoder); | ||
943 | |||
944 | /** Get maximum residual partition order setting. | ||
945 | * | ||
946 | * \param encoder An encoder instance to query. | ||
947 | * \assert | ||
948 | * \code encoder != NULL \endcode | ||
949 | * \retval unsigned | ||
950 | * See FLAC__stream_encoder_set_max_residual_partition_order(). | ||
951 | */ | ||
952 | FLAC_API unsigned FLAC__stream_encoder_get_max_residual_partition_order(const FLAC__StreamEncoder *encoder); | ||
953 | |||
954 | /** Get the Rice parameter search distance setting. | ||
955 | * | ||
956 | * \param encoder An encoder instance to query. | ||
957 | * \assert | ||
958 | * \code encoder != NULL \endcode | ||
959 | * \retval unsigned | ||
960 | * See FLAC__stream_encoder_set_rice_parameter_search_dist(). | ||
961 | */ | ||
962 | FLAC_API unsigned FLAC__stream_encoder_get_rice_parameter_search_dist(const FLAC__StreamEncoder *encoder); | ||
963 | |||
964 | /** Get the previously set estimate of the total samples to be encoded. | ||
965 | * The encoder merely mimics back the value given to | ||
966 | * FLAC__stream_encoder_set_total_samples_estimate() since it has no | ||
967 | * other way of knowing how many samples the user will encode. | ||
968 | * | ||
969 | * \param encoder An encoder instance to set. | ||
970 | * \assert | ||
971 | * \code encoder != NULL \endcode | ||
972 | * \retval FLAC__uint64 | ||
973 | * See FLAC__stream_encoder_get_total_samples_estimate(). | ||
974 | */ | ||
975 | FLAC_API FLAC__uint64 FLAC__stream_encoder_get_total_samples_estimate(const FLAC__StreamEncoder *encoder); | ||
976 | |||
977 | /** Initialize the encoder instance. | ||
978 | * Should be called after FLAC__stream_encoder_new() and | ||
979 | * FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process() | ||
980 | * or FLAC__stream_encoder_process_interleaved(). Will set and return | ||
981 | * the encoder state, which will be FLAC__STREAM_ENCODER_OK if | ||
982 | * initialization succeeded. | ||
983 | * | ||
984 | * The call to FLAC__stream_encoder_init() currently will also immediately | ||
985 | * call the write callback several times, once with the \c fLaC signature, | ||
986 | * and once for each encoded metadata block. | ||
987 | * | ||
988 | * \param encoder An uninitialized encoder instance. | ||
989 | * \assert | ||
990 | * \code encoder != NULL \endcode | ||
991 | * \retval FLAC__StreamEncoderState | ||
992 | * \c FLAC__STREAM_ENCODER_OK if initialization was successful; see | ||
993 | * FLAC__StreamEncoderState for the meanings of other return values. | ||
994 | */ | ||
995 | FLAC_API FLAC__StreamEncoderState FLAC__stream_encoder_init(FLAC__StreamEncoder *encoder); | ||
996 | |||
997 | /** Finish the encoding process. | ||
998 | * Flushes the encoding buffer, releases resources, resets the encoder | ||
999 | * settings to their defaults, and returns the encoder state to | ||
1000 | * FLAC__STREAM_ENCODER_UNINITIALIZED. Note that this can generate | ||
1001 | * one or more write callbacks before returning, and will generate | ||
1002 | * a metadata callback. | ||
1003 | * | ||
1004 | * In the event of a prematurely-terminated encode, it is not strictly | ||
1005 | * necessary to call this immediately before FLAC__stream_encoder_delete() | ||
1006 | * but it is good practice to match every FLAC__stream_encoder_init() | ||
1007 | * with a FLAC__stream_encoder_finish(). | ||
1008 | * | ||
1009 | * \param encoder An uninitialized encoder instance. | ||
1010 | * \assert | ||
1011 | * \code encoder != NULL \endcode | ||
1012 | */ | ||
1013 | FLAC_API void FLAC__stream_encoder_finish(FLAC__StreamEncoder *encoder); | ||
1014 | |||
1015 | /** Submit data for encoding. | ||
1016 | * This version allows you to supply the input data via an array of | ||
1017 | * pointers, each pointer pointing to an array of \a samples samples | ||
1018 | * representing one channel. The samples need not be block-aligned, | ||
1019 | * but each channel should have the same number of samples. | ||
1020 | * | ||
1021 | * \param encoder An initialized encoder instance in the OK state. | ||
1022 | * \param buffer An array of pointers to each channel's signal. | ||
1023 | * \param samples The number of samples in one channel. | ||
1024 | * \assert | ||
1025 | * \code encoder != NULL \endcode | ||
1026 | * \code FLAC__stream_encoder_get_state(encoder) == FLAC__STREAM_ENCODER_OK \endcode | ||
1027 | * \retval FLAC__bool | ||
1028 | * \c true if successful, else \c false; in this case, check the | ||
1029 | * encoder state with FLAC__stream_encoder_get_state() to see what | ||
1030 | * went wrong. | ||
1031 | */ | ||
1032 | FLAC_API FLAC__bool FLAC__stream_encoder_process(FLAC__StreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples); | ||
1033 | |||
1034 | /** Submit data for encoding. | ||
1035 | * This version allows you to supply the input data where the channels | ||
1036 | * are interleaved into a single array (i.e. channel0_sample0, | ||
1037 | * channel1_sample0, ... , channelN_sample0, channel0_sample1, ...). | ||
1038 | * The samples need not be block-aligned but they must be | ||
1039 | * sample-aligned, i.e. the first value should be channel0_sample0 | ||
1040 | * and the last value channelN_sampleM. | ||
1041 | * | ||
1042 | * \param encoder An initialized encoder instance in the OK state. | ||
1043 | * \param buffer An array of channel-interleaved data (see above). | ||
1044 | * \param samples The number of samples in one channel, the same as for | ||
1045 | * FLAC__stream_encoder_process(). For example, if | ||
1046 | * encoding two channels, \c 1000 \a samples corresponds | ||
1047 | * to a \a buffer of 2000 values. | ||
1048 | * \assert | ||
1049 | * \code encoder != NULL \endcode | ||
1050 | * \code FLAC__stream_encoder_get_state(encoder) == FLAC__STREAM_ENCODER_OK \endcode | ||
1051 | * \retval FLAC__bool | ||
1052 | * \c true if successful, else \c false; in this case, check the | ||
1053 | * encoder state with FLAC__stream_encoder_get_state() to see what | ||
1054 | * went wrong. | ||
1055 | */ | ||
1056 | FLAC_API FLAC__bool FLAC__stream_encoder_process_interleaved(FLAC__StreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples); | ||
1057 | |||
1058 | /* \} */ | ||
1059 | |||
1060 | #ifdef __cplusplus | ||
1061 | } | ||
1062 | #endif | ||
1063 | |||
1064 | #endif | ||