stream_decoder.h - vx32 - Local 9vx git repository for patches.
(HTM) git clone git://r-36.net/vx32
(DIR) Log
(DIR) Files
(DIR) Refs
---
stream_decoder.h (36803B)
---
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