fix misspellings in docs
[flac.git] / 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_set_metadata_respond_all(),
153  * FLAC__stream_decoder_set_metadata_ignore() ... or FLAC__stream_decoder_set_metadata_ignore_all(),
154  * FLAC__stream_decoder_set_metadata_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_set_metadata_respond_application(id) and
159  * FLAC__stream_decoder_set_metadata_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