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.  In a valid FLAC file there will always be
 104  *   one STREAMINFO block, followed by zero or more other metadata
 105  *   blocks.  These will be supplied by the decoder in the same order as
 106  *   they appear in the stream and always before the first audio frame
 107  *   (i.e. write callback).  The metadata block that is passed in must not
 108  *   be modified, and it doesn't live beyond the callback, so you should
 109  *   make a copy of it with FLAC__metadata_object_clone() if you will need
 110  *   it elsewhere.  Since metadata blocks can potentially be large, by
 111  *   default the decoder only calls the metadata callback for the STREAMINFO
 112  *   block; you can instruct 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  A 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  A 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 metadata
 446  *  block.  In a valid FLAC file there will always be one STREAMINFO block,
 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  A 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  A 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  A 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