1
/* libOggFLAC - Free Lossless Audio Codec + Ogg library
2
* Copyright (C) 2002,2003,2004,2005 Josh Coalson
4
* Redistribution and use in source and binary forms, with or without
5
* modification, are permitted provided that the following conditions
8
* - Redistributions of source code must retain the above copyright
9
* notice, this list of conditions and the following disclaimer.
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.
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.
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.
32
#ifndef OggFLAC__STREAM_DECODER_H
33
#define OggFLAC__STREAM_DECODER_H
37
#include "FLAC/stream_decoder.h"
44
/** \file include/OggFLAC/stream_decoder.h
47
* This module contains the functions which implement the stream
50
* See the detailed documentation in the
51
* \link oggflac_stream_decoder stream decoder \endlink module.
54
/** \defgroup oggflac_decoder OggFLAC/ *_decoder.h: decoder interfaces
58
* This module describes the three decoder layers provided by libOggFLAC.
60
* libOggFLAC currently provides the same three layers of access as
61
* libFLAC; the interfaces are nearly identical, with th addition of a
62
* method for specifying the Ogg serial number. See the
63
* \link flac_decoder FLAC decoder module \endlink for full documentation.
66
/** \defgroup oggflac_stream_decoder OggFLAC/stream_decoder.h: stream decoder interface
67
* \ingroup oggflac_decoder
70
* This module contains the functions which implement the stream
73
* The interface here is nearly identical to FLAC's stream decoder,
74
* including the callbacks, with the addition of
75
* OggFLAC__stream_decoder_set_serial_number(). See the
76
* \link flac_stream_decoder FLAC stream decoder module \endlink
77
* for full documentation.
83
/** State values for an OggFLAC__StreamDecoder
85
* The decoder's state can be obtained by calling OggFLAC__stream_decoder_get_state().
89
OggFLAC__STREAM_DECODER_OK = 0,
90
/**< The decoder is in the normal OK state. */
92
OggFLAC__STREAM_DECODER_END_OF_STREAM,
93
/**< The decoder has reached the end of the stream. */
95
OggFLAC__STREAM_DECODER_OGG_ERROR,
96
/**< An error occurred in the underlying Ogg layer. */
98
OggFLAC__STREAM_DECODER_READ_ERROR,
99
/**< The read callback returned an error. */
101
OggFLAC__STREAM_DECODER_FLAC_STREAM_DECODER_ERROR,
102
/**< An error occurred in the underlying FLAC stream decoder;
103
* check OggFLAC__stream_decoder_get_FLAC_stream_decoder_state().
106
OggFLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
107
/**< Memory allocation failed. */
109
OggFLAC__STREAM_DECODER_ALREADY_INITIALIZED,
110
/**< OggFLAC__stream_decoder_init() was called when the decoder was
111
* already initialized, usually because
112
* OggFLAC__stream_decoder_finish() was not called.
115
OggFLAC__STREAM_DECODER_INVALID_CALLBACK,
116
/**< The decoder was initialized before setting all the required callbacks. */
118
OggFLAC__STREAM_DECODER_UNINITIALIZED
119
/**< The decoder is in the uninitialized state. */
121
} OggFLAC__StreamDecoderState;
123
/** Maps an OggFLAC__StreamDecoderState to a C string.
125
* Using an OggFLAC__StreamDecoderState as the index to this array
126
* will give the string equivalent. The contents should not be modified.
128
extern OggFLAC_API const char * const OggFLAC__StreamDecoderStateString[];
131
/***********************************************************************
133
* class OggFLAC__StreamDecoder
135
***********************************************************************/
137
struct OggFLAC__StreamDecoderProtected;
138
struct OggFLAC__StreamDecoderPrivate;
139
/** The opaque structure definition for the stream decoder type.
140
* See the \link oggflac_stream_decoder stream decoder module \endlink
141
* for a detailed description.
144
struct OggFLAC__StreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
145
struct OggFLAC__StreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
146
} OggFLAC__StreamDecoder;
148
/** Signature for the read callback.
149
* See OggFLAC__stream_decoder_set_read_callback()
150
* and FLAC__StreamDecoderReadCallback for more info.
152
* \param decoder The decoder instance calling the callback.
153
* \param buffer A pointer to a location for the callee to store
154
* data to be decoded.
155
* \param bytes A pointer to the size of the buffer. On entry
156
* to the callback, it contains the maximum number
157
* of bytes that may be stored in \a buffer. The
158
* callee must set it to the actual number of bytes
159
* stored before returning.
160
* \param client_data The callee's client data set through
161
* OggFLAC__stream_decoder_set_client_data().
162
* \retval FLAC__StreamDecoderReadStatus
163
* The callee's return status.
165
typedef FLAC__StreamDecoderReadStatus (*OggFLAC__StreamDecoderReadCallback)(const OggFLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
167
/** Signature for the write callback.
168
* See OggFLAC__stream_decoder_set_write_callback()
169
* and FLAC__StreamDecoderWriteCallback for more info.
171
* \param decoder The decoder instance calling the callback.
172
* \param frame The description of the decoded frame. See
174
* \param buffer An array of pointers to decoded channels of data.
175
* Each pointer will point to an array of signed
176
* samples of length \a frame->header.blocksize.
177
* Currently, the channel order has no meaning
178
* except for stereo streams; in this case channel
179
* 0 is left and 1 is right.
180
* \param client_data The callee's client data set through
181
* OggFLAC__stream_decoder_set_client_data().
182
* \retval FLAC__StreamDecoderWriteStatus
183
* The callee's return status.
185
typedef FLAC__StreamDecoderWriteStatus (*OggFLAC__StreamDecoderWriteCallback)(const OggFLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
187
/** Signature for the metadata callback.
188
* See OggFLAC__stream_decoder_set_metadata_callback()
189
* and FLAC__StreamDecoderMetadataCallback for more info.
191
* \param decoder The decoder instance calling the callback.
192
* \param metadata The decoded metadata block.
193
* \param client_data The callee's client data set through
194
* OggFLAC__stream_decoder_set_client_data().
196
typedef void (*OggFLAC__StreamDecoderMetadataCallback)(const OggFLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
198
/** Signature for the error callback.
199
* See OggFLAC__stream_decoder_set_error_callback()
200
* and FLAC__StreamDecoderErrorCallback for more info.
202
* \param decoder The decoder instance calling the callback.
203
* \param status The error encountered by the decoder.
204
* \param client_data The callee's client data set through
205
* OggFLAC__stream_decoder_set_client_data().
207
typedef void (*OggFLAC__StreamDecoderErrorCallback)(const OggFLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
210
/***********************************************************************
212
* Class constructor/destructor
214
***********************************************************************/
216
/** Create a new stream decoder instance. The instance is created with
217
* default settings; see the individual OggFLAC__stream_decoder_set_*()
218
* functions for each setting's default.
220
* \retval OggFLAC__StreamDecoder*
221
* \c NULL if there was an error allocating memory, else the new instance.
223
OggFLAC_API OggFLAC__StreamDecoder *OggFLAC__stream_decoder_new();
225
/** Free a decoder instance. Deletes the object pointed to by \a decoder.
227
* \param decoder A pointer to an existing decoder.
229
* \code decoder != NULL \endcode
231
OggFLAC_API void OggFLAC__stream_decoder_delete(OggFLAC__StreamDecoder *decoder);
234
/***********************************************************************
236
* Public class method prototypes
238
***********************************************************************/
240
/** Set the read callback.
241
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_read_callback()
244
* The callback is mandatory and must be set before initialization.
247
* \param decoder A decoder instance to set.
248
* \param value See above.
250
* \code decoder != NULL \endcode
251
* \code value != NULL \endcode
253
* \c false if the decoder is already initialized, else \c true.
255
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_read_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderReadCallback value);
257
/** Set the write callback.
258
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_write_callback()
261
* The callback is mandatory and must be set before initialization.
264
* \param decoder A decoder instance to set.
265
* \param value See above.
267
* \code decoder != NULL \endcode
268
* \code value != NULL \endcode
270
* \c false if the decoder is already initialized, else \c true.
272
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_write_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderWriteCallback value);
274
/** Set the metadata callback.
275
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_callback()
278
* The callback is mandatory and must be set before initialization.
281
* \param decoder A decoder instance to set.
282
* \param value See above.
284
* \code decoder != NULL \endcode
285
* \code value != NULL \endcode
287
* \c false if the decoder is already initialized, else \c true.
289
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderMetadataCallback value);
291
/** Set the error callback.
292
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_error_callback()
295
* The callback is mandatory and must be set before initialization.
298
* \param decoder A decoder instance to set.
299
* \param value See above.
301
* \code decoder != NULL \endcode
302
* \code value != NULL \endcode
304
* \c false if the decoder is already initialized, else \c true.
306
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_error_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderErrorCallback value);
308
/** Set the client data to be passed back to callbacks.
309
* This value will be supplied to callbacks in their \a client_data
313
* \param decoder A decoder instance to set.
314
* \param value See above.
316
* \code decoder != NULL \endcode
318
* \c false if the decoder is already initialized, else \c true.
320
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_client_data(OggFLAC__StreamDecoder *decoder, void *value);
322
/** Set the serial number for the Ogg stream.
323
* The default behavior is to use the serial number of the first Ogg
324
* page. Setting a serial number here will explicitly specify which
325
* stream is to be decoded.
327
* \default \c use serial number of first page
328
* \param decoder A decoder instance to set.
329
* \param serial_number See above.
331
* \code decoder != NULL \endcode
333
* \c false if the decoder is already initialized, else \c true.
335
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_serial_number(OggFLAC__StreamDecoder *decoder, long serial_number);
337
/** Direct the decoder to pass on all metadata blocks of type \a type.
338
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_respond()
340
* \default By default, only the \c STREAMINFO block is returned via the
342
* \param decoder A decoder instance to set.
343
* \param type See above.
345
* \code decoder != NULL \endcode
348
* \c false if the decoder is already initialized, else \c true.
350
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_respond(OggFLAC__StreamDecoder *decoder, FLAC__MetadataType type);
352
/** Direct the decoder to pass on all APPLICATION metadata blocks of the
354
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_respond_application()
356
* \default By default, only the \c STREAMINFO block is returned via the
358
* \param decoder A decoder instance to set.
359
* \param id See above.
361
* \code decoder != NULL \endcode
362
* \code id != NULL \endcode
364
* \c false if the decoder is already initialized, else \c true.
366
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_respond_application(OggFLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
368
/** Direct the decoder to pass on all metadata blocks of any type.
369
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_respond_all()
371
* \default By default, only the \c STREAMINFO block is returned via the
373
* \param decoder A decoder instance to set.
375
* \code decoder != NULL \endcode
377
* \c false if the decoder is already initialized, else \c true.
379
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_respond_all(OggFLAC__StreamDecoder *decoder);
381
/** Direct the decoder to filter out all metadata blocks of type \a type.
382
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_ignore()
384
* \default By default, only the \c STREAMINFO block is returned via the
386
* \param decoder A decoder instance to set.
387
* \param type See above.
389
* \code decoder != NULL \endcode
392
* \c false if the decoder is already initialized, else \c true.
394
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_ignore(OggFLAC__StreamDecoder *decoder, FLAC__MetadataType type);
396
/** Direct the decoder to filter out all APPLICATION metadata blocks of
398
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_ignore_application()
400
* \default By default, only the \c STREAMINFO block is returned via the
402
* \param decoder A decoder instance to set.
403
* \param id See above.
405
* \code decoder != NULL \endcode
406
* \code id != NULL \endcode
408
* \c false if the decoder is already initialized, else \c true.
410
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_ignore_application(OggFLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
412
/** Direct the decoder to filter out all metadata blocks of any type.
413
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_ignore_all()
415
* \default By default, only the \c STREAMINFO block is returned via the
417
* \param decoder A decoder instance to set.
419
* \code decoder != NULL \endcode
421
* \c false if the decoder is already initialized, else \c true.
423
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_ignore_all(OggFLAC__StreamDecoder *decoder);
425
/** Get the current decoder state.
427
* \param decoder A decoder instance to query.
429
* \code decoder != NULL \endcode
430
* \retval OggFLAC__StreamDecoderState
431
* The current decoder state.
433
OggFLAC_API OggFLAC__StreamDecoderState OggFLAC__stream_decoder_get_state(const OggFLAC__StreamDecoder *decoder);
435
/** Get the state of the underlying FLAC stream decoder.
436
* Useful when the stream decoder state is
437
* \c OggFLAC__STREAM_DECODER_FLAC_STREAM_DECODER_ERROR.
439
* \param decoder A decoder instance to query.
441
* \code decoder != NULL \endcode
442
* \retval FLAC__StreamDecoderState
443
* The FLAC stream decoder state.
445
OggFLAC_API FLAC__StreamDecoderState OggFLAC__stream_decoder_get_FLAC_stream_decoder_state(const OggFLAC__StreamDecoder *decoder);
447
/** Get the current decoder state as a C string.
448
* This version automatically resolves
449
* \c OggFLAC__STREAM_DECODER_FLAC_STREAM_DECODER_ERROR
450
* by getting the FLAC stream decoder's state.
452
* \param decoder A decoder instance to query.
454
* \code decoder != NULL \endcode
455
* \retval const char *
456
* The decoder state as a C string. Do not modify the contents.
458
OggFLAC_API const char *OggFLAC__stream_decoder_get_resolved_state_string(const OggFLAC__StreamDecoder *decoder);
460
/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_channels()
462
* \param decoder A decoder instance to query.
464
* \code decoder != NULL \endcode
468
OggFLAC_API unsigned OggFLAC__stream_decoder_get_channels(const OggFLAC__StreamDecoder *decoder);
470
/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_channel_assignment()
472
* \param decoder A decoder instance to query.
474
* \code decoder != NULL \endcode
475
* \retval OggFLAC__ChannelAssignment
478
OggFLAC_API FLAC__ChannelAssignment OggFLAC__stream_decoder_get_channel_assignment(const OggFLAC__StreamDecoder *decoder);
480
/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_bits_per_sample()
482
* \param decoder A decoder instance to query.
484
* \code decoder != NULL \endcode
488
OggFLAC_API unsigned OggFLAC__stream_decoder_get_bits_per_sample(const OggFLAC__StreamDecoder *decoder);
490
/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_sample_rate()
492
* \param decoder A decoder instance to query.
494
* \code decoder != NULL \endcode
498
OggFLAC_API unsigned OggFLAC__stream_decoder_get_sample_rate(const OggFLAC__StreamDecoder *decoder);
500
/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_blocksize()
502
* \param decoder A decoder instance to query.
504
* \code decoder != NULL \endcode
508
OggFLAC_API unsigned OggFLAC__stream_decoder_get_blocksize(const OggFLAC__StreamDecoder *decoder);
510
/** Initialize the decoder instance.
511
* Should be called after OggFLAC__stream_decoder_new() and
512
* OggFLAC__stream_decoder_set_*() but before any of the
513
* OggFLAC__stream_decoder_process_*() functions. Will set and return the
514
* decoder state, which will be OggFLAC__STREAM_DECODER_OK
515
* if initialization succeeded.
517
* \param decoder An uninitialized decoder instance.
519
* \code decoder != NULL \endcode
520
* \retval OggFLAC__StreamDecoderState
521
* \c OggFLAC__STREAM_DECODER_OK if initialization was
522
* successful; see OggFLAC__StreamDecoderState for the meanings of other
525
OggFLAC_API OggFLAC__StreamDecoderState OggFLAC__stream_decoder_init(OggFLAC__StreamDecoder *decoder);
527
/** Finish the decoding process.
528
* Flushes the decoding buffer, releases resources, resets the decoder
529
* settings to their defaults, and returns the decoder state to
530
* OggFLAC__STREAM_DECODER_UNINITIALIZED.
532
* In the event of a prematurely-terminated decode, it is not strictly
533
* necessary to call this immediately before OggFLAC__stream_decoder_delete()
534
* but it is good practice to match every OggFLAC__stream_decoder_init()
535
* with an OggFLAC__stream_decoder_finish().
537
* \param decoder An uninitialized decoder instance.
539
* \code decoder != NULL \endcode
541
OggFLAC_API void OggFLAC__stream_decoder_finish(OggFLAC__StreamDecoder *decoder);
543
/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_flush()
545
* \param decoder A decoder instance.
547
* \code decoder != NULL \endcode
549
* \c true if successful, else \c false if a memory allocation
552
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_flush(OggFLAC__StreamDecoder *decoder);
554
/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_reset()
556
* \param decoder A decoder instance.
558
* \code decoder != NULL \endcode
560
* \c true if successful, else \c false if a memory allocation
563
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_reset(OggFLAC__StreamDecoder *decoder);
565
/** Decode one metadata block or audio frame.
566
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_process_single()
568
* \param decoder An initialized decoder instance in the state
569
* \c OggFLAC__STREAM_DECODER_OK.
571
* \code decoder != NULL \endcode
572
* \code OggFLAC__stream_decoder_get_state(decoder) == OggFLAC__STREAM_DECODER_OK \endcode
574
* \c false if any read or write error occurred (except
575
* \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
576
* in any case, check the decoder state with
577
* OggFLAC__stream_decoder_get_state() to see what went wrong or to
578
* check for lost synchronization (a sign of stream corruption).
580
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_process_single(OggFLAC__StreamDecoder *decoder);
582
/** Decode until the end of the metadata.
583
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_process_until_end_of_metadata()
585
* \param decoder An initialized decoder instance in the state
586
* \c OggFLAC__STREAM_DECODER_OK.
588
* \code decoder != NULL \endcode
589
* \code OggFLAC__stream_decoder_get_state(decoder) == OggFLAC__STREAM_DECODER_OK \endcode
591
* \c false if any read or write error occurred (except
592
* \c OggFLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
593
* in any case, check the decoder state with
594
* OggFLAC__stream_decoder_get_state() to see what went wrong or to
595
* check for lost synchronization (a sign of stream corruption).
597
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_process_until_end_of_metadata(OggFLAC__StreamDecoder *decoder);
599
/** Decode until the end of the stream.
600
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_process_until_end_of_stream()
602
* \param decoder An initialized decoder instance in the state
603
* \c OggFLAC__STREAM_DECODER_OK.
605
* \code decoder != NULL \endcode
606
* \code OggFLAC__stream_decoder_get_state(decoder) == OggFLAC__STREAM_DECODER_OK \endcode
608
* \c false if any read or write error occurred (except
609
* \c OggFLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
610
* in any case, check the decoder state with
611
* OggFLAC__stream_decoder_get_state() to see what went wrong or to
612
* check for lost synchronization (a sign of stream corruption).
614
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_process_until_end_of_stream(OggFLAC__StreamDecoder *decoder);
added
removed
include/OggFLAC/stream_decoder.h
