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