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