20
20
#ifndef FLAC__STREAM_DECODER_H
21
21
#define FLAC__STREAM_DECODER_H
23
24
#include "format.h"
31
/** \file include/FLAC/stream_decoder.h
34
* This module contains the functions which implement the stream
37
* See the detailed documentation in the
38
* \link flac_stream_decoder stream decoder \endlink module.
41
/** \defgroup flac_decoder FLAC/ *_decoder.h: decoder interfaces
45
* This module describes the three decoder layers provided by libFLAC.
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.
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
65
/** \defgroup flac_stream_decoder FLAC/stream_decoder.h: stream decoder interface
66
* \ingroup flac_decoder
69
* This module contains the functions which implement the stream
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().
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:
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
118
* Once the decoder is initialized, your program will call one of several
119
* functions to start the decoding process:
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,
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.
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.
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.
162
* STREAMINFO and SEEKTABLE blocks are always parsed and used internally, but
163
* they still can legally be filtered from the metadata_callback.
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.
173
* FLAC__stream_decoder_finish() resets all settings to the constructor
174
* defaults, including the callbacks.
180
/** State values for a FLAC__StreamDecoder
182
* The decoder's state can be obtained by calling FLAC__stream_decoder_get_state().
26
186
FLAC__STREAM_DECODER_SEARCH_FOR_METADATA = 0,
187
/**< The decoder is ready to search for metadata. */
27
189
FLAC__STREAM_DECODER_READ_METADATA,
190
/**< The decoder is ready to or is in the process of reading metadata. */
28
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. */
29
195
FLAC__STREAM_DECODER_READ_FRAME,
196
/**< The decoder is ready to or is in the process of reading a frame. */
30
198
FLAC__STREAM_DECODER_END_OF_STREAM,
199
/**< The decoder has reached the end of the stream. */
31
201
FLAC__STREAM_DECODER_ABORTED,
202
/**< The decoder was aborted by the read callback. */
32
204
FLAC__STREAM_DECODER_UNPARSEABLE_STREAM,
205
/**< The decoder encountered reserved fields in use in the stream. */
33
207
FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
208
/**< An error occurred allocating memory. */
34
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.
35
216
FLAC__STREAM_DECODER_INVALID_CALLBACK,
217
/**< FLAC__stream_decoder_init() was called without all callbacks being set. */
36
219
FLAC__STREAM_DECODER_UNINITIALIZED
220
/**< The decoder is in the uninitialized state. */
37
222
} FLAC__StreamDecoderState;
38
extern const char *FLAC__StreamDecoderStateString[];
224
/** Maps a FLAC__StreamDecoderState to a C string.
226
* Using a FLAC__StreamDecoderState as the index to this array
227
* will give the string equivalent. The contents should not be modified.
229
extern FLAC_API const char * const FLAC__StreamDecoderStateString[];
232
/** Return values for the FLAC__StreamDecoder read callback.
41
FLAC__STREAM_DECODER_READ_CONTINUE,
42
FLAC__STREAM_DECODER_READ_END_OF_STREAM,
43
FLAC__STREAM_DECODER_READ_ABORT
236
FLAC__STREAM_DECODER_READ_STATUS_CONTINUE,
237
/**< The read was OK and decoding can continue. */
239
FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM,
240
/**< The read was attempted at the end of the stream. */
242
FLAC__STREAM_DECODER_READ_STATUS_ABORT
243
/**< An unrecoverable error occurred. The decoder will return from the process call. */
44
245
} FLAC__StreamDecoderReadStatus;
45
extern const char *FLAC__StreamDecoderReadStatusString[];
247
/** Maps a FLAC__StreamDecoderReadStatus to a C string.
249
* Using a FLAC__StreamDecoderReadStatus as the index to this array
250
* will give the string equivalent. The contents should not be modified.
252
extern FLAC_API const char * const FLAC__StreamDecoderReadStatusString[];
255
/** Return values for the FLAC__StreamDecoder write callback.
48
FLAC__STREAM_DECODER_WRITE_CONTINUE,
49
FLAC__STREAM_DECODER_WRITE_ABORT
259
FLAC__STREAM_DECODER_WRITE_STATUS_CONTINUE,
260
/**< The write was OK and decoding can continue. */
262
FLAC__STREAM_DECODER_WRITE_STATUS_ABORT
263
/**< An unrecoverable error occurred. The decoder will return from the process call. */
50
265
} FLAC__StreamDecoderWriteStatus;
51
extern const char *FLAC__StreamDecoderWriteStatusString[];
267
/** Maps a FLAC__StreamDecoderWriteStatus to a C string.
269
* Using a FLAC__StreamDecoderWriteStatus as the index to this array
270
* will give the string equivalent. The contents should not be modified.
272
extern FLAC_API const char * const FLAC__StreamDecoderWriteStatusString[];
275
/** Possible values passed in to the FLAC__StreamDecoder error callback.
54
FLAC__STREAM_DECODER_ERROR_LOST_SYNC,
55
FLAC__STREAM_DECODER_ERROR_BAD_HEADER,
56
FLAC__STREAM_DECODER_ERROR_FRAME_CRC_MISMATCH
279
FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC,
280
/**< An error in the stream caused the decoder to lose synchronization. */
282
FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER,
283
/**< The decoder encountered a corrupted frame header. */
285
FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH
286
/**< The frame's data did not match the CRC in the footer. */
57
288
} FLAC__StreamDecoderErrorStatus;
58
extern const char *FLAC__StreamDecoderErrorStatusString[];
290
/** Maps a FLAC__StreamDecoderErrorStatus to a C string.
292
* Using a FLAC__StreamDecoderErrorStatus as the index to this array
293
* will give the string equivalent. The contents should not be modified.
295
extern FLAC_API const char * const FLAC__StreamDecoderErrorStatusString[];
60
298
/***********************************************************************
66
304
struct FLAC__StreamDecoderProtected;
67
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.
69
311
struct FLAC__StreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
70
312
struct FLAC__StreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
71
313
} FLAC__StreamDecoder;
315
/** Signature for the read callback.
316
* See FLAC__stream_decoder_set_read_callback() for more info.
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.
331
typedef FLAC__StreamDecoderReadStatus (*FLAC__StreamDecoderReadCallback)(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
333
/** Signature for the write callback.
334
* See FLAC__stream_decoder_set_write_callback() for more info.
336
* \param decoder The decoder instance calling the callback.
337
* \param frame The description of the decoded frame. See
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.
350
typedef FLAC__StreamDecoderWriteStatus (*FLAC__StreamDecoderWriteCallback)(const FLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
352
/** Signature for the metadata callback.
353
* See FLAC__stream_decoder_set_metadata_callback() for more info.
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().
360
typedef void (*FLAC__StreamDecoderMetadataCallback)(const FLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
362
/** Signature for the error callback.
363
* See FLAC__stream_decoder_set_error_callback() for more info.
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().
370
typedef void (*FLAC__StreamDecoderErrorCallback)(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
73
373
/***********************************************************************
75
375
* Class constructor/destructor
77
377
***********************************************************************/
80
* Any parameters that are not set before FLAC__stream_decoder_init()
81
* will take on the defaults from the constructor, shown below.
82
* For more on what the parameters mean, see the documentation.
84
* (*read_callback)() (DEFAULT: NULL ) The callbacks are the only values that MUST be set before FLAC__stream_decoder_init()
85
* (*write_callback)() (DEFAULT: NULL )
86
* (*metadata_callback)() (DEFAULT: NULL )
87
* (*error_callback)() (DEFAULT: NULL )
88
* void* client_data (DEFAULT: NULL ) passed back through the callbacks
90
FLAC__StreamDecoder *FLAC__stream_decoder_new();
91
void FLAC__stream_decoder_delete(FLAC__StreamDecoder *);
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.
383
* \retval FLAC__StreamDecoder*
384
* \c NULL if there was an error allocating memory, else the new instance.
386
FLAC_API FLAC__StreamDecoder *FLAC__stream_decoder_new();
388
/** Free a decoder instance. Deletes the object pointed to by \a decoder.
390
* \param decoder A pointer to an existing decoder.
392
* \code decoder != NULL \endcode
394
FLAC_API void FLAC__stream_decoder_delete(FLAC__StreamDecoder *decoder);
93
397
/***********************************************************************
97
401
***********************************************************************/
100
* Various "set" methods. These may only be called when the decoder
101
* is in the state FLAC__STREAM_DECODER_UNINITIALIZED, i.e. after
102
* FLAC__stream_decoder_new() or FLAC__stream_decoder_finish(), but
103
* before FLAC__stream_decoder_init(). If this is the case they will
104
* return true, otherwise false.
106
* NOTE that these functions do not validate the values as many are
107
* interdependent. The FLAC__stream_decoder_init() function will do
108
* this, so make sure to pay attention to the state returned by
109
* FLAC__stream_decoder_init().
111
* Any parameters that are not set before FLAC__stream_decoder_init()
112
* will take on the defaults from the constructor. NOTE that
113
* FLAC__stream_decoder_flush() or FLAC__stream_decoder_reset() do
114
* NOT reset the values to the constructor defaults.
116
FLAC__bool FLAC__stream_decoder_set_read_callback(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderReadStatus (*value)(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data));
117
FLAC__bool FLAC__stream_decoder_set_write_callback(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderWriteStatus (*value)(const FLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 *buffer[], void *client_data));
118
FLAC__bool FLAC__stream_decoder_set_metadata_callback(const FLAC__StreamDecoder *decoder, void (*value)(const FLAC__StreamDecoder *decoder, const FLAC__StreamMetaData *metadata, void *client_data));
119
FLAC__bool FLAC__stream_decoder_set_error_callback(const FLAC__StreamDecoder *decoder, void (*value)(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data));
120
FLAC__bool FLAC__stream_decoder_set_client_data(const FLAC__StreamDecoder *decoder, void *value);
123
* Methods to return the current stream decoder state, number
124
* of channels, channel assignment, bits-per-sample, sample
125
* rate in Hz, and blocksize in samples. All but the decoder
126
* state will only be valid after decoding has started.
128
FLAC__StreamDecoderState FLAC__stream_decoder_get_state(const FLAC__StreamDecoder *decoder);
129
unsigned FLAC__stream_decoder_get_channels(const FLAC__StreamDecoder *decoder);
130
FLAC__ChannelAssignment FLAC__stream_decoder_get_channel_assignment(const FLAC__StreamDecoder *decoder);
131
unsigned FLAC__stream_decoder_get_bits_per_sample(const FLAC__StreamDecoder *decoder);
132
unsigned FLAC__stream_decoder_get_sample_rate(const FLAC__StreamDecoder *decoder);
133
unsigned FLAC__stream_decoder_get_blocksize(const FLAC__StreamDecoder *decoder);
136
* Initialize the instance; should be called after construction and
137
* 'set' calls but before any of the 'process' calls. Will set and
138
* return the decoder state, which will be
139
* FLAC__STREAM_DECODER_SEARCH_FOR_METADATA if initialization
142
FLAC__StreamDecoderState FLAC__stream_decoder_init(FLAC__StreamDecoder *decoder);
145
* Flush the decoding buffer, release resources, and return the decoder
146
* state to FLAC__STREAM_DECODER_UNINITIALIZED.
148
void FLAC__stream_decoder_finish(FLAC__StreamDecoder *decoder);
151
* state control methods
153
FLAC__bool FLAC__stream_decoder_flush(FLAC__StreamDecoder *decoder);
154
FLAC__bool FLAC__stream_decoder_reset(FLAC__StreamDecoder *decoder);
157
* Methods for decoding the data
159
FLAC__bool FLAC__stream_decoder_process_whole_stream(FLAC__StreamDecoder *decoder);
160
FLAC__bool FLAC__stream_decoder_process_metadata(FLAC__StreamDecoder *decoder);
161
FLAC__bool FLAC__stream_decoder_process_one_frame(FLAC__StreamDecoder *decoder);
162
FLAC__bool FLAC__stream_decoder_process_remaining_frames(FLAC__StreamDecoder *decoder);
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.
412
* The callback is mandatory and must be set before initialization.
415
* \param decoder A decoder instance to set.
416
* \param value See above.
418
* \code decoder != NULL \endcode
419
* \code value != NULL \endcode
421
* \c false if the decoder is already initialized, else \c true.
423
FLAC_API FLAC__bool FLAC__stream_decoder_set_read_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderReadCallback value);
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
432
* The callback is mandatory and must be set before initialization.
435
* \param decoder A decoder instance to set.
436
* \param value See above.
438
* \code decoder != NULL \endcode
439
* \code value != NULL \endcode
441
* \c false if the decoder is already initialized, else \c true.
443
FLAC_API FLAC__bool FLAC__stream_decoder_set_write_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderWriteCallback value);
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.
460
* The callback is mandatory and must be set before initialization.
463
* \param decoder A decoder instance to set.
464
* \param value See above.
466
* \code decoder != NULL \endcode
467
* \code value != NULL \endcode
469
* \c false if the decoder is already initialized, else \c true.
471
FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderMetadataCallback value);
473
/** Set the error callback.
474
* The supplied function will be called whenever an error occurs during
478
* The callback is mandatory and must be set before initialization.
481
* \param decoder A decoder instance to set.
482
* \param value See above.
484
* \code decoder != NULL \endcode
485
* \code value != NULL \endcode
487
* \c false if the decoder is already initialized, else \c true.
489
FLAC_API FLAC__bool FLAC__stream_decoder_set_error_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorCallback value);
491
/** Set the client data to be passed back to callbacks.
492
* This value will be supplied to callbacks in their \a client_data
496
* \param decoder A decoder instance to set.
497
* \param value See above.
499
* \code decoder != NULL \endcode
501
* \c false if the decoder is already initialized, else \c true.
503
FLAC_API FLAC__bool FLAC__stream_decoder_set_client_data(FLAC__StreamDecoder *decoder, void *value);
505
/** Direct the decoder to pass on all metadata blocks of type \a type.
507
* \default By default, only the \c STREAMINFO block is returned via the
509
* \param decoder A decoder instance to set.
510
* \param type See above.
512
* \code decoder != NULL \endcode
515
* \c false if the decoder is already initialized, else \c true.
517
FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
519
/** Direct the decoder to pass on all APPLICATION metadata blocks of the
522
* \default By default, only the \c STREAMINFO block is returned via the
524
* \param decoder A decoder instance to set.
525
* \param id See above.
527
* \code decoder != NULL \endcode
528
* \code id != NULL \endcode
530
* \c false if the decoder is already initialized, else \c true.
532
FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
534
/** Direct the decoder to pass on all metadata blocks of any type.
536
* \default By default, only the \c STREAMINFO block is returned via the
538
* \param decoder A decoder instance to set.
540
* \code decoder != NULL \endcode
542
* \c false if the decoder is already initialized, else \c true.
544
FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_all(FLAC__StreamDecoder *decoder);
546
/** Direct the decoder to filter out all metadata blocks of type \a type.
548
* \default By default, only the \c STREAMINFO block is returned via the
550
* \param decoder A decoder instance to set.
551
* \param type See above.
553
* \code decoder != NULL \endcode
556
* \c false if the decoder is already initialized, else \c true.
558
FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
560
/** Direct the decoder to filter out all APPLICATION metadata blocks of
563
* \default By default, only the \c STREAMINFO block is returned via the
565
* \param decoder A decoder instance to set.
566
* \param id See above.
568
* \code decoder != NULL \endcode
569
* \code id != NULL \endcode
571
* \c false if the decoder is already initialized, else \c true.
573
FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
575
/** Direct the decoder to filter out all metadata blocks of any type.
577
* \default By default, only the \c STREAMINFO block is returned via the
579
* \param decoder A decoder instance to set.
581
* \code decoder != NULL \endcode
583
* \c false if the decoder is already initialized, else \c true.
585
FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_all(FLAC__StreamDecoder *decoder);
587
/** Get the current decoder state.
589
* \param decoder A decoder instance to query.
591
* \code decoder != NULL \endcode
592
* \retval FLAC__StreamDecoderState
593
* The current decoder state.
595
FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_get_state(const FLAC__StreamDecoder *decoder);
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.
601
* \param decoder A decoder instance to query.
603
* \code decoder != NULL \endcode
607
FLAC_API unsigned FLAC__stream_decoder_get_channels(const FLAC__StreamDecoder *decoder);
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.
613
* \param decoder A decoder instance to query.
615
* \code decoder != NULL \endcode
616
* \retval FLAC__ChannelAssignment
619
FLAC_API FLAC__ChannelAssignment FLAC__stream_decoder_get_channel_assignment(const FLAC__StreamDecoder *decoder);
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.
625
* \param decoder A decoder instance to query.
627
* \code decoder != NULL \endcode
631
FLAC_API unsigned FLAC__stream_decoder_get_bits_per_sample(const FLAC__StreamDecoder *decoder);
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.
637
* \param decoder A decoder instance to query.
639
* \code decoder != NULL \endcode
643
FLAC_API unsigned FLAC__stream_decoder_get_sample_rate(const FLAC__StreamDecoder *decoder);
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.
649
* \param decoder A decoder instance to query.
651
* \code decoder != NULL \endcode
655
FLAC_API unsigned FLAC__stream_decoder_get_blocksize(const FLAC__StreamDecoder *decoder);
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.
664
* \param decoder An uninitialized decoder instance.
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
672
FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_init(FLAC__StreamDecoder *decoder);
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.
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().
684
* \param decoder An uninitialized decoder instance.
686
* \code decoder != NULL \endcode
688
FLAC_API void FLAC__stream_decoder_finish(FLAC__StreamDecoder *decoder);
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.
694
* \param decoder A decoder instance.
696
* \code decoder != NULL \endcode
698
* \c true if successful, else \c false if a memory allocation
701
FLAC_API FLAC__bool FLAC__stream_decoder_flush(FLAC__StreamDecoder *decoder);
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.
710
* \param decoder A decoder instance.
712
* \code decoder != NULL \endcode
714
* \c true if successful, else \c false if a memory allocation
717
FLAC_API FLAC__bool FLAC__stream_decoder_reset(FLAC__StreamDecoder *decoder);
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.
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
731
* \param decoder An initialized decoder instance in the state
732
* \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC.
734
* \code decoder != NULL \endcode
735
* \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC \endcode
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).
743
FLAC_API FLAC__bool FLAC__stream_decoder_process_single(FLAC__StreamDecoder *decoder);
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.
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
756
* \param decoder An initialized decoder instance in the state
757
* \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.
759
* \code decoder != NULL \endcode
760
* \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_METADATA \endcode
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).
768
FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_metadata(FLAC__StreamDecoder *decoder);
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.
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.
781
* \param decoder An initialized decoder instance in the state
782
* \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.
784
* \code decoder != NULL \endcode
785
* \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_METADATA \endcode
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).
793
FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_stream(FLAC__StreamDecoder *decoder);
added
removed
include/FLAC/stream_decoder.h
