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