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