diff options
Diffstat (limited to 'apps/codecs/libFLAC/include/FLAC/stream_decoder.h')
-rw-r--r-- | apps/codecs/libFLAC/include/FLAC/stream_decoder.h | 873 |
1 files changed, 873 insertions, 0 deletions
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 | ||