stream_decoder.h 35.9 KB
Newer Older
1
/* libFLAC - Free Lossless Audio Codec library
Josh Coalson's avatar
Josh Coalson committed
2
 * Copyright (C) 2000,2001,2002,2003,2004  Josh Coalson
Josh Coalson's avatar
Josh Coalson committed
3
 *
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * - Redistributions of source code must retain the above copyright
 * notice, this list of conditions and the following disclaimer.
 *
 * - Redistributions in binary form must reproduce the above copyright
 * notice, this list of conditions and the following disclaimer in the
 * documentation and/or other materials provided with the distribution.
 *
 * - Neither the name of the Xiph.org Foundation nor the names of its
 * contributors may be used to endorse or promote products derived from
 * this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Josh Coalson's avatar
Josh Coalson committed
30
31
32
33
34
 */

#ifndef FLAC__STREAM_DECODER_H
#define FLAC__STREAM_DECODER_H

35
#include "export.h"
Josh Coalson's avatar
Josh Coalson committed
36
37
#include "format.h"

38
39
40
41
42
#ifdef __cplusplus
extern "C" {
#endif


Josh Coalson's avatar
Josh Coalson committed
43
44
45
46
47
48
49
50
51
52
/** \file include/FLAC/stream_decoder.h
 *
 *  \brief
 *  This module contains the functions which implement the stream
 *  decoder.
 *
 *  See the detailed documentation in the
 *  \link flac_stream_decoder stream decoder \endlink module.
 */

Josh Coalson's avatar
Josh Coalson committed
53
/** \defgroup flac_decoder FLAC/ *_decoder.h: decoder interfaces
Josh Coalson's avatar
Josh Coalson committed
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
 *  \ingroup flac
 *
 *  \brief
 *  This module describes the three decoder layers provided by libFLAC.
 *
 * For decoding FLAC streams, libFLAC provides three layers of access.  The
 * lowest layer is non-seekable stream-level decoding, the next is seekable
 * stream-level decoding, and the highest layer is file-level decoding.  The
 * interfaces are described in the \link flac_stream_decoder stream decoder
 * \endlink, \link flac_seekable_stream_decoder seekable stream decoder
 * \endlink, and \link flac_file_decoder file decoder \endlink modules
 * respectively.  Typically you will choose the highest layer that your input
 * source will support.
 *
 * The stream decoder relies on callbacks for all input and output and has no
 * provisions for seeking.  The seekable stream decoder wraps the stream
 * decoder and exposes functions for seeking.  However, you must provide
 * extra callbacks for seek-related operations on your stream, like seek and
 * tell.  The file decoder wraps the seekable stream decoder and supplies
 * most of the callbacks internally, simplifying the processing of standard
 * files.
 */

/** \defgroup flac_stream_decoder FLAC/stream_decoder.h: stream decoder interface
 *  \ingroup flac_decoder
 *
 *  \brief
 *  This module contains the functions which implement the stream
 *  decoder.
 *
 * The basic usage of this decoder is as follows:
 * - The program creates an instance of a decoder using
 *   FLAC__stream_decoder_new().
 * - The program overrides the default settings and sets callbacks for
 *   reading, writing, error reporting, and metadata reporting using
 *   FLAC__stream_decoder_set_*() functions.
 * - The program initializes the instance to validate the settings and
 *   prepare for decoding using FLAC__stream_decoder_init().
 * - The program calls the FLAC__stream_decoder_process_*() functions
 *   to decode data, which subsequently calls the callbacks.
 * - The program finishes the decoding with FLAC__stream_decoder_finish(),
 *   which flushes the input and output and resets the decoder to the
 *   uninitialized state.
 * - The instance may be used again or deleted with
 *   FLAC__stream_decoder_delete().
 *
 * In more detail, the program will create a new instance by calling
 * FLAC__stream_decoder_new(), then call FLAC__stream_decoder_set_*()
 * functions to set the callbacks and client data, and call
 * FLAC__stream_decoder_init().  The required callbacks are:
 *
 * - Read callback - This function will be called when the decoder needs
 *   more input data.  The address of the buffer to be filled is supplied,
 *   along with the number of bytes the buffer can hold.  The callback may
 *   choose to supply less data and modify the byte count but must be careful
 *   not to overflow the buffer.  The callback then returns a status code
 *   chosen from FLAC__StreamDecoderReadStatus.
 * - Write callback - This function will be called when the decoder has
 *   decoded a single frame of data.  The decoder will pass the frame
 *   metadata as well as an array of pointers (one for each channel)
 *   pointing to the decoded audio.
 * - Metadata callback - This function will be called when the decoder has
Josh Coalson's avatar
Josh Coalson committed
116
117
118
119
120
121
122
123
124
125
 *   decoded a metadata block.  In a valid FLAC file there will always be
 *   one STREAMINFO block, followed by zero or more other metadata
 *   blocks.  These will be supplied by the decoder in the same order as
 *   they appear in the stream and always before the first audio frame
 *   (i.e. write callback).  The metadata block that is passed in must not
 *   be modified, and it doesn't live beyond the callback, so you should
 *   make a copy of it with FLAC__metadata_object_clone() if you will need
 *   it elsewhere.  Since metadata blocks can potentially be large, by
 *   default the decoder only calls the metadata callback for the STREAMINFO
 *   block; you can instruct the decoder to pass or filter other blocks with
Josh Coalson's avatar
Josh Coalson committed
126
127
128
129
130
131
132
 *   FLAC__stream_decoder_set_metadata_*() calls.
 * - Error callback - This function will be called whenever an error occurs
 *   during decoding.
 *
 * Once the decoder is initialized, your program will call one of several
 * functions to start the decoding process:
 *
Josh Coalson's avatar
Josh Coalson committed
133
134
135
136
137
138
139
140
141
142
 * - FLAC__stream_decoder_process_single() - Tells the decoder to process at
 *   most one metadata block or audio frame and return, calling either the
 *   metadata callback or write callback, respectively, once.  If the decoder
 *   loses sync it will return with only the error callback being called.
 * - FLAC__stream_decoder_process_until_end_of_metadata() - Tells the decoder
 *   to process the stream from the current location and stop upon reaching
 *   the first audio frame.  The user will get one metadata, write, or error
 *   callback per metadata block, audio frame, or sync error, respectively.
 * - FLAC__stream_decoder_process_until_end_of_stream() - Tells the decoder
 *   to process the stream from the current location until the read callback
Josh Coalson's avatar
Josh Coalson committed
143
 *   returns FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM or
Josh Coalson's avatar
Josh Coalson committed
144
145
146
 *   FLAC__STREAM_DECODER_READ_STATUS_ABORT.  The user will get one metadata,
 *   write, or error callback per metadata block, audio frame, or sync error,
 *   respectively.
Josh Coalson's avatar
Josh Coalson committed
147
148
149
150
151
152
153
154
155
156
157
158
159
 *
 * When the decoder has finished decoding (normally or through an abort),
 * the instance is finished by calling FLAC__stream_decoder_finish(), which
 * ensures the decoder is in the correct state and frees memory.  Then the
 * instance may be deleted with FLAC__stream_decoder_delete() or initialized
 * again to decode another stream.
 *
 * Note that the stream decoder has no real concept of stream position, it
 * just converts data.  To seek within a stream the callbacks have only to
 * flush the decoder using FLAC__stream_decoder_flush() and start feeding
 * data from the new position through the read callback.  The seekable
 * stream decoder does just this.
 *
Josh Coalson's avatar
Josh Coalson committed
160
161
162
163
 * The FLAC__stream_decoder_set_metadata_*() functions deserve special
 * attention.  By default, the decoder only calls the metadata_callback for
 * the STREAMINFO block.  These functions allow you to tell the decoder
 * explicitly which blocks to parse and return via the metadata_callback
Josh Coalson's avatar
Josh Coalson committed
164
165
166
 * and/or which to skip.  Use a FLAC__stream_decoder_set_metadata_respond_all(),
 * FLAC__stream_decoder_set_metadata_ignore() ... or FLAC__stream_decoder_set_metadata_ignore_all(),
 * FLAC__stream_decoder_set_metadata_respond() ... sequence to exactly specify which
Josh Coalson's avatar
Josh Coalson committed
167
168
169
 * blocks to return.  Remember that some metadata blocks can be big so
 * filtering out the ones you don't use can reduce the memory requirements
 * of the decoder.  Also note the special forms
Josh Coalson's avatar
Josh Coalson committed
170
171
 * FLAC__stream_decoder_set_metadata_respond_application(id) and
 * FLAC__stream_decoder_set_metadata_ignore_application(id) for filtering APPLICATION
Josh Coalson's avatar
Josh Coalson committed
172
173
174
175
176
 * blocks based on the application ID.
 *
 * STREAMINFO and SEEKTABLE blocks are always parsed and used internally, but
 * they still can legally be filtered from the metadata_callback.
 *
Josh Coalson's avatar
Josh Coalson committed
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
 * \note
 * The "set" functions may only be called when the decoder is in the
 * state FLAC__STREAM_DECODER_UNINITIALIZED, i.e. after
 * FLAC__stream_decoder_new() or FLAC__stream_decoder_finish(), but
 * before FLAC__stream_decoder_init().  If this is the case they will
 * return \c true, otherwise \c false.
 *
 * \note
 * FLAC__stream_decoder_finish() resets all settings to the constructor
 * defaults, including the callbacks.
 *
 * \{
 */


/** State values for a FLAC__StreamDecoder
 *
 *  The decoder's state can be obtained by calling FLAC__stream_decoder_get_state().
 */
Josh Coalson's avatar
Josh Coalson committed
196
typedef enum {
Josh Coalson's avatar
Josh Coalson committed
197

Josh Coalson's avatar
Josh Coalson committed
198
	FLAC__STREAM_DECODER_SEARCH_FOR_METADATA = 0,
Josh Coalson's avatar
Josh Coalson committed
199
200
	/**< The decoder is ready to search for metadata. */

Josh Coalson's avatar
Josh Coalson committed
201
	FLAC__STREAM_DECODER_READ_METADATA,
Josh Coalson's avatar
Josh Coalson committed
202
203
	/**< The decoder is ready to or is in the process of reading metadata. */

Josh Coalson's avatar
Josh Coalson committed
204
	FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC,
Josh Coalson's avatar
Josh Coalson committed
205
206
	/**< The decoder is ready to or is in the process of searching for the frame sync code. */

Josh Coalson's avatar
Josh Coalson committed
207
	FLAC__STREAM_DECODER_READ_FRAME,
Josh Coalson's avatar
Josh Coalson committed
208
209
	/**< The decoder is ready to or is in the process of reading a frame. */

Josh Coalson's avatar
Josh Coalson committed
210
	FLAC__STREAM_DECODER_END_OF_STREAM,
Josh Coalson's avatar
Josh Coalson committed
211
212
	/**< The decoder has reached the end of the stream. */

Josh Coalson's avatar
Josh Coalson committed
213
	FLAC__STREAM_DECODER_ABORTED,
Josh Coalson's avatar
Josh Coalson committed
214
215
	/**< The decoder was aborted by the read callback. */

Josh Coalson's avatar
Josh Coalson committed
216
	FLAC__STREAM_DECODER_UNPARSEABLE_STREAM,
Josh Coalson's avatar
Josh Coalson committed
217
218
	/**< The decoder encountered reserved fields in use in the stream. */

Josh Coalson's avatar
Josh Coalson committed
219
	FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
Josh Coalson's avatar
Josh Coalson committed
220
221
	/**< An error occurred allocating memory. */

222
	FLAC__STREAM_DECODER_ALREADY_INITIALIZED,
Josh Coalson's avatar
Josh Coalson committed
223
224
225
226
227
	/**< FLAC__stream_decoder_init() was called when the decoder was
	 * already initialized, usually because
	 * FLAC__stream_decoder_finish() was not called.
	 */

228
	FLAC__STREAM_DECODER_INVALID_CALLBACK,
Josh Coalson's avatar
Josh Coalson committed
229
230
	/**< FLAC__stream_decoder_init() was called without all callbacks being set. */

Josh Coalson's avatar
Josh Coalson committed
231
	FLAC__STREAM_DECODER_UNINITIALIZED
Josh Coalson's avatar
Josh Coalson committed
232
233
	/**< The decoder is in the uninitialized state. */

Josh Coalson's avatar
Josh Coalson committed
234
} FLAC__StreamDecoderState;
Josh Coalson's avatar
Josh Coalson committed
235
236
237
238
239
240

/** Maps a FLAC__StreamDecoderState to a C string.
 *
 *  Using a FLAC__StreamDecoderState as the index to this array
 *  will give the string equivalent.  The contents should not be modified.
 */
241
extern FLAC_API const char * const FLAC__StreamDecoderStateString[];
Josh Coalson's avatar
Josh Coalson committed
242

Josh Coalson's avatar
Josh Coalson committed
243
244
245

/** Return values for the FLAC__StreamDecoder read callback.
 */
Josh Coalson's avatar
Josh Coalson committed
246
typedef enum {
Josh Coalson's avatar
Josh Coalson committed
247

Josh Coalson's avatar
Josh Coalson committed
248
	FLAC__STREAM_DECODER_READ_STATUS_CONTINUE,
Josh Coalson's avatar
Josh Coalson committed
249
250
	/**< The read was OK and decoding can continue. */

Josh Coalson's avatar
Josh Coalson committed
251
	FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM,
Josh Coalson's avatar
Josh Coalson committed
252
253
	/**< The read was attempted at the end of the stream. */

Josh Coalson's avatar
Josh Coalson committed
254
	FLAC__STREAM_DECODER_READ_STATUS_ABORT
Josh Coalson's avatar
Josh Coalson committed
255
256
	/**< An unrecoverable error occurred.  The decoder will return from the process call. */

Josh Coalson's avatar
Josh Coalson committed
257
} FLAC__StreamDecoderReadStatus;
Josh Coalson's avatar
Josh Coalson committed
258
259
260
261
262
263

/** Maps a FLAC__StreamDecoderReadStatus to a C string.
 *
 *  Using a FLAC__StreamDecoderReadStatus as the index to this array
 *  will give the string equivalent.  The contents should not be modified.
 */
264
extern FLAC_API const char * const FLAC__StreamDecoderReadStatusString[];
Josh Coalson's avatar
Josh Coalson committed
265

Josh Coalson's avatar
Josh Coalson committed
266
267
268

/** Return values for the FLAC__StreamDecoder write callback.
 */
Josh Coalson's avatar
Josh Coalson committed
269
typedef enum {
Josh Coalson's avatar
Josh Coalson committed
270

Josh Coalson's avatar
Josh Coalson committed
271
	FLAC__STREAM_DECODER_WRITE_STATUS_CONTINUE,
Josh Coalson's avatar
Josh Coalson committed
272
273
	/**< The write was OK and decoding can continue. */

Josh Coalson's avatar
Josh Coalson committed
274
	FLAC__STREAM_DECODER_WRITE_STATUS_ABORT
Josh Coalson's avatar
Josh Coalson committed
275
276
	/**< An unrecoverable error occurred.  The decoder will return from the process call. */

Josh Coalson's avatar
Josh Coalson committed
277
} FLAC__StreamDecoderWriteStatus;
Josh Coalson's avatar
Josh Coalson committed
278
279
280
281
282
283

/** Maps a FLAC__StreamDecoderWriteStatus to a C string.
 *
 *  Using a FLAC__StreamDecoderWriteStatus as the index to this array
 *  will give the string equivalent.  The contents should not be modified.
 */
284
extern FLAC_API const char * const FLAC__StreamDecoderWriteStatusString[];
Josh Coalson's avatar
Josh Coalson committed
285

Josh Coalson's avatar
Josh Coalson committed
286
287
288

/** Possible values passed in to the FLAC__StreamDecoder error callback.
 */
Josh Coalson's avatar
Josh Coalson committed
289
typedef enum {
Josh Coalson's avatar
Josh Coalson committed
290

Josh Coalson's avatar
Josh Coalson committed
291
	FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC,
Josh Coalson's avatar
Josh Coalson committed
292
293
	/**< An error in the stream caused the decoder to lose synchronization. */

Josh Coalson's avatar
Josh Coalson committed
294
	FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER,
Josh Coalson's avatar
Josh Coalson committed
295
296
	/**< The decoder encountered a corrupted frame header. */

Josh Coalson's avatar
Josh Coalson committed
297
	FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH
Josh Coalson's avatar
Josh Coalson committed
298
299
	/**< The frame's data did not match the CRC in the footer. */

Josh Coalson's avatar
Josh Coalson committed
300
} FLAC__StreamDecoderErrorStatus;
Josh Coalson's avatar
Josh Coalson committed
301
302
303
304
305
306

/** Maps a FLAC__StreamDecoderErrorStatus to a C string.
 *
 *  Using a FLAC__StreamDecoderErrorStatus as the index to this array
 *  will give the string equivalent.  The contents should not be modified.
 */
307
extern FLAC_API const char * const FLAC__StreamDecoderErrorStatusString[];
Josh Coalson's avatar
Josh Coalson committed
308

Josh Coalson's avatar
Josh Coalson committed
309

310
311
312
313
314
315
316
/***********************************************************************
 *
 * class FLAC__StreamDecoder
 *
 ***********************************************************************/

struct FLAC__StreamDecoderProtected;
Josh Coalson's avatar
Josh Coalson committed
317
struct FLAC__StreamDecoderPrivate;
Josh Coalson's avatar
Josh Coalson committed
318
319
320
321
/** The opaque structure definition for the stream decoder type.
 *  See the \link flac_stream_decoder stream decoder module \endlink
 *  for a detailed description.
 */
Josh Coalson's avatar
Josh Coalson committed
322
typedef struct {
323
324
	struct FLAC__StreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
	struct FLAC__StreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
Josh Coalson's avatar
Josh Coalson committed
325
326
} FLAC__StreamDecoder;

Josh Coalson's avatar
Josh Coalson committed
327
328
329
330
331
332
333
334
335
336
/** Signature for the read callback.
 *  See FLAC__stream_decoder_set_read_callback() for more info.
 *
 * \param  decoder  The decoder instance calling the callback.
 * \param  buffer   A pointer to a location for the callee to store
 *                  data to be decoded.
 * \param  bytes    A pointer to the size of the buffer.  On entry
 *                  to the callback, it contains the maximum number
 *                  of bytes that may be stored in \a buffer.  The
 *                  callee must set it to the actual number of bytes
Josh Coalson's avatar
Josh Coalson committed
337
338
 *                  stored (0 in case of error or end-of-stream) before
 *                  returning.
Josh Coalson's avatar
Josh Coalson committed
339
340
341
342
343
 * \param  client_data  The callee's client data set through
 *                      FLAC__stream_decoder_set_client_data().
 * \retval FLAC__StreamDecoderReadStatus
 *    The callee's return status.
 */
Josh Coalson's avatar
Josh Coalson committed
344
typedef FLAC__StreamDecoderReadStatus (*FLAC__StreamDecoderReadCallback)(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
Josh Coalson's avatar
Josh Coalson committed
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362

/** Signature for the write callback.
 *  See FLAC__stream_decoder_set_write_callback() for more info.
 *
 * \param  decoder  The decoder instance calling the callback.
 * \param  frame    The description of the decoded frame.  See
 *                  FLAC__Frame.
 * \param  buffer   An array of pointers to decoded channels of data.
 *                  Each pointer will point to an array of signed
 *                  samples of length \a frame->header.blocksize.
 *                  Currently, the channel order has no meaning
 *                  except for stereo streams; in this case channel
 *                  0 is left and 1 is right.
 * \param  client_data  The callee's client data set through
 *                      FLAC__stream_decoder_set_client_data().
 * \retval FLAC__StreamDecoderWriteStatus
 *    The callee's return status.
 */
Josh Coalson's avatar
Josh Coalson committed
363
typedef FLAC__StreamDecoderWriteStatus (*FLAC__StreamDecoderWriteCallback)(const FLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
Josh Coalson's avatar
Josh Coalson committed
364
365
366
367
368
369
370
371
372

/** Signature for the metadata callback.
 *  See FLAC__stream_decoder_set_metadata_callback() for more info.
 *
 * \param  decoder  The decoder instance calling the callback.
 * \param  metadata The decoded metadata block.
 * \param  client_data  The callee's client data set through
 *                      FLAC__stream_decoder_set_client_data().
 */
Josh Coalson's avatar
Josh Coalson committed
373
typedef void (*FLAC__StreamDecoderMetadataCallback)(const FLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
Josh Coalson's avatar
Josh Coalson committed
374
375
376
377
378
379
380
381
382

/** Signature for the error callback.
 *  See FLAC__stream_decoder_set_error_callback() for more info.
 *
 * \param  decoder  The decoder instance calling the callback.
 * \param  status   The error encountered by the decoder.
 * \param  client_data  The callee's client data set through
 *                      FLAC__stream_decoder_set_client_data().
 */
Josh Coalson's avatar
Josh Coalson committed
383
384
typedef void (*FLAC__StreamDecoderErrorCallback)(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);

Josh Coalson's avatar
Josh Coalson committed
385

386
387
388
389
390
391
/***********************************************************************
 *
 * Class constructor/destructor
 *
 ***********************************************************************/

Josh Coalson's avatar
Josh Coalson committed
392
393
394
395
396
397
/** Create a new stream decoder instance.  The instance is created with
 *  default settings; see the individual FLAC__stream_decoder_set_*()
 *  functions for each setting's default.
 *
 * \retval FLAC__StreamDecoder*
 *    \c NULL if there was an error allocating memory, else the new instance.
398
 */
399
FLAC_API FLAC__StreamDecoder *FLAC__stream_decoder_new();
Josh Coalson's avatar
Josh Coalson committed
400

Josh Coalson's avatar
Josh Coalson committed
401
/** Free a decoder instance.  Deletes the object pointed to by \a decoder.
Josh Coalson's avatar
Josh Coalson committed
402
403
404
405
406
 *
 * \param decoder  A pointer to an existing decoder.
 * \assert
 *    \code decoder != NULL \endcode
 */
407
FLAC_API void FLAC__stream_decoder_delete(FLAC__StreamDecoder *decoder);
408

Josh Coalson's avatar
Josh Coalson committed
409

410
411
412
413
414
415
/***********************************************************************
 *
 * Public class method prototypes
 *
 ***********************************************************************/

Josh Coalson's avatar
Josh Coalson committed
416
417
418
419
420
421
422
/** Set the read callback.
 *  The supplied function will be called when the decoder needs more input
 *  data.  The address of the buffer to be filled is supplied, along with
 *  the number of bytes the buffer can hold.  The callback may choose to
 *  supply less data and modify the byte count but must be careful not to
 *  overflow the buffer.  The callback then returns a status code chosen
 *  from FLAC__StreamDecoderReadStatus.
423
 *
Josh Coalson's avatar
Josh Coalson committed
424
425
 * \note
 * The callback is mandatory and must be set before initialization.
426
 *
Josh Coalson's avatar
Josh Coalson committed
427
 * \default \c NULL
Josh Coalson's avatar
Josh Coalson committed
428
 * \param  decoder  A decoder instance to set.
Josh Coalson's avatar
Josh Coalson committed
429
430
431
432
433
434
 * \param  value    See above.
 * \assert
 *    \code decoder != NULL \endcode
 *    \code value != NULL \endcode
 * \retval FLAC__bool
 *    \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);
Josh Coalson's avatar
Josh Coalson committed
437
438
439
440
441
442
443
444
445
446
447

/** Set the write callback.
 *  The supplied function will be called when the decoder has decoded a
 *  single frame of data.  The decoder will pass the frame metadata as
 *  well as an array of pointers (one for each channel) pointing to the
 *  decoded audio.
 *
 * \note
 * The callback is mandatory and must be set before initialization.
 *
 * \default \c NULL
Josh Coalson's avatar
Josh Coalson committed
448
 * \param  decoder  A decoder instance to set.
Josh Coalson's avatar
Josh Coalson committed
449
450
451
452
453
454
455
 * \param  value    See above.
 * \assert
 *    \code decoder != NULL \endcode
 *    \code value != NULL \endcode
 * \retval FLAC__bool
 *    \c false if the decoder is already initialized, else \c true.
 */
456
FLAC_API FLAC__bool FLAC__stream_decoder_set_write_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderWriteCallback value);
Josh Coalson's avatar
Josh Coalson committed
457
458

/** Set the metadata callback.
Josh Coalson's avatar
Josh Coalson committed
459
460
 *  The supplied function will be called when the decoder has decoded a metadata
 *  block.  In a valid FLAC file there will always be one STREAMINFO block,
Josh Coalson's avatar
Josh Coalson committed
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
 *  followed by zero or more other metadata blocks.  These will be supplied
 *  by the decoder in the same order as they appear in the stream and always
 *  before the first audio frame (i.e. write callback).  The metadata block
 *  that is passed in must not be modified, and it doesn't live beyond the
 *  callback, so you should make a copy of it with
 *  FLAC__metadata_object_clone() if you will need it elsewhere.  Since
 *  metadata blocks can potentially be large, by default the decoder only
 *  calls the metadata callback for the STREAMINFO block; you can instruct
 *  the decoder to pass or filter other blocks with
 *  FLAC__stream_decoder_set_metadata_*() calls.
 *
 * \note
 * The callback is mandatory and must be set before initialization.
 *
 * \default \c NULL
Josh Coalson's avatar
Josh Coalson committed
476
 * \param  decoder  A decoder instance to set.
Josh Coalson's avatar
Josh Coalson committed
477
478
479
480
481
482
483
 * \param  value    See above.
 * \assert
 *    \code decoder != NULL \endcode
 *    \code value != NULL \endcode
 * \retval FLAC__bool
 *    \c false if the decoder is already initialized, else \c true.
 */
484
FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderMetadataCallback value);
Josh Coalson's avatar
Josh Coalson committed
485
486
487
488
489
490
491
492
493

/** Set the error callback.
 *  The supplied function will be called whenever an error occurs during
 *  decoding.
 *
 * \note
 * The callback is mandatory and must be set before initialization.
 *
 * \default \c NULL
Josh Coalson's avatar
Josh Coalson committed
494
 * \param  decoder  A decoder instance to set.
Josh Coalson's avatar
Josh Coalson committed
495
496
497
498
499
500
501
 * \param  value    See above.
 * \assert
 *    \code decoder != NULL \endcode
 *    \code value != NULL \endcode
 * \retval FLAC__bool
 *    \c false if the decoder is already initialized, else \c true.
 */
502
FLAC_API FLAC__bool FLAC__stream_decoder_set_error_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorCallback value);
Josh Coalson's avatar
Josh Coalson committed
503
504
505
506
507
508

/** Set the client data to be passed back to callbacks.
 *  This value will be supplied to callbacks in their \a client_data
 *  argument.
 *
 * \default \c NULL
Josh Coalson's avatar
Josh Coalson committed
509
 * \param  decoder  A decoder instance to set.
Josh Coalson's avatar
Josh Coalson committed
510
511
512
513
514
515
 * \param  value    See above.
 * \assert
 *    \code decoder != NULL \endcode
 * \retval FLAC__bool
 *    \c false if the decoder is already initialized, else \c true.
 */
516
FLAC_API FLAC__bool FLAC__stream_decoder_set_client_data(FLAC__StreamDecoder *decoder, void *value);
Josh Coalson's avatar
Josh Coalson committed
517

Josh Coalson's avatar
Josh Coalson committed
518
/** Direct the decoder to pass on all metadata blocks of type \a type.
519
 *
Josh Coalson's avatar
Josh Coalson committed
520
521
522
523
524
525
526
527
528
 * \default By default, only the \c STREAMINFO block is returned via the
 *          metadata callback.
 * \param  decoder  A decoder instance to set.
 * \param  type     See above.
 * \assert
 *    \code decoder != NULL \endcode
 *    \a type is valid
 * \retval FLAC__bool
 *    \c false if the decoder is already initialized, else \c true.
Josh Coalson's avatar
Josh Coalson committed
529
 */
530
FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
Josh Coalson's avatar
Josh Coalson committed
531
532
533
534
535
536
537
538
539
540
541
542
543
544

/** Direct the decoder to pass on all APPLICATION metadata blocks of the
 *  given \a id.
 *
 * \default By default, only the \c STREAMINFO block is returned via the
 *          metadata callback.
 * \param  decoder  A decoder instance to set.
 * \param  id       See above.
 * \assert
 *    \code decoder != NULL \endcode
 *    \code id != NULL \endcode
 * \retval FLAC__bool
 *    \c false if the decoder is already initialized, else \c true.
 */
545
FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
Josh Coalson's avatar
Josh Coalson committed
546
547
548
549
550
551
552
553
554
555
556

/** Direct the decoder to pass on all metadata blocks of any type.
 *
 * \default By default, only the \c STREAMINFO block is returned via the
 *          metadata callback.
 * \param  decoder  A decoder instance to set.
 * \assert
 *    \code decoder != NULL \endcode
 * \retval FLAC__bool
 *    \c false if the decoder is already initialized, else \c true.
 */
557
FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_all(FLAC__StreamDecoder *decoder);
Josh Coalson's avatar
Josh Coalson committed
558
559
560
561
562
563
564
565
566
567
568
569
570

/** Direct the decoder to filter out all metadata blocks of type \a type.
 *
 * \default By default, only the \c STREAMINFO block is returned via the
 *          metadata callback.
 * \param  decoder  A decoder instance to set.
 * \param  type     See above.
 * \assert
 *    \code decoder != NULL \endcode
 *    \a type is valid
 * \retval FLAC__bool
 *    \c false if the decoder is already initialized, else \c true.
 */
571
FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
Josh Coalson's avatar
Josh Coalson committed
572
573
574
575
576
577
578
579
580
581
582
583
584
585

/** Direct the decoder to filter out all APPLICATION metadata blocks of
 *  the given \a id.
 *
 * \default By default, only the \c STREAMINFO block is returned via the
 *          metadata callback.
 * \param  decoder  A decoder instance to set.
 * \param  id       See above.
 * \assert
 *    \code decoder != NULL \endcode
 *    \code id != NULL \endcode
 * \retval FLAC__bool
 *    \c false if the decoder is already initialized, else \c true.
 */
586
FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
Josh Coalson's avatar
Josh Coalson committed
587
588
589
590
591
592
593
594
595
596
597

/** Direct the decoder to filter out all metadata blocks of any type.
 *
 * \default By default, only the \c STREAMINFO block is returned via the
 *          metadata callback.
 * \param  decoder  A decoder instance to set.
 * \assert
 *    \code decoder != NULL \endcode
 * \retval FLAC__bool
 *    \c false if the decoder is already initialized, else \c true.
 */
598
FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_all(FLAC__StreamDecoder *decoder);
599

Josh Coalson's avatar
Josh Coalson committed
600
601
602
603
604
605
606
/** Get the current decoder state.
 *
 * \param  decoder  A decoder instance to query.
 * \assert
 *    \code decoder != NULL \endcode
 * \retval FLAC__StreamDecoderState
 *    The current decoder state.
607
 */
608
FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_get_state(const FLAC__StreamDecoder *decoder);
Josh Coalson's avatar
Josh Coalson committed
609

Josh Coalson's avatar
Josh Coalson committed
610
611
612
613
614
615
616
617
618
619
/** Get the current decoder state as a C string.
 *
 * \param  decoder  A decoder instance to query.
 * \assert
 *    \code decoder != NULL \endcode
 * \retval const char *
 *    The decoder state as a C string.  Do not modify the contents.
 */
FLAC_API const char *FLAC__stream_decoder_get_resolved_state_string(const FLAC__StreamDecoder *decoder);

Josh Coalson's avatar
Josh Coalson committed
620
621
622
623
624
625
626
627
628
629
/** Get the current number of channels in the stream being decoded.
 *  Will only be valid after decoding has started and will contain the
 *  value from the most recently decoded frame header.
 *
 * \param  decoder  A decoder instance to query.
 * \assert
 *    \code decoder != NULL \endcode
 * \retval unsigned
 *    See above.
 */
630
FLAC_API unsigned FLAC__stream_decoder_get_channels(const FLAC__StreamDecoder *decoder);
Josh Coalson's avatar
Josh Coalson committed
631
632
633
634
635
636
637
638
639
640
641

/** Get the current channel assignment in the stream being decoded.
 *  Will only be valid after decoding has started and will contain the
 *  value from the most recently decoded frame header.
 *
 * \param  decoder  A decoder instance to query.
 * \assert
 *    \code decoder != NULL \endcode
 * \retval FLAC__ChannelAssignment
 *    See above.
 */
642
FLAC_API FLAC__ChannelAssignment FLAC__stream_decoder_get_channel_assignment(const FLAC__StreamDecoder *decoder);
Josh Coalson's avatar
Josh Coalson committed
643
644
645
646
647
648
649
650
651
652
653

/** Get the current sample resolution in the stream being decoded.
 *  Will only be valid after decoding has started and will contain the
 *  value from the most recently decoded frame header.
 *
 * \param  decoder  A decoder instance to query.
 * \assert
 *    \code decoder != NULL \endcode
 * \retval unsigned
 *    See above.
 */
654
FLAC_API unsigned FLAC__stream_decoder_get_bits_per_sample(const FLAC__StreamDecoder *decoder);
Josh Coalson's avatar
Josh Coalson committed
655
656
657
658
659
660
661
662
663
664
665

/** Get the current sample rate in Hz of the stream being decoded.
 *  Will only be valid after decoding has started and will contain the
 *  value from the most recently decoded frame header.
 *
 * \param  decoder  A decoder instance to query.
 * \assert
 *    \code decoder != NULL \endcode
 * \retval unsigned
 *    See above.
 */
666
FLAC_API unsigned FLAC__stream_decoder_get_sample_rate(const FLAC__StreamDecoder *decoder);
Josh Coalson's avatar
Josh Coalson committed
667
668
669
670
671
672
673
674
675
676
677

/** Get the current blocksize of the stream being decoded.
 *  Will only be valid after decoding has started and will contain the
 *  value from the most recently decoded frame header.
 *
 * \param  decoder  A decoder instance to query.
 * \assert
 *    \code decoder != NULL \endcode
 * \retval unsigned
 *    See above.
 */
678
FLAC_API unsigned FLAC__stream_decoder_get_blocksize(const FLAC__StreamDecoder *decoder);
679

Josh Coalson's avatar
Josh Coalson committed
680
681
682
683
684
685
686
687
688
689
690
/** Initialize the decoder instance.
 *  Should be called after FLAC__stream_decoder_new() and
 *  FLAC__stream_decoder_set_*() but before any of the
 *  FLAC__stream_decoder_process_*() functions.  Will set and return the
 *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
 *  if initialization succeeded.
 *
 * \param  decoder  An uninitialized decoder instance.
 * \assert
 *    \code decoder != NULL \endcode
 * \retval FLAC__StreamDecoderState
Josh Coalson's avatar
Josh Coalson committed
691
 *    \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA if initialization was
Josh Coalson's avatar
Josh Coalson committed
692
693
 *    successful; see FLAC__StreamDecoderState for the meanings of other
 *    return values.
694
 */
695
FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_init(FLAC__StreamDecoder *decoder);
696

Josh Coalson's avatar
Josh Coalson committed
697
698
699
700
701
702
703
704
705
706
707
708
709
/** Finish the decoding process.
 *  Flushes the decoding buffer, releases resources, resets the decoder
 *  settings to their defaults, and returns the decoder state to
 *  FLAC__STREAM_DECODER_UNINITIALIZED.
 *
 *  In the event of a prematurely-terminated decode, it is not strictly
 *  necessary to call this immediately before FLAC__stream_decoder_delete()
 *  but it is good practice to match every FLAC__stream_decoder_init()
 *  with a FLAC__stream_decoder_finish().
 *
 * \param  decoder  An uninitialized decoder instance.
 * \assert
 *    \code decoder != NULL \endcode
710
 */
711
FLAC_API void FLAC__stream_decoder_finish(FLAC__StreamDecoder *decoder);
712

Josh Coalson's avatar
Josh Coalson committed
713
714
715
716
717
718
719
720
721
722
/** Flush the stream input.
 *  The decoder's input buffer will be cleared and the state set to
 *  \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC.
 *
 * \param  decoder  A decoder instance.
 * \assert
 *    \code decoder != NULL \endcode
 * \retval FLAC__bool
 *    \c true if successful, else \c false if a memory allocation
 *    error occurs.
723
 */
724
FLAC_API FLAC__bool FLAC__stream_decoder_flush(FLAC__StreamDecoder *decoder);
Josh Coalson's avatar
Josh Coalson committed
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739

/** Reset the decoding process.
 *  The decoder's input buffer will be cleared and the state set to
 *  \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.  This is similar to
 *  FLAC__stream_decoder_finish() except that the settings are
 *  preserved; there is no need to call FLAC__stream_decoder_init()
 *  before decoding again.
 *
 * \param  decoder  A decoder instance.
 * \assert
 *    \code decoder != NULL \endcode
 * \retval FLAC__bool
 *    \c true if successful, else \c false if a memory allocation
 *    error occurs.
 */
740
FLAC_API FLAC__bool FLAC__stream_decoder_reset(FLAC__StreamDecoder *decoder);
741

Josh Coalson's avatar
Josh Coalson committed
742
743
744
745
746
/** Decode one metadata block or audio frame.
 *  This version instructs the decoder to decode a either a single metadata
 *  block or a single frame and stop, unless the callbacks return a fatal
 *  error or the read callback returns
 *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
Josh Coalson's avatar
Josh Coalson committed
747
748
 *
 *  As the decoder needs more input it will call the read callback.
Josh Coalson's avatar
Josh Coalson committed
749
750
751
752
 *  Depending on what was decoded, the metadata or write callback will be
 *  called with the decoded metadata block or audio frame, unless an error
 *  occurred.  If the decoder loses sync it will call the error callback
 *  instead.
Josh Coalson's avatar
Josh Coalson committed
753
 *
754
755
 *  Unless there is a fatal read error or end of stream, this function
 *  will return once one whole frame is decoded.  In other words, if the
Josh Coalson's avatar
Josh Coalson committed
756
 *  stream is not synchronized or points to a corrupt frame header, the
757
758
759
760
761
762
763
764
765
766
 *  decoder will continue to try and resync until it gets to a valid
 *  frame, then decode one frame, then return.  If the decoder points to
 *  frame whose frame CRC in the frame footer does not match the
 *  computed frame CRC, this function will issue a
 *  FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH error to the
 *  error callback, and return, having decoded one complete, although
 *  corrupt, frame.  (Such corrupted frames are sent as silence of the
 *  correct length to the write callback.)
 *
 * \param  decoder  An initialized decoder instance.
Josh Coalson's avatar
Josh Coalson committed
767
768
769
770
 * \assert
 *    \code decoder != NULL \endcode
 * \retval FLAC__bool
 *    \c false if any read or write error occurred (except
Josh Coalson's avatar
Josh Coalson committed
771
 *    \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
Josh Coalson's avatar
Josh Coalson committed
772
773
774
 *    in any case, check the decoder state with
 *    FLAC__stream_decoder_get_state() to see what went wrong or to
 *    check for lost synchronization (a sign of stream corruption).
775
 */
776
FLAC_API FLAC__bool FLAC__stream_decoder_process_single(FLAC__StreamDecoder *decoder);
Josh Coalson's avatar
Josh Coalson committed
777

Josh Coalson's avatar
Josh Coalson committed
778
779
780
781
/** Decode until the end of the metadata.
 *  This version instructs the decoder to decode from the current position
 *  and continue until all the metadata has been read, or until the
 *  callbacks return a fatal error or the read callback returns
Josh Coalson's avatar
Josh Coalson committed
782
783
784
785
 *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
 *
 *  As the decoder needs more input it will call the read callback.
 *  As each metadata block is decoded, the metadata callback will be called
Josh Coalson's avatar
Josh Coalson committed
786
787
 *  with the decoded metadata.  If the decoder loses sync it will call the
 *  error callback.
Josh Coalson's avatar
Josh Coalson committed
788
 *
789
 * \param  decoder  An initialized decoder instance.
Josh Coalson's avatar
Josh Coalson committed
790
791
792
793
 * \assert
 *    \code decoder != NULL \endcode
 * \retval FLAC__bool
 *    \c false if any read or write error occurred (except
Josh Coalson's avatar
Josh Coalson committed
794
 *    \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
Josh Coalson's avatar
Josh Coalson committed
795
796
797
798
 *    in any case, check the decoder state with
 *    FLAC__stream_decoder_get_state() to see what went wrong or to
 *    check for lost synchronization (a sign of stream corruption).
 */
799
FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_metadata(FLAC__StreamDecoder *decoder);
Josh Coalson's avatar
Josh Coalson committed
800

Josh Coalson's avatar
Josh Coalson committed
801
802
803
804
805
/** Decode until the end of the stream.
 *  This version instructs the decoder to decode from the current position
 *  and continue until the end of stream (the read callback returns
 *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM), or until the
 *  callbacks return a fatal error.
Josh Coalson's avatar
Josh Coalson committed
806
807
 *
 *  As the decoder needs more input it will call the read callback.
Josh Coalson's avatar
Josh Coalson committed
808
809
810
 *  As each metadata block and frame is decoded, the metadata or write
 *  callback will be called with the decoded metadata or frame.  If the
 *  decoder loses sync it will call the error callback.
Josh Coalson's avatar
Josh Coalson committed
811
 *
812
 * \param  decoder  An initialized decoder instance.
Josh Coalson's avatar
Josh Coalson committed
813
814
815
816
 * \assert
 *    \code decoder != NULL \endcode
 * \retval FLAC__bool
 *    \c false if any read or write error occurred (except
Josh Coalson's avatar
Josh Coalson committed
817
 *    \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
Josh Coalson's avatar
Josh Coalson committed
818
819
820
821
 *    in any case, check the decoder state with
 *    FLAC__stream_decoder_get_state() to see what went wrong or to
 *    check for lost synchronization (a sign of stream corruption).
 */
822
FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_stream(FLAC__StreamDecoder *decoder);
Josh Coalson's avatar
Josh Coalson committed
823

824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
/** Skip one audio frame.
 *  This version instructs the decoder to 'skip' a single frame and stop,
 *  unless the callbacks return a fatal error or the read callback returns
 *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
 *
 *  The decoding flow is the same as what occurs when
 *  FLAC__stream_decoder_process_single() is called to process an audio
 *  frame, except that this function does not decode the parsed data into
 *  PCM or call the write callback.  The integrity of the frame is still
 *  checked the same way as in the other process functions.
 *
 *  This function will return once one whole frame is skipped, in the
 *  same way that FLAC__stream_decoder_process_single() will return once
 *  one whole frame is decoded.
 *
 *  This function, when used from the higher FLAC__SeekableStreamDecoder
 *  layer, can be used in more quickly determining FLAC frame boundaries
 *  when decoding of the actual data is not needed, for example when a
 *  application is separating a FLAC stream into frames for editing or
 *  storing in a container.  To do this, the application can use
 *  FLAC__seekable_stream_decoder_skip_single_frame() to quickly advance
 *  to the next frame, then use
 *  FLAC__seekable_stream_decoder_get_decode_position() to find the new
 *  frame boundary.
 *
 *  This function should only be called when the stream has advanced
 *  past all the metadata, otherwise it will return \c false.
 *
 * \param  decoder  An initialized decoder instance not in a metadata
 *                  state.
 * \assert
 *    \code decoder != NULL \endcode
 * \retval FLAC__bool
 *    \c false if any read or write error occurred (except
 *    \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), or if the decoder
 *    is in the FLAC__STREAM_DECODER_SEARCH_FOR_METADATA or
 *    FLAC__STREAM_DECODER_READ_METADATA state, else \c true;
 *    in any case, check the decoder state with
 *    FLAC__stream_decoder_get_state() to see what went wrong or to
 *    check for lost synchronization (a sign of stream corruption).
 */
FLAC_API FLAC__bool FLAC__stream_decoder_skip_single_frame(FLAC__StreamDecoder *decoder);

Josh Coalson's avatar
Josh Coalson committed
867
868
/* \} */

869
870
871
872
#ifdef __cplusplus
}
#endif

Josh Coalson's avatar
Josh Coalson committed
873
#endif