more doxygen comments
[flac.git] / include / FLAC / stream_decoder.h
1 /* libFLAC - Free Lossless Audio Codec library
2  * Copyright (C) 2000,2001,2002  Josh Coalson
3  *
4  * This library is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Library General Public
6  * License as published by the Free Software Foundation; either
7  * version 2 of the License, or (at your option) any later version.
8  *
9  * This library is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12  * Library General Public License for more details.
13  *
14  * You should have received a copy of the GNU Library General Public
15  * License along with this library; if not, write to the
16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17  * Boston, MA  02111-1307, USA.
18  */
19
20 #ifndef FLAC__STREAM_DECODER_H
21 #define FLAC__STREAM_DECODER_H
22
23 #include "format.h"
24
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28
29
30 /** \file include/FLAC/stream_decoder.h
31  *
32  *  \brief
33  *  This module contains the functions which implement the stream
34  *  decoder.
35  *
36  *  See the detailed documentation in the
37  *  \link flac_stream_decoder stream decoder \endlink module.
38  */
39
40 /** \defgroup flac_decoder FLAC/ *_decoder.h: decoder interfaces
41  *  \ingroup flac
42  *
43  *  \brief
44  *  This module describes the three decoder layers provided by libFLAC.
45  *
46  * For decoding FLAC streams, libFLAC provides three layers of access.  The
47  * lowest layer is non-seekable stream-level decoding, the next is seekable
48  * stream-level decoding, and the highest layer is file-level decoding.  The
49  * interfaces are described in the \link flac_stream_decoder stream decoder
50  * \endlink, \link flac_seekable_stream_decoder seekable stream decoder
51  * \endlink, and \link flac_file_decoder file decoder \endlink modules
52  * respectively.  Typically you will choose the highest layer that your input
53  * source will support.
54  *
55  * The stream decoder relies on callbacks for all input and output and has no
56  * provisions for seeking.  The seekable stream decoder wraps the stream
57  * decoder and exposes functions for seeking.  However, you must provide
58  * extra callbacks for seek-related operations on your stream, like seek and
59  * tell.  The file decoder wraps the seekable stream decoder and supplies
60  * most of the callbacks internally, simplifying the processing of standard
61  * files.
62  */
63
64 /** \defgroup flac_stream_decoder FLAC/stream_decoder.h: stream decoder interface
65  *  \ingroup flac_decoder
66  *
67  *  \brief
68  *  This module contains the functions which implement the stream
69  *  decoder.
70  *
71  * The basic usage of this decoder is as follows:
72  * - The program creates an instance of a decoder using
73  *   FLAC__stream_decoder_new().
74  * - The program overrides the default settings and sets callbacks for
75  *   reading, writing, error reporting, and metadata reporting using
76  *   FLAC__stream_decoder_set_*() functions.
77  * - The program initializes the instance to validate the settings and
78  *   prepare for decoding using FLAC__stream_decoder_init().
79  * - The program calls the FLAC__stream_decoder_process_*() functions
80  *   to decode data, which subsequently calls the callbacks.
81  * - The program finishes the decoding with FLAC__stream_decoder_finish(),
82  *   which flushes the input and output and resets the decoder to the
83  *   uninitialized state.
84  * - The instance may be used again or deleted with
85  *   FLAC__stream_decoder_delete().
86  *
87  * In more detail, the program will create a new instance by calling
88  * FLAC__stream_decoder_new(), then call FLAC__stream_decoder_set_*()
89  * functions to set the callbacks and client data, and call
90  * FLAC__stream_decoder_init().  The required callbacks are:
91  *
92  * - Read callback - This function will be called when the decoder needs
93  *   more input data.  The address of the buffer to be filled is supplied,
94  *   along with the number of bytes the buffer can hold.  The callback may
95  *   choose to supply less data and modify the byte count but must be careful
96  *   not to overflow the buffer.  The callback then returns a status code
97  *   chosen from FLAC__StreamDecoderReadStatus.
98  * - Write callback - This function will be called when the decoder has
99  *   decoded a single frame of data.  The decoder will pass the frame
100  *   metadata as well as an array of pointers (one for each channel)
101  *   pointing to the decoded audio.
102  * - Metadata callback - This function will be called when the decoder has
103  *   decoded a metadata block.  There will always be one STREAMINFO block
104  *   per stream, followed by zero or more other metadata blocks.  These will
105  *   be supplied by the decoder in the same order as they appear in the
106  *   stream and always before the first audio frame (i.e. write callback).
107  *   The metadata block that is passed in must not be modified, and it
108  *   doesn't live beyond the callback, so you should make a copy of it with
109  *   FLAC__metadata_object_clone() if you will need it elsewhere.  Since
110  *   metadata blocks can potentially be large, by default the decoder only
111  *   calls the metadata callback for the STREAMINFO block; you can instruct
112  *   the decoder to pass or filter other blocks with
113  *   FLAC__stream_decoder_set_metadata_*() calls.
114  * - Error callback - This function will be called whenever an error occurs
115  *   during decoding.
116  *
117  * Once the decoder is initialized, your program will call one of several
118  * functions to start the decoding process:
119  *
120  * - FLAC__stream_decoder_process_single() - Tells the decoder to process at
121  *   most one metadata block or audio frame and return, calling either the
122  *   metadata callback or write callback, respectively, once.  If the decoder
123  *   loses sync it will return with only the error callback being called.
124  * - FLAC__stream_decoder_process_until_end_of_metadata() - Tells the decoder
125  *   to process the stream from the current location and stop upon reaching
126  *   the first audio frame.  The user will get one metadata, write, or error
127  *   callback per metadata block, audio frame, or sync error, respectively.
128  * - FLAC__stream_decoder_process_until_end_of_stream() - Tells the decoder
129  *   to process the stream from the current location until the read callback
130  *   returns FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM or
131  *   FLAC__STREAM_DECODER_READ_STATUS_ABORT.  The user will get one metadata,
132  *   write, or error callback per metadata block, audio frame, or sync error,
133  *   respectively.
134  *
135  * When the decoder has finished decoding (normally or through an abort),
136  * the instance is finished by calling FLAC__stream_decoder_finish(), which
137  * ensures the decoder is in the correct state and frees memory.  Then the
138  * instance may be deleted with FLAC__stream_decoder_delete() or initialized
139  * again to decode another stream.
140  *
141  * Note that the stream decoder has no real concept of stream position, it
142  * just converts data.  To seek within a stream the callbacks have only to
143  * flush the decoder using FLAC__stream_decoder_flush() and start feeding
144  * data from the new position through the read callback.  The seekable
145  * stream decoder does just this.
146  *
147  * The FLAC__stream_decoder_set_metadata_*() functions deserve special
148  * attention.  By default, the decoder only calls the metadata_callback for
149  * the STREAMINFO block.  These functions allow you to tell the decoder
150  * explicitly which blocks to parse and return via the metadata_callback
151  * and/or which to skip.  Use a FLAC__stream_decoder_respond_all(),
152  * FLAC__stream_decoder_ignore() ... or FLAC__stream_decoder_ignore_all(),
153  * FLAC__stream_decoder_respond() ... sequence to exactly specify which
154  * blocks to return.  Remember that some metadata blocks can be big so
155  * filtering out the ones you don't use can reduce the memory requirements
156  * of the decoder.  Also note the special forms
157  * FLAC__stream_decoder_respond_application(id) and 
158  * FLAC__stream_decoder_ignore_application(id) for filtering APPLICATION
159  * blocks based on the application ID.
160  *
161  * STREAMINFO and SEEKTABLE blocks are always parsed and used internally, but
162  * they still can legally be filtered from the metadata_callback.
163  *
164  * \note
165  * The "set" functions may only be called when the decoder is in the
166  * state FLAC__STREAM_DECODER_UNINITIALIZED, i.e. after
167  * FLAC__stream_decoder_new() or FLAC__stream_decoder_finish(), but
168  * before FLAC__stream_decoder_init().  If this is the case they will
169  * return \c true, otherwise \c false.
170  *
171  * \note
172  * FLAC__stream_decoder_finish() resets all settings to the constructor
173  * defaults, including the callbacks.
174  *
175  * \{
176  */
177
178
179 /** State values for a FLAC__StreamDecoder
180  *
181  *  The decoder's state can be obtained by calling FLAC__stream_decoder_get_state().
182  */
183 typedef enum {
184
185         FLAC__STREAM_DECODER_SEARCH_FOR_METADATA = 0,
186         /**< The decoder is ready to search for metadata. */
187
188         FLAC__STREAM_DECODER_READ_METADATA,
189         /**< The decoder is ready to or is in the process of reading metadata. */
190
191         FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC,
192         /**< The decoder is ready to or is in the process of searching for the frame sync code. */
193
194         FLAC__STREAM_DECODER_READ_FRAME,
195         /**< The decoder is ready to or is in the process of reading a frame. */
196
197         FLAC__STREAM_DECODER_END_OF_STREAM,
198         /**< The decoder has reached the end of the stream. */
199
200         FLAC__STREAM_DECODER_ABORTED,
201         /**< The decoder was aborted by the read callback. */
202
203         FLAC__STREAM_DECODER_UNPARSEABLE_STREAM,
204         /**< The decoder encountered reserved fields in use in the stream. */
205
206         FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
207         /**< An error occurred allocating memory. */
208
209         FLAC__STREAM_DECODER_ALREADY_INITIALIZED,
210         /**< FLAC__stream_decoder_init() was called when the decoder was
211          * already initialized, usually because
212          * FLAC__stream_decoder_finish() was not called.
213          */
214
215         FLAC__STREAM_DECODER_INVALID_CALLBACK,
216         /**< FLAC__stream_decoder_init() was called without all callbacks being set. */
217
218         FLAC__STREAM_DECODER_UNINITIALIZED
219         /**< The decoder is in the uninitialized state. */
220
221 } FLAC__StreamDecoderState;
222
223 /** Maps a FLAC__StreamDecoderState to a C string.
224  *
225  *  Using a FLAC__StreamDecoderState as the index to this array
226  *  will give the string equivalent.  The contents should not be modified.
227  */
228 extern const char * const FLAC__StreamDecoderStateString[];
229
230
231 /** Return values for the FLAC__StreamDecoder read callback.
232  */
233 typedef enum {
234
235         FLAC__STREAM_DECODER_READ_STATUS_CONTINUE,
236         /**< The read was OK and decoding can continue. */
237
238         FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM,
239         /**< The read was attempted at the end of the stream. */
240
241         FLAC__STREAM_DECODER_READ_STATUS_ABORT
242         /**< An unrecoverable error occurred.  The decoder will return from the process call. */
243
244 } FLAC__StreamDecoderReadStatus;
245
246 /** Maps a FLAC__StreamDecoderReadStatus to a C string.
247  *
248  *  Using a FLAC__StreamDecoderReadStatus as the index to this array
249  *  will give the string equivalent.  The contents should not be modified.
250  */
251 extern const char * const FLAC__StreamDecoderReadStatusString[];
252
253
254 /** Return values for the FLAC__StreamDecoder write callback.
255  */
256 typedef enum {
257
258         FLAC__STREAM_DECODER_WRITE_STATUS_CONTINUE,
259         /**< The write was OK and decoding can continue. */
260
261         FLAC__STREAM_DECODER_WRITE_STATUS_ABORT
262         /**< An unrecoverable error occurred.  The decoder will return from the process call. */
263
264 } FLAC__StreamDecoderWriteStatus;
265
266 /** Maps a FLAC__StreamDecoderWriteStatus to a C string.
267  *
268  *  Using a FLAC__StreamDecoderWriteStatus as the index to this array
269  *  will give the string equivalent.  The contents should not be modified.
270  */
271 extern const char * const FLAC__StreamDecoderWriteStatusString[];
272
273
274 /** Possible values passed in to the FLAC__StreamDecoder error callback.
275  */
276 typedef enum {
277
278         FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC,
279         /**< An error in the stream caused the decoder to lose synchronization. */
280
281         FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER,
282         /**< The decoder encountered a corrupted frame header. */
283
284         FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH
285         /**< The frame's data did not match the CRC in the footer. */
286
287 } FLAC__StreamDecoderErrorStatus;
288
289 /** Maps a FLAC__StreamDecoderErrorStatus to a C string.
290  *
291  *  Using a FLAC__StreamDecoderErrorStatus as the index to this array
292  *  will give the string equivalent.  The contents should not be modified.
293  */
294 extern const char * const FLAC__StreamDecoderErrorStatusString[];
295
296
297 /***********************************************************************
298  *
299  * class FLAC__StreamDecoder
300  *
301  ***********************************************************************/
302
303 struct FLAC__StreamDecoderProtected;
304 struct FLAC__StreamDecoderPrivate;
305 /** The opaque structure definition for the stream decoder type.
306  *  See the \link flac_stream_decoder stream decoder module \endlink
307  *  for a detailed description.
308  */
309 typedef struct {
310         struct FLAC__StreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
311         struct FLAC__StreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
312 } FLAC__StreamDecoder;
313
314 /** Signature for the read callback.
315  *  See FLAC__stream_decoder_set_read_callback() for more info.
316  *
317  * \param  decoder  The decoder instance calling the callback.
318  * \param  buffer   A pointer to a location for the callee to store
319  *                  data to be decoded.
320  * \param  bytes    A pointer to the size of the buffer.  On entry
321  *                  to the callback, it contains the maximum number
322  *                  of bytes that may be stored in \a buffer.  The
323  *                  callee must set it to the actual number of bytes
324  *                  stored before returning.
325  * \param  client_data  The callee's client data set through
326  *                      FLAC__stream_decoder_set_client_data().
327  * \retval FLAC__StreamDecoderReadStatus
328  *    The callee's return status.
329  */
330 typedef FLAC__StreamDecoderReadStatus (*FLAC__StreamDecoderReadCallback)(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
331
332 /** Signature for the write callback.
333  *  See FLAC__stream_decoder_set_write_callback() for more info.
334  *
335  * \param  decoder  The decoder instance calling the callback.
336  * \param  frame    The description of the decoded frame.  See
337  *                  FLAC__Frame.
338  * \param  buffer   An array of pointers to decoded channels of data.
339  *                  Each pointer will point to an array of signed
340  *                  samples of length \a frame->header.blocksize.
341  *                  Currently, the channel order has no meaning
342  *                  except for stereo streams; in this case channel
343  *                  0 is left and 1 is right.
344  * \param  client_data  The callee's client data set through
345  *                      FLAC__stream_decoder_set_client_data().
346  * \retval FLAC__StreamDecoderWriteStatus
347  *    The callee's return status.
348  */
349 typedef FLAC__StreamDecoderWriteStatus (*FLAC__StreamDecoderWriteCallback)(const FLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
350
351 /** Signature for the metadata callback.
352  *  See FLAC__stream_decoder_set_metadata_callback() for more info.
353  *
354  * \param  decoder  The decoder instance calling the callback.
355  * \param  metadata The decoded metadata block.
356  * \param  client_data  The callee's client data set through
357  *                      FLAC__stream_decoder_set_client_data().
358  */
359 typedef void (*FLAC__StreamDecoderMetadataCallback)(const FLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
360
361 /** Signature for the error callback.
362  *  See FLAC__stream_decoder_set_error_callback() for more info.
363  *
364  * \param  decoder  The decoder instance calling the callback.
365  * \param  status   The error encountered by the decoder.
366  * \param  client_data  The callee's client data set through
367  *                      FLAC__stream_decoder_set_client_data().
368  */
369 typedef void (*FLAC__StreamDecoderErrorCallback)(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
370
371
372 /***********************************************************************
373  *
374  * Class constructor/destructor
375  *
376  ***********************************************************************/
377
378 /** Create a new stream decoder instance.  The instance is created with
379  *  default settings; see the individual FLAC__stream_decoder_set_*()
380  *  functions for each setting's default.
381  *
382  * \retval FLAC__StreamDecoder*
383  *    \c NULL if there was an error allocating memory, else the new instance.
384  */
385 FLAC__StreamDecoder *FLAC__stream_decoder_new();
386
387 /** Free a decoder instance.  Deletes the object pointed to by \a decoder.
388  *
389  * \param decoder  A pointer to an existing decoder.
390  * \assert
391  *    \code decoder != NULL \endcode
392  */
393 void FLAC__stream_decoder_delete(FLAC__StreamDecoder *decoder);
394
395
396 /***********************************************************************
397  *
398  * Public class method prototypes
399  *
400  ***********************************************************************/
401
402 /** Set the read callback.
403  *  The supplied function will be called when the decoder needs more input
404  *  data.  The address of the buffer to be filled is supplied, along with
405  *  the number of bytes the buffer can hold.  The callback may choose to
406  *  supply less data and modify the byte count but must be careful not to
407  *  overflow the buffer.  The callback then returns a status code chosen
408  *  from FLAC__StreamDecoderReadStatus.
409  *
410  * \note
411  * The callback is mandatory and must be set before initialization.
412  *
413  * \default \c NULL
414  * \param  decoder  An decoder instance to set.
415  * \param  value    See above.
416  * \assert
417  *    \code decoder != NULL \endcode
418  *    \code value != NULL \endcode
419  * \retval FLAC__bool
420  *    \c false if the decoder is already initialized, else \c true.
421  */
422 FLAC__bool FLAC__stream_decoder_set_read_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderReadCallback value);
423
424 /** Set the write callback.
425  *  The supplied function will be called when the decoder has decoded a
426  *  single frame of data.  The decoder will pass the frame metadata as
427  *  well as an array of pointers (one for each channel) pointing to the
428  *  decoded audio.
429  *
430  * \note
431  * The callback is mandatory and must be set before initialization.
432  *
433  * \default \c NULL
434  * \param  decoder  An decoder instance to set.
435  * \param  value    See above.
436  * \assert
437  *    \code decoder != NULL \endcode
438  *    \code value != NULL \endcode
439  * \retval FLAC__bool
440  *    \c false if the decoder is already initialized, else \c true.
441  */
442 FLAC__bool FLAC__stream_decoder_set_write_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderWriteCallback value);
443
444 /** Set the metadata callback.
445  *  The supplied function will be called when the decoder has decoded a
446  *  metadata block.  There will always be one STREAMINFO block per stream,
447  *  followed by zero or more other metadata blocks.  These will be supplied
448  *  by the decoder in the same order as they appear in the stream and always
449  *  before the first audio frame (i.e. write callback).  The metadata block
450  *  that is passed in must not be modified, and it doesn't live beyond the
451  *  callback, so you should make a copy of it with
452  *  FLAC__metadata_object_clone() if you will need it elsewhere.  Since
453  *  metadata blocks can potentially be large, by default the decoder only
454  *  calls the metadata callback for the STREAMINFO block; you can instruct
455  *  the decoder to pass or filter other blocks with
456  *  FLAC__stream_decoder_set_metadata_*() calls.
457  *
458  * \note
459  * The callback is mandatory and must be set before initialization.
460  *
461  * \default \c NULL
462  * \param  decoder  An decoder instance to set.
463  * \param  value    See above.
464  * \assert
465  *    \code decoder != NULL \endcode
466  *    \code value != NULL \endcode
467  * \retval FLAC__bool
468  *    \c false if the decoder is already initialized, else \c true.
469  */
470 FLAC__bool FLAC__stream_decoder_set_metadata_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderMetadataCallback value);
471
472 /** Set the error callback.
473  *  The supplied function will be called whenever an error occurs during
474  *  decoding.
475  *
476  * \note
477  * The callback is mandatory and must be set before initialization.
478  *
479  * \default \c NULL
480  * \param  decoder  An decoder instance to set.
481  * \param  value    See above.
482  * \assert
483  *    \code decoder != NULL \endcode
484  *    \code value != NULL \endcode
485  * \retval FLAC__bool
486  *    \c false if the decoder is already initialized, else \c true.
487  */
488 FLAC__bool FLAC__stream_decoder_set_error_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorCallback value);
489
490 /** Set the client data to be passed back to callbacks.
491  *  This value will be supplied to callbacks in their \a client_data
492  *  argument.
493  *
494  * \default \c NULL
495  * \param  decoder  An decoder instance to set.
496  * \param  value    See above.
497  * \assert
498  *    \code decoder != NULL \endcode
499  * \retval FLAC__bool
500  *    \c false if the decoder is already initialized, else \c true.
501  */
502 FLAC__bool FLAC__stream_decoder_set_client_data(FLAC__StreamDecoder *decoder, void *value);
503
504 /** Direct the decoder to pass on all metadata blocks of type \a type.
505  *
506  * \default By default, only the \c STREAMINFO block is returned via the
507  *          metadata callback.
508  * \param  decoder  A decoder instance to set.
509  * \param  type     See above.
510  * \assert
511  *    \code decoder != NULL \endcode
512  *    \a type is valid
513  * \retval FLAC__bool
514  *    \c false if the decoder is already initialized, else \c true.
515  */
516 FLAC__bool FLAC__stream_decoder_set_metadata_respond(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
517
518 /** Direct the decoder to pass on all APPLICATION metadata blocks of the
519  *  given \a id.
520  *
521  * \default By default, only the \c STREAMINFO block is returned via the
522  *          metadata callback.
523  * \param  decoder  A decoder instance to set.
524  * \param  id       See above.
525  * \assert
526  *    \code decoder != NULL \endcode
527  *    \code id != NULL \endcode
528  * \retval FLAC__bool
529  *    \c false if the decoder is already initialized, else \c true.
530  */
531 FLAC__bool FLAC__stream_decoder_set_metadata_respond_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
532
533 /** Direct the decoder to pass on all metadata blocks of any type.
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  * \assert
539  *    \code decoder != NULL \endcode
540  * \retval FLAC__bool
541  *    \c false if the decoder is already initialized, else \c true.
542  */
543 FLAC__bool FLAC__stream_decoder_set_metadata_respond_all(FLAC__StreamDecoder *decoder);
544
545 /** Direct the decoder to filter out all metadata blocks of type \a type.
546  *
547  * \default By default, only the \c STREAMINFO block is returned via the
548  *          metadata callback.
549  * \param  decoder  A decoder instance to set.
550  * \param  type     See above.
551  * \assert
552  *    \code decoder != NULL \endcode
553  *    \a type is valid
554  * \retval FLAC__bool
555  *    \c false if the decoder is already initialized, else \c true.
556  */
557 FLAC__bool FLAC__stream_decoder_set_metadata_ignore(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
558
559 /** Direct the decoder to filter out all APPLICATION metadata blocks of
560  *  the given \a id.
561  *
562  * \default By default, only the \c STREAMINFO block is returned via the
563  *          metadata callback.
564  * \param  decoder  A decoder instance to set.
565  * \param  id       See above.
566  * \assert
567  *    \code decoder != NULL \endcode
568  *    \code id != NULL \endcode
569  * \retval FLAC__bool
570  *    \c false if the decoder is already initialized, else \c true.
571  */
572 FLAC__bool FLAC__stream_decoder_set_metadata_ignore_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
573
574 /** Direct the decoder to filter out all metadata blocks of any type.
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  * \assert
580  *    \code decoder != NULL \endcode
581  * \retval FLAC__bool
582  *    \c false if the decoder is already initialized, else \c true.
583  */
584 FLAC__bool FLAC__stream_decoder_set_metadata_ignore_all(FLAC__StreamDecoder *decoder);
585
586 /** Get the current decoder state.
587  *
588  * \param  decoder  A decoder instance to query.
589  * \assert
590  *    \code decoder != NULL \endcode
591  * \retval FLAC__StreamDecoderState
592  *    The current decoder state.
593  */
594 FLAC__StreamDecoderState FLAC__stream_decoder_get_state(const FLAC__StreamDecoder *decoder);
595
596 /** Get the current number of channels in the stream being decoded.
597  *  Will only be valid after decoding has started and will contain the
598  *  value from the most recently decoded frame header.
599  *
600  * \param  decoder  A decoder instance to query.
601  * \assert
602  *    \code decoder != NULL \endcode
603  * \retval unsigned
604  *    See above.
605  */
606 unsigned FLAC__stream_decoder_get_channels(const FLAC__StreamDecoder *decoder);
607
608 /** Get the current channel assignment in the stream being decoded.
609  *  Will only be valid after decoding has started and will contain the
610  *  value from the most recently decoded frame header.
611  *
612  * \param  decoder  A decoder instance to query.
613  * \assert
614  *    \code decoder != NULL \endcode
615  * \retval FLAC__ChannelAssignment
616  *    See above.
617  */
618 FLAC__ChannelAssignment FLAC__stream_decoder_get_channel_assignment(const FLAC__StreamDecoder *decoder);
619
620 /** Get the current sample resolution 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 unsigned FLAC__stream_decoder_get_bits_per_sample(const FLAC__StreamDecoder *decoder);
631
632 /** Get the current sample rate in Hz of 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 unsigned
640  *    See above.
641  */
642 unsigned FLAC__stream_decoder_get_sample_rate(const FLAC__StreamDecoder *decoder);
643
644 /** Get the current blocksize of 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 unsigned FLAC__stream_decoder_get_blocksize(const FLAC__StreamDecoder *decoder);
655
656 /** Initialize the decoder instance.
657  *  Should be called after FLAC__stream_decoder_new() and
658  *  FLAC__stream_decoder_set_*() but before any of the
659  *  FLAC__stream_decoder_process_*() functions.  Will set and return the
660  *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
661  *  if initialization succeeded.
662  *
663  * \param  decoder  An uninitialized decoder instance.
664  * \assert
665  *    \code decoder != NULL \endcode
666  * \retval FLAC__StreamDecoderState
667  *    \c FLAC__STREAM_DECODER_SEARCH_FOR_MEATADATA if initialization was
668  *    successful; see FLAC__StreamDecoderState for the meanings of other
669  *    return values.
670  */
671 FLAC__StreamDecoderState FLAC__stream_decoder_init(FLAC__StreamDecoder *decoder);
672
673 /** Finish the decoding process.
674  *  Flushes the decoding buffer, releases resources, resets the decoder
675  *  settings to their defaults, and returns the decoder state to
676  *  FLAC__STREAM_DECODER_UNINITIALIZED.
677  *
678  *  In the event of a prematurely-terminated decode, it is not strictly
679  *  necessary to call this immediately before FLAC__stream_decoder_delete()
680  *  but it is good practice to match every FLAC__stream_decoder_init()
681  *  with a FLAC__stream_decoder_finish().
682  *
683  * \param  decoder  An uninitialized decoder instance.
684  * \assert
685  *    \code decoder != NULL \endcode
686  */
687 void FLAC__stream_decoder_finish(FLAC__StreamDecoder *decoder);
688
689 /** Flush the stream input.
690  *  The decoder's input buffer will be cleared and the state set to
691  *  \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC.
692  *
693  * \param  decoder  A decoder instance.
694  * \assert
695  *    \code decoder != NULL \endcode
696  * \retval FLAC__bool
697  *    \c true if successful, else \c false if a memory allocation
698  *    error occurs.
699  */
700 FLAC__bool FLAC__stream_decoder_flush(FLAC__StreamDecoder *decoder);
701
702 /** Reset the decoding process.
703  *  The decoder's input buffer will be cleared and the state set to
704  *  \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.  This is similar to
705  *  FLAC__stream_decoder_finish() except that the settings are
706  *  preserved; there is no need to call FLAC__stream_decoder_init()
707  *  before decoding again.
708  *
709  * \param  decoder  A decoder instance.
710  * \assert
711  *    \code decoder != NULL \endcode
712  * \retval FLAC__bool
713  *    \c true if successful, else \c false if a memory allocation
714  *    error occurs.
715  */
716 FLAC__bool FLAC__stream_decoder_reset(FLAC__StreamDecoder *decoder);
717
718 /** Decode one metadata block or audio frame.
719  *  This version instructs the decoder to decode a either a single metadata
720  *  block or a single frame and stop, unless the callbacks return a fatal
721  *  error or the read callback returns
722  *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
723  *
724  *  As the decoder needs more input it will call the read callback.
725  *  Depending on what was decoded, the metadata or write callback will be
726  *  called with the decoded metadata block or audio frame, unless an error
727  *  occurred.  If the decoder loses sync it will call the error callback
728  *  instead.
729  * 
730  * \param  decoder  An initialized decoder instance in the state
731  *                  \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC.
732  * \assert
733  *    \code decoder != NULL \endcode
734  *    \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC \endcode
735  * \retval FLAC__bool
736  *    \c false if any read or write error occurred (except
737  *    \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
738  *    in any case, check the decoder state with
739  *    FLAC__stream_decoder_get_state() to see what went wrong or to
740  *    check for lost synchronization (a sign of stream corruption).
741  */
742 FLAC__bool FLAC__stream_decoder_process_single(FLAC__StreamDecoder *decoder);
743
744 /** Decode until the end of the metadata.
745  *  This version instructs the decoder to decode from the current position
746  *  and continue until all the metadata has been read, or until the
747  *  callbacks return a fatal error or the read callback returns
748  *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
749  *
750  *  As the decoder needs more input it will call the read callback.
751  *  As each metadata block is decoded, the metadata callback will be called
752  *  with the decoded metadata.  If the decoder loses sync it will call the
753  *  error callback.
754  * 
755  * \param  decoder  An initialized decoder instance in the state
756  *                  \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.
757  * \assert
758  *    \code decoder != NULL \endcode
759  *    \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_METADATA \endcode
760  * \retval FLAC__bool
761  *    \c false if any read or write error occurred (except
762  *    \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
763  *    in any case, check the decoder state with
764  *    FLAC__stream_decoder_get_state() to see what went wrong or to
765  *    check for lost synchronization (a sign of stream corruption).
766  */
767 FLAC__bool FLAC__stream_decoder_process_until_end_of_metadata(FLAC__StreamDecoder *decoder);
768
769 /** Decode until the end of the stream.
770  *  This version instructs the decoder to decode from the current position
771  *  and continue until the end of stream (the read callback returns
772  *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM), or until the
773  *  callbacks return a fatal error.
774  *
775  *  As the decoder needs more input it will call the read callback.
776  *  As each metadata block and frame is decoded, the metadata or write
777  *  callback will be called with the decoded metadata or frame.  If the
778  *  decoder loses sync it will call the error callback.
779  * 
780  * \param  decoder  An initialized decoder instance in the state
781  *                  \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.
782  * \assert
783  *    \code decoder != NULL \endcode
784  *    \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_METADATA \endcode
785  * \retval FLAC__bool
786  *    \c false if any read or write error occurred (except
787  *    \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
788  *    in any case, check the decoder state with
789  *    FLAC__stream_decoder_get_state() to see what went wrong or to
790  *    check for lost synchronization (a sign of stream corruption).
791  */
792 FLAC__bool FLAC__stream_decoder_process_until_end_of_stream(FLAC__StreamDecoder *decoder);
793
794 /* \} */
795
796 #ifdef __cplusplus
797 }
798 #endif
799
800 #endif