add callback.h
[flac.git] / include / FLAC / stream_decoder.h
1 /* libFLAC - Free Lossless Audio Codec library
2  * Copyright (C) 2000,2001,2002,2003,2004  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  * \param  decoder  An initialized decoder instance in the state
755  *                  \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC.
756  * \assert
757  *    \code decoder != NULL \endcode
758  *    \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC \endcode
759  * \retval FLAC__bool
760  *    \c false if any read or write error occurred (except
761  *    \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
762  *    in any case, check the decoder state with
763  *    FLAC__stream_decoder_get_state() to see what went wrong or to
764  *    check for lost synchronization (a sign of stream corruption).
765  */
766 FLAC_API FLAC__bool FLAC__stream_decoder_process_single(FLAC__StreamDecoder *decoder);
767
768 /** Decode until the end of the metadata.
769  *  This version instructs the decoder to decode from the current position
770  *  and continue until all the metadata has been read, or until the
771  *  callbacks return a fatal error or the read callback returns
772  *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
773  *
774  *  As the decoder needs more input it will call the read callback.
775  *  As each metadata block is decoded, the metadata callback will be called
776  *  with the decoded metadata.  If the decoder loses sync it will call the
777  *  error callback.
778  *
779  * \param  decoder  An initialized decoder instance in the state
780  *                  \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.
781  * \assert
782  *    \code decoder != NULL \endcode
783  *    \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_METADATA \endcode
784  * \retval FLAC__bool
785  *    \c false if any read or write error occurred (except
786  *    \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
787  *    in any case, check the decoder state with
788  *    FLAC__stream_decoder_get_state() to see what went wrong or to
789  *    check for lost synchronization (a sign of stream corruption).
790  */
791 FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_metadata(FLAC__StreamDecoder *decoder);
792
793 /** Decode until the end of the stream.
794  *  This version instructs the decoder to decode from the current position
795  *  and continue until the end of stream (the read callback returns
796  *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM), or until the
797  *  callbacks return a fatal error.
798  *
799  *  As the decoder needs more input it will call the read callback.
800  *  As each metadata block and frame is decoded, the metadata or write
801  *  callback will be called with the decoded metadata or frame.  If the
802  *  decoder loses sync it will call the error callback.
803  *
804  * \param  decoder  An initialized decoder instance in the state
805  *                  \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.
806  * \assert
807  *    \code decoder != NULL \endcode
808  *    \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_METADATA \endcode
809  * \retval FLAC__bool
810  *    \c false if any read or write error occurred (except
811  *    \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
812  *    in any case, check the decoder state with
813  *    FLAC__stream_decoder_get_state() to see what went wrong or to
814  *    check for lost synchronization (a sign of stream corruption).
815  */
816 FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_stream(FLAC__StreamDecoder *decoder);
817
818 /* \} */
819
820 #ifdef __cplusplus
821 }
822 #endif
823
824 #endif