d2fb6bb756d10dc670dbc56facb94e5d81db3b03
[flac.git] / include / FLAC / stream_decoder.h
1 /* libFLAC - Free Lossless Audio Codec library
2  * Copyright (C) 2000,2001,2002,2003  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 before returning.
338  * \param  client_data  The callee's client data set through
339  *                      FLAC__stream_decoder_set_client_data().
340  * \retval FLAC__StreamDecoderReadStatus
341  *    The callee's return status.
342  */
343 typedef FLAC__StreamDecoderReadStatus (*FLAC__StreamDecoderReadCallback)(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
344
345 /** Signature for the write callback.
346  *  See FLAC__stream_decoder_set_write_callback() for more info.
347  *
348  * \param  decoder  The decoder instance calling the callback.
349  * \param  frame    The description of the decoded frame.  See
350  *                  FLAC__Frame.
351  * \param  buffer   An array of pointers to decoded channels of data.
352  *                  Each pointer will point to an array of signed
353  *                  samples of length \a frame->header.blocksize.
354  *                  Currently, the channel order has no meaning
355  *                  except for stereo streams; in this case channel
356  *                  0 is left and 1 is right.
357  * \param  client_data  The callee's client data set through
358  *                      FLAC__stream_decoder_set_client_data().
359  * \retval FLAC__StreamDecoderWriteStatus
360  *    The callee's return status.
361  */
362 typedef FLAC__StreamDecoderWriteStatus (*FLAC__StreamDecoderWriteCallback)(const FLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
363
364 /** Signature for the metadata callback.
365  *  See FLAC__stream_decoder_set_metadata_callback() for more info.
366  *
367  * \param  decoder  The decoder instance calling the callback.
368  * \param  metadata The decoded metadata block.
369  * \param  client_data  The callee's client data set through
370  *                      FLAC__stream_decoder_set_client_data().
371  */
372 typedef void (*FLAC__StreamDecoderMetadataCallback)(const FLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
373
374 /** Signature for the error callback.
375  *  See FLAC__stream_decoder_set_error_callback() for more info.
376  *
377  * \param  decoder  The decoder instance calling the callback.
378  * \param  status   The error encountered by the decoder.
379  * \param  client_data  The callee's client data set through
380  *                      FLAC__stream_decoder_set_client_data().
381  */
382 typedef void (*FLAC__StreamDecoderErrorCallback)(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
383
384
385 /***********************************************************************
386  *
387  * Class constructor/destructor
388  *
389  ***********************************************************************/
390
391 /** Create a new stream decoder instance.  The instance is created with
392  *  default settings; see the individual FLAC__stream_decoder_set_*()
393  *  functions for each setting's default.
394  *
395  * \retval FLAC__StreamDecoder*
396  *    \c NULL if there was an error allocating memory, else the new instance.
397  */
398 FLAC_API FLAC__StreamDecoder *FLAC__stream_decoder_new();
399
400 /** Free a decoder instance.  Deletes the object pointed to by \a decoder.
401  *
402  * \param decoder  A pointer to an existing decoder.
403  * \assert
404  *    \code decoder != NULL \endcode
405  */
406 FLAC_API void FLAC__stream_decoder_delete(FLAC__StreamDecoder *decoder);
407
408
409 /***********************************************************************
410  *
411  * Public class method prototypes
412  *
413  ***********************************************************************/
414
415 /** Set the read callback.
416  *  The supplied function will be called when the decoder needs more input
417  *  data.  The address of the buffer to be filled is supplied, along with
418  *  the number of bytes the buffer can hold.  The callback may choose to
419  *  supply less data and modify the byte count but must be careful not to
420  *  overflow the buffer.  The callback then returns a status code chosen
421  *  from FLAC__StreamDecoderReadStatus.
422  *
423  * \note
424  * The callback is mandatory and must be set before initialization.
425  *
426  * \default \c NULL
427  * \param  decoder  A decoder instance to set.
428  * \param  value    See above.
429  * \assert
430  *    \code decoder != NULL \endcode
431  *    \code value != NULL \endcode
432  * \retval FLAC__bool
433  *    \c false if the decoder is already initialized, else \c true.
434  */
435 FLAC_API FLAC__bool FLAC__stream_decoder_set_read_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderReadCallback value);
436
437 /** Set the write callback.
438  *  The supplied function will be called when the decoder has decoded a
439  *  single frame of data.  The decoder will pass the frame metadata as
440  *  well as an array of pointers (one for each channel) pointing to the
441  *  decoded audio.
442  *
443  * \note
444  * The callback is mandatory and must be set before initialization.
445  *
446  * \default \c NULL
447  * \param  decoder  A decoder instance to set.
448  * \param  value    See above.
449  * \assert
450  *    \code decoder != NULL \endcode
451  *    \code value != NULL \endcode
452  * \retval FLAC__bool
453  *    \c false if the decoder is already initialized, else \c true.
454  */
455 FLAC_API FLAC__bool FLAC__stream_decoder_set_write_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderWriteCallback value);
456
457 /** Set the metadata callback.
458  *  The supplied function will be called when the decoder has decoded a metadata
459  *  block.  In a valid FLAC file there will always be one STREAMINFO block,
460  *  followed by zero or more other metadata blocks.  These will be supplied
461  *  by the decoder in the same order as they appear in the stream and always
462  *  before the first audio frame (i.e. write callback).  The metadata block
463  *  that is passed in must not be modified, and it doesn't live beyond the
464  *  callback, so you should make a copy of it with
465  *  FLAC__metadata_object_clone() if you will need it elsewhere.  Since
466  *  metadata blocks can potentially be large, by default the decoder only
467  *  calls the metadata callback for the STREAMINFO block; you can instruct
468  *  the decoder to pass or filter other blocks with
469  *  FLAC__stream_decoder_set_metadata_*() calls.
470  *
471  * \note
472  * The callback is mandatory and must be set before initialization.
473  *
474  * \default \c NULL
475  * \param  decoder  A decoder instance to set.
476  * \param  value    See above.
477  * \assert
478  *    \code decoder != NULL \endcode
479  *    \code value != NULL \endcode
480  * \retval FLAC__bool
481  *    \c false if the decoder is already initialized, else \c true.
482  */
483 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderMetadataCallback value);
484
485 /** Set the error callback.
486  *  The supplied function will be called whenever an error occurs during
487  *  decoding.
488  *
489  * \note
490  * The callback is mandatory and must be set before initialization.
491  *
492  * \default \c NULL
493  * \param  decoder  A decoder instance to set.
494  * \param  value    See above.
495  * \assert
496  *    \code decoder != NULL \endcode
497  *    \code value != NULL \endcode
498  * \retval FLAC__bool
499  *    \c false if the decoder is already initialized, else \c true.
500  */
501 FLAC_API FLAC__bool FLAC__stream_decoder_set_error_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorCallback value);
502
503 /** Set the client data to be passed back to callbacks.
504  *  This value will be supplied to callbacks in their \a client_data
505  *  argument.
506  *
507  * \default \c NULL
508  * \param  decoder  A decoder instance to set.
509  * \param  value    See above.
510  * \assert
511  *    \code decoder != NULL \endcode
512  * \retval FLAC__bool
513  *    \c false if the decoder is already initialized, else \c true.
514  */
515 FLAC_API FLAC__bool FLAC__stream_decoder_set_client_data(FLAC__StreamDecoder *decoder, void *value);
516
517 /** Direct the decoder to pass on all metadata blocks of type \a type.
518  *
519  * \default By default, only the \c STREAMINFO block is returned via the
520  *          metadata callback.
521  * \param  decoder  A decoder instance to set.
522  * \param  type     See above.
523  * \assert
524  *    \code decoder != NULL \endcode
525  *    \a type is valid
526  * \retval FLAC__bool
527  *    \c false if the decoder is already initialized, else \c true.
528  */
529 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
530
531 /** Direct the decoder to pass on all APPLICATION metadata blocks of the
532  *  given \a id.
533  *
534  * \default By default, only the \c STREAMINFO block is returned via the
535  *          metadata callback.
536  * \param  decoder  A decoder instance to set.
537  * \param  id       See above.
538  * \assert
539  *    \code decoder != NULL \endcode
540  *    \code id != NULL \endcode
541  * \retval FLAC__bool
542  *    \c false if the decoder is already initialized, else \c true.
543  */
544 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
545
546 /** Direct the decoder to pass on all metadata blocks of any type.
547  *
548  * \default By default, only the \c STREAMINFO block is returned via the
549  *          metadata callback.
550  * \param  decoder  A decoder instance to set.
551  * \assert
552  *    \code decoder != NULL \endcode
553  * \retval FLAC__bool
554  *    \c false if the decoder is already initialized, else \c true.
555  */
556 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_all(FLAC__StreamDecoder *decoder);
557
558 /** Direct the decoder to filter out all metadata blocks of type \a type.
559  *
560  * \default By default, only the \c STREAMINFO block is returned via the
561  *          metadata callback.
562  * \param  decoder  A decoder instance to set.
563  * \param  type     See above.
564  * \assert
565  *    \code decoder != NULL \endcode
566  *    \a type is valid
567  * \retval FLAC__bool
568  *    \c false if the decoder is already initialized, else \c true.
569  */
570 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
571
572 /** Direct the decoder to filter out all APPLICATION metadata blocks of
573  *  the given \a id.
574  *
575  * \default By default, only the \c STREAMINFO block is returned via the
576  *          metadata callback.
577  * \param  decoder  A decoder instance to set.
578  * \param  id       See above.
579  * \assert
580  *    \code decoder != NULL \endcode
581  *    \code id != NULL \endcode
582  * \retval FLAC__bool
583  *    \c false if the decoder is already initialized, else \c true.
584  */
585 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
586
587 /** Direct the decoder to filter out all metadata blocks of any type.
588  *
589  * \default By default, only the \c STREAMINFO block is returned via the
590  *          metadata callback.
591  * \param  decoder  A decoder instance to set.
592  * \assert
593  *    \code decoder != NULL \endcode
594  * \retval FLAC__bool
595  *    \c false if the decoder is already initialized, else \c true.
596  */
597 FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_all(FLAC__StreamDecoder *decoder);
598
599 /** Get the current decoder state.
600  *
601  * \param  decoder  A decoder instance to query.
602  * \assert
603  *    \code decoder != NULL \endcode
604  * \retval FLAC__StreamDecoderState
605  *    The current decoder state.
606  */
607 FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_get_state(const FLAC__StreamDecoder *decoder);
608
609 /** Get the current number of channels in the stream being decoded.
610  *  Will only be valid after decoding has started and will contain the
611  *  value from the most recently decoded frame header.
612  *
613  * \param  decoder  A decoder instance to query.
614  * \assert
615  *    \code decoder != NULL \endcode
616  * \retval unsigned
617  *    See above.
618  */
619 FLAC_API unsigned FLAC__stream_decoder_get_channels(const FLAC__StreamDecoder *decoder);
620
621 /** Get the current channel assignment in the stream being decoded.
622  *  Will only be valid after decoding has started and will contain the
623  *  value from the most recently decoded frame header.
624  *
625  * \param  decoder  A decoder instance to query.
626  * \assert
627  *    \code decoder != NULL \endcode
628  * \retval FLAC__ChannelAssignment
629  *    See above.
630  */
631 FLAC_API FLAC__ChannelAssignment FLAC__stream_decoder_get_channel_assignment(const FLAC__StreamDecoder *decoder);
632
633 /** Get the current sample resolution in the stream being decoded.
634  *  Will only be valid after decoding has started and will contain the
635  *  value from the most recently decoded frame header.
636  *
637  * \param  decoder  A decoder instance to query.
638  * \assert
639  *    \code decoder != NULL \endcode
640  * \retval unsigned
641  *    See above.
642  */
643 FLAC_API unsigned FLAC__stream_decoder_get_bits_per_sample(const FLAC__StreamDecoder *decoder);
644
645 /** Get the current sample rate in Hz of the stream being decoded.
646  *  Will only be valid after decoding has started and will contain the
647  *  value from the most recently decoded frame header.
648  *
649  * \param  decoder  A decoder instance to query.
650  * \assert
651  *    \code decoder != NULL \endcode
652  * \retval unsigned
653  *    See above.
654  */
655 FLAC_API unsigned FLAC__stream_decoder_get_sample_rate(const FLAC__StreamDecoder *decoder);
656
657 /** Get the current blocksize of the stream being decoded.
658  *  Will only be valid after decoding has started and will contain the
659  *  value from the most recently decoded frame header.
660  *
661  * \param  decoder  A decoder instance to query.
662  * \assert
663  *    \code decoder != NULL \endcode
664  * \retval unsigned
665  *    See above.
666  */
667 FLAC_API unsigned FLAC__stream_decoder_get_blocksize(const FLAC__StreamDecoder *decoder);
668
669 /** Initialize the decoder instance.
670  *  Should be called after FLAC__stream_decoder_new() and
671  *  FLAC__stream_decoder_set_*() but before any of the
672  *  FLAC__stream_decoder_process_*() functions.  Will set and return the
673  *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
674  *  if initialization succeeded.
675  *
676  * \param  decoder  An uninitialized decoder instance.
677  * \assert
678  *    \code decoder != NULL \endcode
679  * \retval FLAC__StreamDecoderState
680  *    \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA if initialization was
681  *    successful; see FLAC__StreamDecoderState for the meanings of other
682  *    return values.
683  */
684 FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_init(FLAC__StreamDecoder *decoder);
685
686 /** Finish the decoding process.
687  *  Flushes the decoding buffer, releases resources, resets the decoder
688  *  settings to their defaults, and returns the decoder state to
689  *  FLAC__STREAM_DECODER_UNINITIALIZED.
690  *
691  *  In the event of a prematurely-terminated decode, it is not strictly
692  *  necessary to call this immediately before FLAC__stream_decoder_delete()
693  *  but it is good practice to match every FLAC__stream_decoder_init()
694  *  with a FLAC__stream_decoder_finish().
695  *
696  * \param  decoder  An uninitialized decoder instance.
697  * \assert
698  *    \code decoder != NULL \endcode
699  */
700 FLAC_API void FLAC__stream_decoder_finish(FLAC__StreamDecoder *decoder);
701
702 /** Flush the stream input.
703  *  The decoder's input buffer will be cleared and the state set to
704  *  \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC.
705  *
706  * \param  decoder  A decoder instance.
707  * \assert
708  *    \code decoder != NULL \endcode
709  * \retval FLAC__bool
710  *    \c true if successful, else \c false if a memory allocation
711  *    error occurs.
712  */
713 FLAC_API FLAC__bool FLAC__stream_decoder_flush(FLAC__StreamDecoder *decoder);
714
715 /** Reset the decoding process.
716  *  The decoder's input buffer will be cleared and the state set to
717  *  \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.  This is similar to
718  *  FLAC__stream_decoder_finish() except that the settings are
719  *  preserved; there is no need to call FLAC__stream_decoder_init()
720  *  before decoding again.
721  *
722  * \param  decoder  A decoder instance.
723  * \assert
724  *    \code decoder != NULL \endcode
725  * \retval FLAC__bool
726  *    \c true if successful, else \c false if a memory allocation
727  *    error occurs.
728  */
729 FLAC_API FLAC__bool FLAC__stream_decoder_reset(FLAC__StreamDecoder *decoder);
730
731 /** Decode one metadata block or audio frame.
732  *  This version instructs the decoder to decode a either a single metadata
733  *  block or a single frame and stop, unless the callbacks return a fatal
734  *  error or the read callback returns
735  *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
736  *
737  *  As the decoder needs more input it will call the read callback.
738  *  Depending on what was decoded, the metadata or write callback will be
739  *  called with the decoded metadata block or audio frame, unless an error
740  *  occurred.  If the decoder loses sync it will call the error callback
741  *  instead.
742  *
743  * \param  decoder  An initialized decoder instance in the state
744  *                  \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC.
745  * \assert
746  *    \code decoder != NULL \endcode
747  *    \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC \endcode
748  * \retval FLAC__bool
749  *    \c false if any read or write error occurred (except
750  *    \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
751  *    in any case, check the decoder state with
752  *    FLAC__stream_decoder_get_state() to see what went wrong or to
753  *    check for lost synchronization (a sign of stream corruption).
754  */
755 FLAC_API FLAC__bool FLAC__stream_decoder_process_single(FLAC__StreamDecoder *decoder);
756
757 /** Decode until the end of the metadata.
758  *  This version instructs the decoder to decode from the current position
759  *  and continue until all the metadata has been read, or until the
760  *  callbacks return a fatal error or the read callback returns
761  *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
762  *
763  *  As the decoder needs more input it will call the read callback.
764  *  As each metadata block is decoded, the metadata callback will be called
765  *  with the decoded metadata.  If the decoder loses sync it will call the
766  *  error callback.
767  *
768  * \param  decoder  An initialized decoder instance in the state
769  *                  \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.
770  * \assert
771  *    \code decoder != NULL \endcode
772  *    \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_METADATA \endcode
773  * \retval FLAC__bool
774  *    \c false if any read or write error occurred (except
775  *    \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
776  *    in any case, check the decoder state with
777  *    FLAC__stream_decoder_get_state() to see what went wrong or to
778  *    check for lost synchronization (a sign of stream corruption).
779  */
780 FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_metadata(FLAC__StreamDecoder *decoder);
781
782 /** Decode until the end of the stream.
783  *  This version instructs the decoder to decode from the current position
784  *  and continue until the end of stream (the read callback returns
785  *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM), or until the
786  *  callbacks return a fatal error.
787  *
788  *  As the decoder needs more input it will call the read callback.
789  *  As each metadata block and frame is decoded, the metadata or write
790  *  callback will be called with the decoded metadata or frame.  If the
791  *  decoder loses sync it will call the error callback.
792  *
793  * \param  decoder  An initialized decoder instance in the state
794  *                  \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.
795  * \assert
796  *    \code decoder != NULL \endcode
797  *    \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_METADATA \endcode
798  * \retval FLAC__bool
799  *    \c false if any read or write error occurred (except
800  *    \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
801  *    in any case, check the decoder state with
802  *    FLAC__stream_decoder_get_state() to see what went wrong or to
803  *    check for lost synchronization (a sign of stream corruption).
804  */
805 FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_stream(FLAC__StreamDecoder *decoder);
806
807 /* \} */
808
809 #ifdef __cplusplus
810 }
811 #endif
812
813 #endif