mirrors
/
flac
mirror of https://github.com/xiph/flac
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

did more work but still not finished

This commit is contained in:
Josh Coalson 2002-08-06 05:38:55 +00:00
parent fb4ab8fdc0
commit ac2932b47f
6 changed files with 887 additions and 1072 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

235
include/OggFLAC/file_decoder.h
View File

@ -44,114 +44,57 @@ extern "C" {
* This module contains the functions which implement the file
* decoder.
*
* The basic usage of this decoder is as follows:
* - The program creates an instance of a decoder using
* OggFLAC__file_decoder_new().
* - The program overrides the default settings and sets callbacks for
* writing, error reporting, and metadata reporting using
* OggFLAC__file_decoder_set_*() functions.
* - The program initializes the instance to validate the settings and
* prepare for decoding using OggFLAC__file_decoder_init().
* - The program calls the OggFLAC__file_decoder_process_*() functions
* to decode data, which subsequently calls the callbacks.
* - The program finishes the decoding with OggFLAC__file_decoder_finish(),
* which flushes the input and output and resets the decoder to the
* uninitialized state.
* - The instance may be used again or deleted with
* OggFLAC__file_decoder_delete().
*
* The file decoder is a trivial wrapper around the
* \link oggflac_seekable_stream_decoder seekable stream decoder \endlink
* meant to simplfy the process of decoding from a standard file. The
* file decoder supplies all but the Write/Metadata/Error callbacks.
* The user needs only to provide the path to the file and the file
* decoder handles the rest.
*
* Like the seekable stream decoder, seeking is exposed through the
* OggFLAC__file_decoder_seek_absolute() method. At any point after the file
* decoder has been initialized, the user can call this function to seek to
* an exact sample within the file. Subsequently, the first time the write
* callback is called it will be passed a (possibly partial) block starting
* at that sample.
*
* The file decoder also inherits MD5 signature checking from the seekable
* stream decoder. If this is turned on before initialization,
* OggFLAC__file_decoder_finish() will report when the decoded MD5 signature
* does not match the one stored in the STREAMINFO block. MD5 checking is
* automatically turned off if there is no signature in the STREAMINFO
* block or when a seek is attempted.
*
* Make sure to read the detailed descriptions of the
* \link oggflac_seekable_stream_decoder seekable stream decoder module \endlink
* and \link oggflac_stream_decoder stream decoder module \endlink
* since the file decoder inherits much of its behavior from them.
*
* \note
* The "set" functions may only be called when the decoder is in the
* state OggFLAC__FILE_DECODER_UNINITIALIZED, i.e. after
* OggFLAC__file_decoder_new() or OggFLAC__file_decoder_finish(), but
* before OggFLAC__file_decoder_init(). If this is the case they will
* return \c true, otherwise \c false.
*
* \note
* OggFLAC__file_decoder_finish() resets all settings to the constructor
* defaults, including the callbacks.
* The interface here is identical to FLAC's file decoder. See the
* defaults, including the callbacks. See the \link flac_file_decoder
* FLAC file decoder module \endlink for full documentation.
*
* \{
*/
/** State values for a OggFLAC__FileDecoder
/** State values for an OggFLAC__FileDecoder
*
* The decoder's state can be obtained by calling OggFLAC__file_decoder_get_state().
*/
typedef enum {
OggFLAC__FILE_DECODER_OK = 0,
OggFLAC__FILE_DECODER_OK = 0,
/**< The decoder is in the normal OK state. */
OggFLAC__FILE_DECODER_END_OF_FILE,
/**< The decoder has reached the end of the file. */
OggFLAC__FILE_DECODER_ERROR_OPENING_FILE,
/**< An error occurred opening the input file. */
OggFLAC__FILE_DECODER_MEMORY_ALLOCATION_ERROR,
/**< An error occurred allocating memory. */
OggFLAC__FILE_DECODER_SEEK_ERROR,
/**< An error occurred while seeking. */
OggFLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR,
/**< An error occurred in the underlying seekable stream decoder. */
OggFLAC__FILE_DECODER_ALREADY_INITIALIZED,
/**< OggFLAC__file_decoder_init() was called when the decoder was already
* initialized, usually because OggFLAC__file_decoder_finish() was not
* called.
OggFLAC__FILE_DECODER_FLAC_FILE_DECODER_ERROR,
/**< An error occurred in the underlying FLAC file decoder;
* check OggFLAC__file_decoder_get_FLAC_file_decoder_state().
*/
OggFLAC__FILE_DECODER_INVALID_CALLBACK,
/**< OggFLAC__file_decoder_init() was called without all callbacks
* being set.
OggFLAC__FILE_DECODER_INVALID_CALLBACK,
/**< The decoder was initialized before setting all the required callbacks. */
OggFLAC__FILE_DECODER_MEMORY_ALLOCATION_ERROR,
/**< Memory allocation failed. */
OggFLAC__FILE_DECODER_ALREADY_INITIALIZED,
/**< OggFLAC__file_decoder_init() was called when the decoder was
* already initialized, usually because
* OggFLAC__file_decoder_finish() was not called.
*/
OggFLAC__FILE_DECODER_UNINITIALIZED
OggFLAC__FILE_DECODER_UNINITIALIZED
/**< The decoder is in the uninitialized state. */
} OggFLAC__FileDecoderState;
/** Maps a OggFLAC__FileDecoderState to a C string.
/** Maps an OggFLAC__FileDecoderState to a C string.
*
* Using a OggFLAC__FileDecoderState as the index to this array
* Using an OggFLAC__FileDecoderState as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
/* @@@@ double-check mapping */
extern const char * const OggFLAC__FileDecoderStateString[];
/***********************************************************************
*
* class OggFLAC__FileDecoder : public OggFLAC__StreamDecoder
* class OggFLAC__FileDecoder : public FLAC__FileDecoder
*
***********************************************************************/
@ -167,9 +110,9 @@ typedef struct {
} OggFLAC__FileDecoder;
/* @@@@ document */
typedef OggFLAC__StreamDecoderWriteStatus (*OggFLAC__FileDecoderWriteCallback)(const OggFLAC__FileDecoder *decoder, const OggFLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
typedef void (*OggFLAC__FileDecoderMetadataCallback)(const OggFLAC__FileDecoder *decoder, const OggFLAC__StreamMetadata *metadata, void *client_data);
typedef void (*OggFLAC__FileDecoderErrorCallback)(const OggFLAC__FileDecoder *decoder, OggFLAC__StreamDecoderErrorStatus status, void *client_data);
typedef FLAC__StreamDecoderWriteStatus (*OggFLAC__FileDecoderWriteCallback)(const OggFLAC__FileDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
typedef void (*OggFLAC__FileDecoderMetadataCallback)(const OggFLAC__FileDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
typedef void (*OggFLAC__FileDecoderErrorCallback)(const OggFLAC__FileDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
/***********************************************************************
@ -203,8 +146,8 @@ void OggFLAC__file_decoder_delete(OggFLAC__FileDecoder *decoder);
***********************************************************************/
/** Set the "MD5 signature checking" flag.
* This is inherited from OggFLAC__SeekableStreamDecoder; see
* OggFLAC__seekable_stream_decoder_set_md5_checking().
* This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_set_md5_checking().
*
* \default \c false
* \param decoder A decoder instance to set.
@ -217,6 +160,8 @@ void OggFLAC__file_decoder_delete(OggFLAC__FileDecoder *decoder);
FLAC__bool OggFLAC__file_decoder_set_md5_checking(OggFLAC__FileDecoder *decoder, FLAC__bool value);
/** Set the input file name to decode.
* This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_set_filename().
*
* \default \c "-"
* \param decoder A decoder instance to set.
@ -231,8 +176,8 @@ FLAC__bool OggFLAC__file_decoder_set_md5_checking(OggFLAC__FileDecoder *decoder,
FLAC__bool OggFLAC__file_decoder_set_filename(OggFLAC__FileDecoder *decoder, const char *value);
/** Set the write callback.
* This is inherited from OggFLAC__SeekableStreamDecoder; see
* OggFLAC__seekable_stream_decoder_set_write_callback().
* This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_set_write_callback().
*
* \note
* The callback is mandatory and must be set before initialization.
@ -249,8 +194,8 @@ FLAC__bool OggFLAC__file_decoder_set_filename(OggFLAC__FileDecoder *decoder, con
FLAC__bool OggFLAC__file_decoder_set_write_callback(OggFLAC__FileDecoder *decoder, OggFLAC__FileDecoderWriteCallback value);
/** Set the metadata callback.
* This is inherited from OggFLAC__SeekableStreamDecoder; see
* OggFLAC__seekable_stream_decoder_set_metadata_callback().
* This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_set_metadata_callback().
*
* \note
* The callback is mandatory and must be set before initialization.
@ -267,8 +212,8 @@ FLAC__bool OggFLAC__file_decoder_set_write_callback(OggFLAC__FileDecoder *decode
FLAC__bool OggFLAC__file_decoder_set_metadata_callback(OggFLAC__FileDecoder *decoder, OggFLAC__FileDecoderMetadataCallback value);
/** Set the error callback.
* This is inherited from OggFLAC__SeekableStreamDecoder; see
* OggFLAC__seekable_stream_decoder_set_error_callback().
* This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_set_error_callback().
*
* \note
* The callback is mandatory and must be set before initialization.
@ -298,8 +243,8 @@ FLAC__bool OggFLAC__file_decoder_set_error_callback(OggFLAC__FileDecoder *decode
*/
FLAC__bool OggFLAC__file_decoder_set_client_data(OggFLAC__FileDecoder *decoder, void *value);
/** This is inherited from OggFLAC__SeekableStreamDecoder; see
* OggFLAC__seekable_stream_decoder_set_metadata_respond().
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_set_metadata_respond().
*
* \default By default, only the \c STREAMINFO block is returned via the
* metadata callback.
@ -313,8 +258,8 @@ FLAC__bool OggFLAC__file_decoder_set_client_data(OggFLAC__FileDecoder *decoder,
*/
FLAC__bool OggFLAC__file_decoder_set_metadata_respond(OggFLAC__FileDecoder *decoder, OggFLAC__MetadataType type);
/** This is inherited from OggFLAC__SeekableStreamDecoder; see
* OggFLAC__seekable_stream_decoder_set_metadata_respond_application().
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_set_metadata_respond_application().
*
* \default By default, only the \c STREAMINFO block is returned via the
* metadata callback.
@ -328,8 +273,8 @@ FLAC__bool OggFLAC__file_decoder_set_metadata_respond(OggFLAC__FileDecoder *deco
*/
FLAC__bool OggFLAC__file_decoder_set_metadata_respond_application(OggFLAC__FileDecoder *decoder, const FLAC__byte id[4]);
/** This is inherited from OggFLAC__SeekableStreamDecoder; see
* OggFLAC__seekable_stream_decoder_set_metadata_respond_all().
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_set_metadata_respond_all().
*
* \default By default, only the \c STREAMINFO block is returned via the
* metadata callback.
@ -341,8 +286,8 @@ FLAC__bool OggFLAC__file_decoder_set_metadata_respond_application(OggFLAC__FileD
*/
FLAC__bool OggFLAC__file_decoder_set_metadata_respond_all(OggFLAC__FileDecoder *decoder);
/** This is inherited from OggFLAC__SeekableStreamDecoder; see
* OggFLAC__seekable_stream_decoder_set_metadata_ignore().
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_set_metadata_ignore().
*
* \default By default, only the \c STREAMINFO block is returned via the
* metadata callback.
@ -356,8 +301,8 @@ FLAC__bool OggFLAC__file_decoder_set_metadata_respond_all(OggFLAC__FileDecoder *
*/
FLAC__bool OggFLAC__file_decoder_set_metadata_ignore(OggFLAC__FileDecoder *decoder, OggFLAC__MetadataType type);
/** This is inherited from OggFLAC__SeekableStreamDecoder; see
* OggFLAC__seekable_stream_decoder_set_metadata_ignore_application().
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_set_metadata_ignore_application().
*
* \default By default, only the \c STREAMINFO block is returned via the
* metadata callback.
@ -371,8 +316,8 @@ FLAC__bool OggFLAC__file_decoder_set_metadata_ignore(OggFLAC__FileDecoder *decod
*/
FLAC__bool OggFLAC__file_decoder_set_metadata_ignore_application(OggFLAC__FileDecoder *decoder, const FLAC__byte id[4]);
/** This is inherited from OggFLAC__SeekableStreamDecoder; see
* OggFLAC__seekable_stream_decoder_set_metadata_ignore_all().
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_set_metadata_ignore_all().
*
* \default By default, only the \c STREAMINFO block is returned via the
* metadata callback.
@ -394,34 +339,47 @@ FLAC__bool OggFLAC__file_decoder_set_metadata_ignore_all(OggFLAC__FileDecoder *d
*/
OggFLAC__FileDecoderState OggFLAC__file_decoder_get_state(const OggFLAC__FileDecoder *decoder);
/** Get the state of the underlying seekable stream decoder.
/** Get the state of the underlying FLAC file decoder.
* Useful when the file decoder state is
* \c OggFLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR.
* \c OggFLAC__FILE_DECODER_FLAC_FILE_DECODER_ERROR.
*
* \param decoder An decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval OggFLAC__SeekableStreamDecoderState
* The seekable stream decoder state.
* \retval FLAC__FileDecoderState
* The FLAC file decoder state.
*/
OggFLAC__SeekableStreamDecoderState OggFLAC__file_decoder_get_seekable_stream_decoder_state(const OggFLAC__FileDecoder *decoder);
FLAC__FileDecoderState OggFLAC__file_decoder_get_FLAC_file_decoder_state(const OggFLAC__FileDecoder *decoder);
/** Get the state of the underlying stream decoder.
/** Get the state of the underlying FLAC file decoder's seekable stream decoder.
* Useful when the file decoder state is
* \c OggFLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR and the seekable stream
* decoder state is \c OggFLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
* \c OggFLAC__FILE_DECODER_FLAC_FILE_DECODER_ERROR and the FLAC file decoder state is
* \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR.
*
* \param decoder An decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval OggFLAC__SeekableStreamDecoderState
* The seekable stream decoder state.
* \retval FLAC__SeekableStreamDecoderState
* The FLAC seekable stream decoder state.
*/
OggFLAC__StreamDecoderState OggFLAC__file_decoder_get_stream_decoder_state(const OggFLAC__FileDecoder *decoder);
FLAC__SeekableStreamDecoderState OggFLAC__file_decoder_get_FLAC_seekable_stream_decoder_state(const OggFLAC__FileDecoder *decoder);
/** Get the "MD5 signature checking" flag.
* This is inherited from OggFLAC__SeekableStreamDecoder; see
* OggFLAC__seekable_stream_decoder_get_md5_checking().
/** Get the state of the underlying FLAC file decoder's stream decoder.
* Useful when the file decoder state is
* \c OggFLAC__FILE_DECODER_FLAC_FILE_DECODER_ERROR and the FLAC file decoder state is
* \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR and the
* FLAC seekable stream decoder state is \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
*
* \param decoder An decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__StreamDecoderState
* The FLAC stream decoder state.
*/
FLAC__StreamDecoderState OggFLAC__file_decoder_get_FLAC_stream_decoder_state(const OggFLAC__FileDecoder *decoder);
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_get_md5_checking().
*
* \param decoder A decoder instance to query.
* \assert
@ -431,8 +389,8 @@ OggFLAC__StreamDecoderState OggFLAC__file_decoder_get_stream_decoder_state(const
*/
FLAC__bool OggFLAC__file_decoder_get_md5_checking(const OggFLAC__FileDecoder *decoder);
/** This is inherited from OggFLAC__SeekableStreamDecoder; see
* OggFLAC__seekable_stream_decoder_get_channels().
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_get_channels().
*
* \param decoder A decoder instance to query.
* \assert
@ -442,8 +400,8 @@ FLAC__bool OggFLAC__file_decoder_get_md5_checking(const OggFLAC__FileDecoder *de
*/
unsigned OggFLAC__file_decoder_get_channels(const OggFLAC__FileDecoder *decoder);
/** This is inherited from OggFLAC__SeekableStreamDecoder; see
* OggFLAC__seekable_stream_decoder_get_channel_assignment().
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_get_channel_assignment().
*
* \param decoder A decoder instance to query.
* \assert
@ -453,8 +411,8 @@ unsigned OggFLAC__file_decoder_get_channels(const OggFLAC__FileDecoder *decoder)
*/
OggFLAC__ChannelAssignment OggFLAC__file_decoder_get_channel_assignment(const OggFLAC__FileDecoder *decoder);
/** This is inherited from OggFLAC__SeekableStreamDecoder; see
* OggFLAC__seekable_stream_decoder_get_bits_per_sample().
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_get_bits_per_sample().
*
* \param decoder A decoder instance to query.
* \assert
@ -464,8 +422,8 @@ OggFLAC__ChannelAssignment OggFLAC__file_decoder_get_channel_assignment(const Og
*/
unsigned OggFLAC__file_decoder_get_bits_per_sample(const OggFLAC__FileDecoder *decoder);
/** This is inherited from OggFLAC__SeekableStreamDecoder; see
* OggFLAC__seekable_stream_decoder_get_sample_rate().
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_get_sample_rate().
*
* \param decoder A decoder instance to query.
* \assert
@ -475,8 +433,8 @@ unsigned OggFLAC__file_decoder_get_bits_per_sample(const OggFLAC__FileDecoder *d
*/
unsigned OggFLAC__file_decoder_get_sample_rate(const OggFLAC__FileDecoder *decoder);
/** This is inherited from OggFLAC__SeekableStreamDecoder; see
* OggFLAC__seekable_stream_decoder_get_blocksize().
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_get_blocksize().
*
* \param decoder A decoder instance to query.
* \assert
@ -510,7 +468,7 @@ OggFLAC__FileDecoderState OggFLAC__file_decoder_init(OggFLAC__FileDecoder *decod
* In the event of a prematurely-terminated decode, it is not strictly
* necessary to call this immediately before OggFLAC__file_decoder_delete()
* but it is good practice to match every OggFLAC__file_decoder_init() with
* a OggFLAC__file_decoder_finish().
* an OggFLAC__file_decoder_finish().
*
* \param decoder An uninitialized decoder instance.
* \assert
@ -523,8 +481,8 @@ OggFLAC__FileDecoderState OggFLAC__file_decoder_init(OggFLAC__FileDecoder *decod
*/
FLAC__bool OggFLAC__file_decoder_finish(OggFLAC__FileDecoder *decoder);
/** This is inherited from OggFLAC__SeekableStreamDecoder; see
* OggFLAC__seekable_stream_decoder_process_single().
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_process_single().
*
* \param decoder A decoder instance.
* \assert
@ -534,8 +492,8 @@ FLAC__bool OggFLAC__file_decoder_finish(OggFLAC__FileDecoder *decoder);
*/
FLAC__bool OggFLAC__file_decoder_process_single(OggFLAC__FileDecoder *decoder);
/** This is inherited from OggFLAC__SeekableStreamDecoder; see
* OggFLAC__seekable_stream_decoder_process_until_end_of_metadata().
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_process_until_end_of_metadata().
*
* \param decoder A decoder instance.
* \assert
@ -545,8 +503,8 @@ FLAC__bool OggFLAC__file_decoder_process_single(OggFLAC__FileDecoder *decoder);
*/
FLAC__bool OggFLAC__file_decoder_process_until_end_of_metadata(OggFLAC__FileDecoder *decoder);
/** This is inherited from OggFLAC__SeekableStreamDecoder; see
* OggFLAC__seekable_stream_decoder_process_until_end_of_stream().
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_process_until_end_of_stream().
*
* \param decoder A decoder instance.
* \assert
@ -556,8 +514,8 @@ FLAC__bool OggFLAC__file_decoder_process_until_end_of_metadata(OggFLAC__FileDeco
*/
FLAC__bool OggFLAC__file_decoder_process_until_end_of_file(OggFLAC__FileDecoder *decoder);
/** This is inherited from OggFLAC__SeekableStreamDecoder; see
* OggFLAC__seekable_stream_decoder_process_remaining_frames().
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_process_remaining_frames().
*
* \param decoder A decoder instance.
* \assert
@ -567,9 +525,8 @@ FLAC__bool OggFLAC__file_decoder_process_until_end_of_file(OggFLAC__FileDecoder
*/
FLAC__bool OggFLAC__file_decoder_process_remaining_frames(OggFLAC__FileDecoder *decoder);
/** Flush the input and seek to an absolute sample.
* This is inherited from OggFLAC__SeekableStreamDecoder; see
* OggFLAC__seekable_stream_decoder_seek_absolute().
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_seek_absolute().
*
* \param decoder A decoder instance.
* \param sample The target sample number to seek to.

284
include/OggFLAC/file_encoder.h
View File

@ -44,48 +44,15 @@ extern "C" {
* This module contains the functions which implement the file
* encoder.
*
* The basic usage of this encoder is as follows:
* - The program creates an instance of an encoder using
* OggFLAC__file_encoder_new().
* - The program overrides the default settings using
* OggFLAC__file_encoder_set_*() functions.
* - The program initializes the instance to validate the settings and
* prepare for encoding using OggFLAC__file_encoder_init().
* - The program calls OggFLAC__file_encoder_process() or
* OggFLAC__file_encoder_process_interleaved() to encode data, which
* subsequently writes data to the output file.
* - The program finishes the encoding with OggFLAC__file_encoder_finish(),
* which causes the encoder to encode any data still in its input pipe,
* rewind and write the STREAMINFO metadata to file, and finally reset
* the encoder to the uninitialized state.
* - The instance may be used again or deleted with
* OggFLAC__file_encoder_delete().
*
* The file encoder is a wrapper around the
* \link oggflac_seekable_stream_encoder seekable stream encoder \endlink which supplies all
* callbacks internally; the user need specify only the filename.
*
* Make sure to read the detailed description of the
* \link oggflac_seekable_stream_encoder seekable stream encoder module \endlink since the
* \link oggflac_stream_encoder stream encoder module \endlink since the
* file encoder inherits much of its behavior from them.
*
* \note
* The "set" functions may only be called when the encoder is in the
* state OggFLAC__FILE_ENCODER_UNINITIALIZED, i.e. after
* OggFLAC__file_encoder_new() or OggFLAC__file_encoder_finish(), but
* before OggFLAC__file_encoder_init(). If this is the case they will
* return \c true, otherwise \c false.
*
* \note
* OggFLAC__file_encoder_finish() resets all settings to the constructor
* defaults.
* The interface here is identical to FLAC's file encoder. See the
* defaults, including the callbacks. See the \link flac_file_encoder
* FLAC file encoder module \endlink for full documentation.
*
* \{
*/
/** State values for a OggFLAC__FileEncoder
/** State values for an OggFLAC__FileEncoder
*
* The encoder's state can be obtained by calling OggFLAC__file_encoder_get_state().
*/
@ -94,21 +61,13 @@ typedef enum {
OggFLAC__FILE_ENCODER_OK = 0,
/**< The encoder is in the normal OK state. */
OggFLAC__FILE_ENCODER_NO_FILENAME,
/**< OggFLAC__file_encoder_init() was called without first calling
* OggFLAC__file_encoder_set_filename().
OggFLAC__FILE_ENCODER_FLAC_FILE_ENCODER_ERROR,
/**< An error occurred in the underlying FLAC file encoder;
* check OggFLAC__file_encoder_get_FLAC_file_encoder_state().
*/
OggFLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR,
/**< An error occurred in the underlying seekable stream encoder;
* check OggFLAC__file_encoder_get_seekable_stream_encoder_state().
*/
OggFLAC__FILE_ENCODER_FATAL_ERROR_WHILE_WRITING,
/**< A fatal error occurred while writing to the encoded file. */
OggFLAC__FILE_ENCODER_ERROR_OPENING_FILE,
/**< An error occurred opening the output file for writing. */
OggFLAC__FILE_ENCODER_INVALID_CALLBACK,
/**< The encoder was initialized before setting all the required callbacks. */
OggFLAC__FILE_ENCODER_MEMORY_ALLOCATION_ERROR,
/**< Memory allocation failed. */
@ -124,9 +83,9 @@ typedef enum {
} OggFLAC__FileEncoderState;
/** Maps a OggFLAC__FileEncoderState to a C string.
/** Maps an OggFLAC__FileEncoderState to a C string.
*
* Using a OggFLAC__FileEncoderState as the index to this array
* Using an OggFLAC__FileEncoderState as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
/* @@@@ double-check mapping */
@ -183,8 +142,8 @@ void OggFLAC__file_encoder_delete(OggFLAC__FileEncoder *encoder);
*
***********************************************************************/
/** This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_set_verify().
/** This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_set_verify().
*
* \default \c true
* \param encoder An encoder instance to set.
@ -196,8 +155,8 @@ void OggFLAC__file_encoder_delete(OggFLAC__FileEncoder *encoder);
*/
FLAC__bool OggFLAC__file_encoder_set_verify(OggFLAC__FileEncoder *encoder, FLAC__bool value);
/** This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_set_streamable_subset().
/** This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_set_streamable_subset().
*
* \default \c true
* \param encoder An encoder instance to set.
@ -209,8 +168,8 @@ FLAC__bool OggFLAC__file_encoder_set_verify(OggFLAC__FileEncoder *encoder, FLAC_
*/
FLAC__bool OggFLAC__file_encoder_set_streamable_subset(OggFLAC__FileEncoder *encoder, FLAC__bool value);
/** This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_set_do_mid_side_stereo().
/** This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_set_do_mid_side_stereo().
*
* \default \c false
* \param encoder An encoder instance to set.
@ -222,8 +181,8 @@ FLAC__bool OggFLAC__file_encoder_set_streamable_subset(OggFLAC__FileEncoder *enc
*/
FLAC__bool OggFLAC__file_encoder_set_do_mid_side_stereo(OggFLAC__FileEncoder *encoder, FLAC__bool value);
/** This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_set_loose_mid_side_stereo().
/** This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_set_loose_mid_side_stereo().
*
* \default \c false
* \param encoder An encoder instance to set.
@ -235,8 +194,8 @@ FLAC__bool OggFLAC__file_encoder_set_do_mid_side_stereo(OggFLAC__FileEncoder *en
*/
FLAC__bool OggFLAC__file_encoder_set_loose_mid_side_stereo(OggFLAC__FileEncoder *encoder, FLAC__bool value);
/** This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_set_channels().
/** This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_set_channels().
*
* \default \c 2
* \param encoder An encoder instance to set.
@ -248,8 +207,8 @@ FLAC__bool OggFLAC__file_encoder_set_loose_mid_side_stereo(OggFLAC__FileEncoder
*/
FLAC__bool OggFLAC__file_encoder_set_channels(OggFLAC__FileEncoder *encoder, unsigned value);
/** This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_set_bits_per_sample().
/** This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_set_bits_per_sample().
*
* \warning
* Do not feed the encoder data that is wider than the value you
@ -265,8 +224,8 @@ FLAC__bool OggFLAC__file_encoder_set_channels(OggFLAC__FileEncoder *encoder, uns
*/
FLAC__bool OggFLAC__file_encoder_set_bits_per_sample(OggFLAC__FileEncoder *encoder, unsigned value);
/** This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_set_sample_rate().
/** This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_set_sample_rate().
*
* \default \c 44100
* \param encoder An encoder instance to set.
@ -278,8 +237,8 @@ FLAC__bool OggFLAC__file_encoder_set_bits_per_sample(OggFLAC__FileEncoder *encod
*/
FLAC__bool OggFLAC__file_encoder_set_sample_rate(OggFLAC__FileEncoder *encoder, unsigned value);
/** This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_set_blocksize().
/** This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_set_blocksize().
*
* \default \c 1152
* \param encoder An encoder instance to set.
@ -291,8 +250,8 @@ FLAC__bool OggFLAC__file_encoder_set_sample_rate(OggFLAC__FileEncoder *encoder,
*/
FLAC__bool OggFLAC__file_encoder_set_blocksize(OggFLAC__FileEncoder *encoder, unsigned value);
/** This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_set_max_lpc_order().
/** This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_set_max_lpc_order().
*
* \default \c 0
* \param encoder An encoder instance to set.
@ -304,8 +263,8 @@ FLAC__bool OggFLAC__file_encoder_set_blocksize(OggFLAC__FileEncoder *encoder, un
*/
FLAC__bool OggFLAC__file_encoder_set_max_lpc_order(OggFLAC__FileEncoder *encoder, unsigned value);
/** This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_set_qlp_coeff_precision().
/** This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_set_qlp_coeff_precision().
*
* \note
* In the current implementation, qlp_coeff_precision + bits_per_sample must
@ -321,8 +280,8 @@ FLAC__bool OggFLAC__file_encoder_set_max_lpc_order(OggFLAC__FileEncoder *encoder
*/
FLAC__bool OggFLAC__file_encoder_set_qlp_coeff_precision(OggFLAC__FileEncoder *encoder, unsigned value);
/** This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search().
/** This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_set_do_qlp_coeff_prec_search().
*
* \default \c false
* \param encoder An encoder instance to set.
@ -334,8 +293,8 @@ FLAC__bool OggFLAC__file_encoder_set_qlp_coeff_precision(OggFLAC__FileEncoder *e
*/
FLAC__bool OggFLAC__file_encoder_set_do_qlp_coeff_prec_search(OggFLAC__FileEncoder *encoder, FLAC__bool value);
/** This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_set_do_escape_coding().
/** This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_set_do_escape_coding().
*
* \default \c false
* \param encoder An encoder instance to set.
@ -347,8 +306,8 @@ FLAC__bool OggFLAC__file_encoder_set_do_qlp_coeff_prec_search(OggFLAC__FileEncod
*/
FLAC__bool OggFLAC__file_encoder_set_do_escape_coding(OggFLAC__FileEncoder *encoder, FLAC__bool value);
/** This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_set_do_exhaustive_model_search().
/** This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_set_do_exhaustive_model_search().
*
* \default \c false
* \param encoder An encoder instance to set.
@ -360,8 +319,8 @@ FLAC__bool OggFLAC__file_encoder_set_do_escape_coding(OggFLAC__FileEncoder *enco
*/
FLAC__bool OggFLAC__file_encoder_set_do_exhaustive_model_search(OggFLAC__FileEncoder *encoder, FLAC__bool value);
/** This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_set_min_residual_partition_order().
/** This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_set_min_residual_partition_order().
*
* \default \c 0
* \param encoder An encoder instance to set.
@ -373,8 +332,8 @@ FLAC__bool OggFLAC__file_encoder_set_do_exhaustive_model_search(OggFLAC__FileEnc
*/
FLAC__bool OggFLAC__file_encoder_set_min_residual_partition_order(OggFLAC__FileEncoder *encoder, unsigned value);
/** This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_set_max_residual_partition_order().
/** This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_set_max_residual_partition_order().
*
* \default \c 0
* \param encoder An encoder instance to set.
@ -386,8 +345,8 @@ FLAC__bool OggFLAC__file_encoder_set_min_residual_partition_order(OggFLAC__FileE
*/
FLAC__bool OggFLAC__file_encoder_set_max_residual_partition_order(OggFLAC__FileEncoder *encoder, unsigned value);
/** This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_set_rice_parameter_search_dist().
/** This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_set_rice_parameter_search_dist().
*
* \default \c 0
* \param encoder An encoder instance to set.
@ -399,8 +358,8 @@ FLAC__bool OggFLAC__file_encoder_set_max_residual_partition_order(OggFLAC__FileE
*/
FLAC__bool OggFLAC__file_encoder_set_rice_parameter_search_dist(OggFLAC__FileEncoder *encoder, unsigned value);
/** This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_set_total_samples_estimate().
/** This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_set_total_samples_estimate().
*
* \default \c 0
* \param encoder An encoder instance to set.
@ -412,8 +371,8 @@ FLAC__bool OggFLAC__file_encoder_set_rice_parameter_search_dist(OggFLAC__FileEnc
*/
FLAC__bool OggFLAC__file_encoder_set_total_samples_estimate(OggFLAC__FileEncoder *encoder, FLAC__uint64 value);
/** This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_set_metadata().
/** This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_set_metadata().
*
* \default \c NULL, 0
* \param encoder An encoder instance to set.
@ -426,14 +385,8 @@ FLAC__bool OggFLAC__file_encoder_set_total_samples_estimate(OggFLAC__FileEncoder
*/
FLAC__bool OggFLAC__file_encoder_set_metadata(OggFLAC__FileEncoder *encoder, OggFLAC__StreamMetadata **metadata, unsigned num_blocks);
/** Set the output file name encode to.
*
* \note
* The filename is mandatory and must be set before initialization.
*
* \note
* Unlike the OggFLAC__FileDecoder, the filename does not interpret "-" for
* \c stdout; writing to \c stdout is not relevant in the file encoder.
/** This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_set_filename().
*
* \default \c NULL
* \param encoder A encoder instance to set.
@ -448,14 +401,8 @@ FLAC__bool OggFLAC__file_encoder_set_metadata(OggFLAC__FileEncoder *encoder, Ogg
FLAC__bool OggFLAC__file_encoder_set_filename(OggFLAC__FileEncoder *encoder, const char *value);
/** Set the progress callback.
* The supplied function will be called when the encoder has finished
* writing a frame. The \c total_frames_estimate argument to the callback
* will be based on the value from
* OggFLAC__file_encoder_set_total_samples_estimate().
*
* \note
* Unlike most other callbacks, the progress callback is \b not mandatory
* and need not be set before initialization.
* This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_set_progress_callback().
*
* \default \c NULL
* \param encoder An encoder instance to set.
@ -492,48 +439,63 @@ FLAC__bool OggFLAC__file_encoder_set_client_data(OggFLAC__FileEncoder *encoder,
*/
OggFLAC__FileEncoderState OggFLAC__file_encoder_get_state(const OggFLAC__FileEncoder *encoder);
/** Get the state of the underlying seekable stream encoder.
/** Get the state of the underlying FLAC file encoder.
* Useful when the file encoder state is
* \c OggFLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR.
* \c OggFLAC__FILE_ENCODER_FLAC_FILE_ENCODER_ERROR.
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval OggFLAC__SeekableStreamEncoderState
* The seekable stream encoder state.
* \retval FLAC__FileEncoderState
* The FLAC file encoder state.
*/
OggFLAC__SeekableStreamEncoderState OggFLAC__file_encoder_get_seekable_stream_encoder_state(const OggFLAC__FileEncoder *encoder);
FLAC__FileEncoderState OggFLAC__file_encoder_get_FLAC_file_encoder_state(const OggFLAC__FileEncoder *encoder);
/** Get the state of the underlying stream encoder.
/** Get the state of the underlying FLAC file encoder's seekable stream encoder.
* Useful when the file encoder state is
* \c OggFLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR and the seekable stream
* encoder state is \c OggFLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR.
* \c OggFLAC__FILE_ENCODER_FLAC_FILE_ENCODER_ERROR and the FLAC file encoder state is
* \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_DECODER_ERROR.
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval OggFLAC__SeekableStreamEncoderState
* The seekable stream encoder state.
* \retval FLAC__SeekableStreamEncoderState
* The FLAC seekable stream encoder state.
*/
OggFLAC__StreamEncoderState OggFLAC__file_encoder_get_stream_encoder_state(const OggFLAC__FileEncoder *encoder);
FLAC__SeekableStreamEncoderState OggFLAC__file_encoder_get_FLAC_seekable_stream_encoder_state(const OggFLAC__FileEncoder *encoder);
/** Get the state of the underlying stream encoder's verify decoder.
/** Get the state of the underlying FLAC file encoder's stream encoder.
* Useful when the file encoder state is
* \c OggFLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR and the seekable stream
* encoder state is \c OggFLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and
* the stream encoder state is \c OggFLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
* \c OggFLAC__FILE_ENCODER_FLAC_FILE_ENCODER_ERROR and the FLAC file encoder state is
* \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_DECODER_ERROR and the
* FLAC seekable stream encoder state is \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR.
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval OggFLAC__StreamEncoderState
* The stream encoder state.
* \retval FLAC__StreamEncoderState
* The FLAC stream encoder state.
*/
OggFLAC__StreamDecoderState OggFLAC__file_encoder_get_verify_decoder_state(const OggFLAC__FileEncoder *encoder);
FLAC__StreamEncoderState OggFLAC__file_encoder_get_FLAC_stream_encoder_state(const OggFLAC__FileEncoder *encoder);
/** Get the state of the underlying FLAC file encoder's verify decoder.
* Useful when the file encoder state is
* \c OggFLAC__FILE_ENCODER_FLAC_FILE_ENCODER_ERROR and the FLAC file encoder state is
* \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_DECODER_ERROR and the
* FLAC seekable stream encoder state is \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR
* and the stream encoder state is \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__StreamDecoderState
* The FLAC verify decoder state.
*/
FLAC__StreamDecoderState OggFLAC__file_encoder_get_verify_decoder_state(const OggFLAC__FileEncoder *encoder);
/** Get the "verify" flag.
* This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_get_verify().
* This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_get_verify().
*
* \param encoder An encoder instance to query.
* \assert
@ -544,8 +506,8 @@ OggFLAC__StreamDecoderState OggFLAC__file_encoder_get_verify_decoder_state(const
FLAC__bool OggFLAC__file_encoder_get_verify(const OggFLAC__FileEncoder *encoder);
/** Get the "streamable subset" flag.
* This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_get_streamable_subset().
* This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_get_streamable_subset().
*
* \param encoder An encoder instance to query.
* \assert
@ -556,8 +518,8 @@ FLAC__bool OggFLAC__file_encoder_get_verify(const OggFLAC__FileEncoder *encoder)
FLAC__bool OggFLAC__file_encoder_get_streamable_subset(const OggFLAC__FileEncoder *encoder);
/** Get the "mid/side stereo coding" flag.
* This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_get_do_mid_side_stereo().
* This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_get_do_mid_side_stereo().
*
* \param encoder An encoder instance to query.
* \assert
@ -568,8 +530,8 @@ FLAC__bool OggFLAC__file_encoder_get_streamable_subset(const OggFLAC__FileEncode
FLAC__bool OggFLAC__file_encoder_get_do_mid_side_stereo(const OggFLAC__FileEncoder *encoder);
/** Get the "adaptive mid/side switching" flag.
* This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_get_loose_mid_side_stereo().
* This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_get_loose_mid_side_stereo().
*
* \param encoder An encoder instance to query.
* \assert
@ -580,8 +542,8 @@ FLAC__bool OggFLAC__file_encoder_get_do_mid_side_stereo(const OggFLAC__FileEncod
FLAC__bool OggFLAC__file_encoder_get_loose_mid_side_stereo(const OggFLAC__FileEncoder *encoder);
/** Get the number of input channels being processed.
* This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_get_channels().
* This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_get_channels().
*
* \param encoder An encoder instance to query.
* \assert
@ -592,8 +554,8 @@ FLAC__bool OggFLAC__file_encoder_get_loose_mid_side_stereo(const OggFLAC__FileEn
unsigned OggFLAC__file_encoder_get_channels(const OggFLAC__FileEncoder *encoder);
/** Get the input sample resolution setting.
* This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_get_bits_per_sample().
* This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_get_bits_per_sample().
*
* \param encoder An encoder instance to query.
* \assert
@ -604,8 +566,8 @@ unsigned OggFLAC__file_encoder_get_channels(const OggFLAC__FileEncoder *encoder)
unsigned OggFLAC__file_encoder_get_bits_per_sample(const OggFLAC__FileEncoder *encoder);
/** Get the input sample rate setting.
* This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_get_sample_rate().
* This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_get_sample_rate().
*
* \param encoder An encoder instance to query.
* \assert
@ -616,8 +578,8 @@ unsigned OggFLAC__file_encoder_get_bits_per_sample(const OggFLAC__FileEncoder *e
unsigned OggFLAC__file_encoder_get_sample_rate(const OggFLAC__FileEncoder *encoder);
/** Get the blocksize setting.
* This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_get_blocksize().
* This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_get_blocksize().
*
* \param encoder An encoder instance to query.
* \assert
@ -628,8 +590,8 @@ unsigned OggFLAC__file_encoder_get_sample_rate(const OggFLAC__FileEncoder *encod
unsigned OggFLAC__file_encoder_get_blocksize(const OggFLAC__FileEncoder *encoder);
/** Get the maximum LPC order setting.
* This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_get_max_lpc_order().
* This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_get_max_lpc_order().
*
* \param encoder An encoder instance to query.
* \assert
@ -640,8 +602,8 @@ unsigned OggFLAC__file_encoder_get_blocksize(const OggFLAC__FileEncoder *encoder
unsigned OggFLAC__file_encoder_get_max_lpc_order(const OggFLAC__FileEncoder *encoder);
/** Get the quantized linear predictor coefficient precision setting.
* This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_get_qlp_coeff_precision().
* This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_get_qlp_coeff_precision().
*
* \param encoder An encoder instance to query.
* \assert
@ -652,8 +614,8 @@ unsigned OggFLAC__file_encoder_get_max_lpc_order(const OggFLAC__FileEncoder *enc
unsigned OggFLAC__file_encoder_get_qlp_coeff_precision(const OggFLAC__FileEncoder *encoder);
/** Get the qlp coefficient precision search flag.
* This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search().
* This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_get_do_qlp_coeff_prec_search().
*
* \param encoder An encoder instance to query.
* \assert
@ -664,8 +626,8 @@ unsigned OggFLAC__file_encoder_get_qlp_coeff_precision(const OggFLAC__FileEncode
FLAC__bool OggFLAC__file_encoder_get_do_qlp_coeff_prec_search(const OggFLAC__FileEncoder *encoder);
/** Get the "escape coding" flag.
* This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_get_do_escape_coding().
* This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_get_do_escape_coding().
*
* \param encoder An encoder instance to query.
* \assert
@ -676,8 +638,8 @@ FLAC__bool OggFLAC__file_encoder_get_do_qlp_coeff_prec_search(const OggFLAC__Fil
FLAC__bool OggFLAC__file_encoder_get_do_escape_coding(const OggFLAC__FileEncoder *encoder);
/** Get the exhaustive model search flag.
* This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_get_do_exhaustive_model_search().
* This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_get_do_exhaustive_model_search().
*
* \param encoder An encoder instance to query.
* \assert
@ -688,8 +650,8 @@ FLAC__bool OggFLAC__file_encoder_get_do_escape_coding(const OggFLAC__FileEncoder
FLAC__bool OggFLAC__file_encoder_get_do_exhaustive_model_search(const OggFLAC__FileEncoder *encoder);
/** Get the minimum residual partition order setting.
* This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_get_min_residual_partition_order().
* This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_get_min_residual_partition_order().
*
* \param encoder An encoder instance to query.
* \assert
@ -700,8 +662,8 @@ FLAC__bool OggFLAC__file_encoder_get_do_exhaustive_model_search(const OggFLAC__F
unsigned OggFLAC__file_encoder_get_min_residual_partition_order(const OggFLAC__FileEncoder *encoder);
/** Get maximum residual partition order setting.
* This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_get_max_residual_partition_order().
* This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_get_max_residual_partition_order().
*
* \param encoder An encoder instance to query.
* \assert
@ -712,8 +674,8 @@ unsigned OggFLAC__file_encoder_get_min_residual_partition_order(const OggFLAC__F
unsigned OggFLAC__file_encoder_get_max_residual_partition_order(const OggFLAC__FileEncoder *encoder);
/** Get the Rice parameter search distance setting.
* This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_get_rice_parameter_search_dist().
* This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_get_rice_parameter_search_dist().
*
* \param encoder An encoder instance to query.
* \assert
@ -724,8 +686,8 @@ unsigned OggFLAC__file_encoder_get_max_residual_partition_order(const OggFLAC__F
unsigned OggFLAC__file_encoder_get_rice_parameter_search_dist(const OggFLAC__FileEncoder *encoder);
/** Get the previously set estimate of the total samples to be encoded.
* This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_get_total_samples_estimate().
* This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_get_total_samples_estimate().
*
* \param encoder An encoder instance to query.
* \assert
@ -759,7 +721,7 @@ OggFLAC__FileEncoderState OggFLAC__file_encoder_init(OggFLAC__FileEncoder *encod
* In the event of a prematurely-terminated encode, it is not strictly
* necessary to call this immediately before OggFLAC__file_encoder_delete()
* but it is good practice to match every OggFLAC__file_encoder_init()
* with a OggFLAC__file_encoder_finish().
* with an OggFLAC__file_encoder_finish().
*
* \param encoder An uninitialized encoder instance.
* \assert
@ -768,8 +730,8 @@ OggFLAC__FileEncoderState OggFLAC__file_encoder_init(OggFLAC__FileEncoder *encod
void OggFLAC__file_encoder_finish(OggFLAC__FileEncoder *encoder);
/** Submit data for encoding.
* This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_process().
* This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_process().
*
* \param encoder An initialized encoder instance in the OK state.
* \param buffer An array of pointers to each channel's signal.
@ -785,8 +747,8 @@ void OggFLAC__file_encoder_finish(OggFLAC__FileEncoder *encoder);
FLAC__bool OggFLAC__file_encoder_process(OggFLAC__FileEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
/** Submit data for encoding.
* This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_process_interleaved().
* This is inherited from FLAC__FileEncoder; see
* FLAC__file_encoder_process_interleaved().
*
* \param encoder An initialized encoder instance in the OK state.
* \param buffer An array of channel-interleaved data (see above).

361
include/OggFLAC/seekable_stream_decoder.h
View File

@ -44,210 +44,56 @@ extern "C" {
* This module contains the functions which implement the seekable stream
* decoder.
*
* The basic usage of this decoder is as follows:
* - The program creates an instance of a decoder using
* OggFLAC__seekable_stream_decoder_new().
* - The program overrides the default settings and sets callbacks for
* reading, writing, seeking, error reporting, and metadata reporting
* using OggFLAC__seekable_stream_decoder_set_*() functions.
* - The program initializes the instance to validate the settings and
* prepare for decoding using OggFLAC__seekable_stream_decoder_init().
* - The program calls the OggFLAC__seekable_stream_decoder_process_*()
* functions to decode data, which subsequently calls the callbacks.
* - The program finishes the decoding with
* OggFLAC__seekable_stream_decoder_finish(), which flushes the input and
* output and resets the decoder to the uninitialized state.
* - The instance may be used again or deleted with
* OggFLAC__seekable_stream_decoder_delete().
*
* The seekable stream decoder is a wrapper around the
* \link oggflac_stream_decoder stream decoder \endlink which also provides
* seeking capability. In addition to the Read/Write/Metadata/Error
* callbacks of the stream decoder, the user must also provide the following:
*
* - Seek callback - This function will be called when the decoder wants to
* seek to an absolute position in the stream.
* - Tell callback - This function will be called when the decoder wants to
* know the current absolute position of the stream.
* - Length callback - This function will be called when the decoder wants
* to know length of the stream. The seeking algorithm currently requires
* that the overall stream length be known.
* - EOF callback - This function will be called when the decoder wants to
* know if it is at the end of the stream. This could be synthesized from
* the tell and length callbacks but it may be more expensive that way, so
* there is a separate callback for it.
*
* Seeking is exposed through the
* OggFLAC__seekable_stream_decoder_seek_absolute() method. At any point after
* the seekable stream decoder has been initialized, the user can call this
* function to seek to an exact sample within the stream. Subsequently, the
* first time the write callback is called it will be passed a (possibly
* partial) block starting at that sample.
*
* The seekable stream decoder also provides MD5 signature checking. If
* this is turned on before initialization,
* OggFLAC__seekable_stream_decoder_finish() will report when the decoded MD5
* signature does not match the one stored in the STREAMINFO block. MD5
* checking is automatically turned off (until the next
* OggFLAC__seekable_stream_decoder_reset()) if there is no signature in the
* STREAMINFO block or when a seek is attempted.
*
* Make sure to read the detailed description of the
* \link oggflac_stream_decoder stream decoder module \endlink since the
* seekable stream decoder inherits much of its behavior.
*
* \note
* The "set" functions may only be called when the decoder is in the
* state OggFLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED, i.e. after
* OggFLAC__seekable_stream_decoder_new() or
* OggFLAC__seekable_stream_decoder_finish(), but before
* OggFLAC__seekable_stream_decoder_init(). If this is the case they will
* return \c true, otherwise \c false.
*
* \note
* OggFLAC__stream_decoder_finish() resets all settings to the constructor
* defaults, including the callbacks.
* The interface here is identical to FLAC's seekable stream decoder. See the
* defaults, including the callbacks. See the \link flac_seekable_stream_decoder
* FLAC seekable stream decoder module \endlink for full documentation.
*
* \{
*/
/** State values for a OggFLAC__SeekableStreamDecoder
/** State values for an OggFLAC__SeekableStreamDecoder
*
* The decoder's state can be obtained by calling OggFLAC__seekable_stream_decoder_get_state().
*/
typedef enum {
OggFLAC__SEEKABLE_STREAM_DECODER_OK = 0,
OggFLAC__SEEKABLE_STREAM_DECODER_OK = 0,
/**< The decoder is in the normal OK state. */
OggFLAC__SEEKABLE_STREAM_DECODER_SEEKING,
/**< The decoder is in the process of seeking. */
OggFLAC__SEEKABLE_STREAM_DECODER_END_OF_STREAM,
/**< The decoder has reached the end of the stream. */
OggFLAC__SEEKABLE_STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
/**< An error occurred allocating memory. */
OggFLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR,
/**< An error occurred in the underlying stream decoder. */
OggFLAC__SEEKABLE_STREAM_DECODER_READ_ERROR,
/**< The read callback returned an error. */
OggFLAC__SEEKABLE_STREAM_DECODER_SEEK_ERROR,
/**< An error occurred while seeking or the seek or tell
* callback returned an error.
OggFLAC__SEEKABLE_STREAM_DECODER_FLAC_SEEKABLE_STREAM_DECODER_ERROR,
/**< An error occurred in the underlying FLAC seekable stream decoder;
* check OggFLAC__seekable_stream_decoder_get_FLAC_seekable_stream_decoder_state().
*/
OggFLAC__SEEKABLE_STREAM_DECODER_ALREADY_INITIALIZED,
/**< OggFLAC__seekable_stream_decoder_init() was called when the
* decoder was already initialized, usually because
OggFLAC__SEEKABLE_STREAM_DECODER_INVALID_CALLBACK,
/**< The decoder was initialized before setting all the required callbacks. */
OggFLAC__SEEKABLE_STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
/**< Memory allocation failed. */
OggFLAC__SEEKABLE_STREAM_DECODER_ALREADY_INITIALIZED,
/**< OggFLAC__seekable_stream_decoder_init() was called when the decoder was
* already initialized, usually because
* OggFLAC__seekable_stream_decoder_finish() was not called.
*/
OggFLAC__SEEKABLE_STREAM_DECODER_INVALID_CALLBACK,
/**< OggFLAC__seekable_stream_decoder_init() was called without all
* callbacks being set.
*/
OggFLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED
OggFLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED
/**< The decoder is in the uninitialized state. */
} OggFLAC__SeekableStreamDecoderState;
/** Maps a OggFLAC__SeekableStreamDecoderState to a C string.
/** Maps an OggFLAC__SeekableStreamDecoderState to a C string.
*
* Using a OggFLAC__SeekableStreamDecoderState as the index to this array
* Using an OggFLAC__SeekableStreamDecoderState as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern const char * const OggFLAC__SeekableStreamDecoderStateString[];
/** Return values for the OggFLAC__SeekableStreamDecoder read callback.
*/
typedef enum {
OggFLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_OK,
/**< The read was OK and decoding can continue. */
OggFLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_ERROR
/**< An unrecoverable error occurred. The decoder will return from the process call. */
} OggFLAC__SeekableStreamDecoderReadStatus;
/** Maps a OggFLAC__SeekableStreamDecoderReadStatus to a C string.
*
* Using a OggFLAC__SeekableStreamDecoderReadStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern const char * const OggFLAC__SeekableStreamDecoderReadStatusString[];
/** Return values for the OggFLAC__SeekableStreamDecoder seek callback.
*/
typedef enum {
OggFLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_OK,
/**< The seek was OK and decoding can continue. */
OggFLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_ERROR
/**< An unrecoverable error occurred. The decoder will return from the process call. */
} OggFLAC__SeekableStreamDecoderSeekStatus;
/** Maps a OggFLAC__SeekableStreamDecoderSeekStatus to a C string.
*
* Using a OggFLAC__SeekableStreamDecoderSeekStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern const char * const OggFLAC__SeekableStreamDecoderSeekStatusString[];
/** Return values for the OggFLAC__SeekableStreamDecoder tell callback.
*/
typedef enum {
OggFLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_OK,
/**< The tell was OK and decoding can continue. */
OggFLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_ERROR
/**< An unrecoverable error occurred. The decoder will return from the process call. */
} OggFLAC__SeekableStreamDecoderTellStatus;
/** Maps a OggFLAC__SeekableStreamDecoderTellStatus to a C string.
*
* Using a OggFLAC__SeekableStreamDecoderTellStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern const char * const OggFLAC__SeekableStreamDecoderTellStatusString[];
/** Return values for the OggFLAC__SeekableStreamDecoder length callback.
*/
typedef enum {
OggFLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_OK,
/**< The length call was OK and decoding can continue. */
OggFLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_ERROR
/**< An unrecoverable error occurred. The decoder will return from the process call. */
} OggFLAC__SeekableStreamDecoderLengthStatus;
/** Maps a OggFLAC__SeekableStreamDecoderLengthStatus to a C string.
*
* Using a OggFLAC__SeekableStreamDecoderLengthStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern const char * const OggFLAC__SeekableStreamDecoderLengthStatusString[];
/***********************************************************************
*
* class OggFLAC__SeekableStreamDecoder : public OggFLAC__StreamDecoder
* class OggFLAC__SeekableStreamDecoder : public FLAC__StreamDecoder
*
***********************************************************************/
@ -264,14 +110,14 @@ typedef struct {
} OggFLAC__SeekableStreamDecoder;
/*@@@ document */
typedef OggFLAC__SeekableStreamDecoderReadStatus (*OggFLAC__SeekableStreamDecoderReadCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
typedef OggFLAC__SeekableStreamDecoderSeekStatus (*OggFLAC__SeekableStreamDecoderSeekCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
typedef OggFLAC__SeekableStreamDecoderTellStatus (*OggFLAC__SeekableStreamDecoderTellCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
typedef OggFLAC__SeekableStreamDecoderLengthStatus (*OggFLAC__SeekableStreamDecoderLengthCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
typedef FLAC__SeekableStreamDecoderReadStatus (*OggFLAC__SeekableStreamDecoderReadCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
typedef FLAC__SeekableStreamDecoderSeekStatus (*OggFLAC__SeekableStreamDecoderSeekCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
typedef FLAC__SeekableStreamDecoderTellStatus (*OggFLAC__SeekableStreamDecoderTellCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
typedef FLAC__SeekableStreamDecoderLengthStatus (*OggFLAC__SeekableStreamDecoderLengthCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
typedef FLAC__bool (*OggFLAC__SeekableStreamDecoderEofCallback)(const OggFLAC__SeekableStreamDecoder *decoder, void *client_data);
typedef OggFLAC__StreamDecoderWriteStatus (*OggFLAC__SeekableStreamDecoderWriteCallback)(const OggFLAC__SeekableStreamDecoder *decoder, const OggFLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
typedef void (*OggFLAC__SeekableStreamDecoderMetadataCallback)(const OggFLAC__SeekableStreamDecoder *decoder, const OggFLAC__StreamMetadata *metadata, void *client_data);
typedef void (*OggFLAC__SeekableStreamDecoderErrorCallback)(const OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__StreamDecoderErrorStatus status, void *client_data);
typedef FLAC__StreamDecoderWriteStatus (*OggFLAC__SeekableStreamDecoderWriteCallback)(const OggFLAC__SeekableStreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
typedef void (*OggFLAC__SeekableStreamDecoderMetadataCallback)(const OggFLAC__SeekableStreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
typedef void (*OggFLAC__SeekableStreamDecoderErrorCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
/***********************************************************************
@ -305,14 +151,9 @@ void OggFLAC__seekable_stream_decoder_delete(OggFLAC__SeekableStreamDecoder *dec
*
***********************************************************************/
/** Set the "MD5 signature checking" flag. If \c true, the decoder will
* compute the MD5 signature of the unencoded audio data while decoding
* and compare it to the signature from the STREAMINFO block, if it
* exists, during OggFLAC__seekable_stream_decoder_finish().
*
* MD5 signature checking will be turned off (until the next
* OggFLAC__seekable_stream_decoder_reset()) if there is no signature in
* the STREAMINFO block or when a seek is attempted.
/** Set the "MD5 signature checking" flag.
* This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_md5_checking().
*
* \default \c false
* \param decoder A decoder instance to set.
@ -325,8 +166,8 @@ void OggFLAC__seekable_stream_decoder_delete(OggFLAC__SeekableStreamDecoder *dec
FLAC__bool OggFLAC__seekable_stream_decoder_set_md5_checking(OggFLAC__SeekableStreamDecoder *decoder, FLAC__bool value);
/** Set the read callback.
* This is inherited from OggFLAC__StreamDecoder; see
* OggFLAC__stream_decoder_set_read_callback().
* This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_read_callback().
*
* \note
* The callback is mandatory and must be set before initialization.
@ -343,9 +184,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_md5_checking(OggFLAC__SeekableSt
FLAC__bool OggFLAC__seekable_stream_decoder_set_read_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderReadCallback value);
/** Set the seek callback.
* The supplied function will be called when the decoder needs to seek
* the input stream. The decoder will pass the absolute byte offset
* to seek to, 0 meaning the beginning of the stream.
* This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_seek_callback().
*
* \note
* The callback is mandatory and must be set before initialization.
@ -362,9 +202,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_read_callback(OggFLAC__SeekableS
FLAC__bool OggFLAC__seekable_stream_decoder_set_seek_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderSeekCallback value);
/** Set the tell callback.
* The supplied function will be called when the decoder wants to know
* the current position of the stream. The callback should return the
* byte offset from the beginning of the stream.
* This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_tell_callback().
*
* \note
* The callback is mandatory and must be set before initialization.
@ -381,8 +220,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_seek_callback(OggFLAC__SeekableS
FLAC__bool OggFLAC__seekable_stream_decoder_set_tell_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderTellCallback value);
/** Set the length callback.
* The supplied function will be called when the decoder wants to know
* the total length of the stream in bytes.
* This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_length_callback().
*
* \note
* The callback is mandatory and must be set before initialization.
@ -399,8 +238,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_tell_callback(OggFLAC__SeekableS
FLAC__bool OggFLAC__seekable_stream_decoder_set_length_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderLengthCallback value);
/** Set the eof callback.
* The supplied function will be called when the decoder needs to know
* if the end of the stream has been reached.
* This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_eof_callback().
*
* \note
* The callback is mandatory and must be set before initialization.
@ -417,8 +256,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_length_callback(OggFLAC__Seekabl
FLAC__bool OggFLAC__seekable_stream_decoder_set_eof_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderEofCallback value);
/** Set the write callback.
* This is inherited from OggFLAC__StreamDecoder; see
* OggFLAC__stream_decoder_set_write_callback().
* This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_write_callback().
*
* \note
* The callback is mandatory and must be set before initialization.
@ -435,8 +274,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_eof_callback(OggFLAC__SeekableSt
FLAC__bool OggFLAC__seekable_stream_decoder_set_write_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderWriteCallback value);
/** Set the metadata callback.
* This is inherited from OggFLAC__StreamDecoder; see
* OggFLAC__stream_decoder_set_metadata_callback().
* This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_metadata_callback().
*
* \note
* The callback is mandatory and must be set before initialization.
@ -453,8 +292,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_write_callback(OggFLAC__Seekable
FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderMetadataCallback value);
/** Set the error callback.
* This is inherited from OggFLAC__StreamDecoder; see
* OggFLAC__stream_decoder_set_error_callback().
* This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_error_callback().
*
* \note
* The callback is mandatory and must be set before initialization.
@ -484,8 +323,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_error_callback(OggFLAC__Seekable
*/
FLAC__bool OggFLAC__seekable_stream_decoder_set_client_data(OggFLAC__SeekableStreamDecoder *decoder, void *value);
/** This is inherited from OggFLAC__StreamDecoder; see
* OggFLAC__stream_decoder_set_metadata_respond().
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_metadata_respond().
*
* \default By default, only the \c STREAMINFO block is returned via the
* metadata callback.
@ -499,8 +338,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_client_data(OggFLAC__SeekableStr
*/
FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_respond(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__MetadataType type);
/** This is inherited from OggFLAC__StreamDecoder; see
* OggFLAC__stream_decoder_set_metadata_respond_application().
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_metadata_respond_application().
*
* \default By default, only the \c STREAMINFO block is returned via the
* metadata callback.
@ -514,8 +353,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_respond(OggFLAC__Seekab
*/
FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_respond_application(OggFLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
/** This is inherited from OggFLAC__StreamDecoder; see
* OggFLAC__stream_decoder_set_metadata_respond_all().
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_metadata_respond_all().
*
* \default By default, only the \c STREAMINFO block is returned via the
* metadata callback.
@ -527,8 +366,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_respond_application(Ogg
*/
FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_respond_all(OggFLAC__SeekableStreamDecoder *decoder);
/** This is inherited from OggFLAC__StreamDecoder; see
* OggFLAC__stream_decoder_set_metadata_ignore().
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_metadata_ignore().
*
* \default By default, only the \c STREAMINFO block is returned via the
* metadata callback.
@ -542,8 +381,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_respond_all(OggFLAC__Se
*/
FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_ignore(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__MetadataType type);
/** This is inherited from OggFLAC__StreamDecoder; see
* OggFLAC__stream_decoder_set_metadata_ignore_application().
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_metadata_ignore_application().
*
* \default By default, only the \c STREAMINFO block is returned via the
* metadata callback.
@ -557,8 +396,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_ignore(OggFLAC__Seekabl
*/
FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_ignore_application(OggFLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
/** This is inherited from OggFLAC__StreamDecoder; see
* OggFLAC__stream_decoder_set_metadata_ignore_all().
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_metadata_ignore_all().
*
* \default By default, only the \c STREAMINFO block is returned via the
* metadata callback.
@ -580,23 +419,33 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_ignore_all(OggFLAC__See
*/
OggFLAC__SeekableStreamDecoderState OggFLAC__seekable_stream_decoder_get_state(const OggFLAC__SeekableStreamDecoder *decoder);
/** Get the state of the underlying stream decoder.
/** Get the state of the underlying FLAC seekable stream decoder.
* Useful when the seekable stream decoder state is
* \c OggFLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
* \c OggFLAC__SEEKABLE_STREAM_DECODER_FLAC_SEEKABLE_STREAM_DECODER_ERROR.
*
* \param decoder An decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval OggFLAC__StreamDecoderState
* The stream decoder state.
* \retval FLAC__SeekableStreamDecoderState
* The FLAC seekable stream decoder state.
*/
OggFLAC__StreamDecoderState OggFLAC__seekable_stream_decoder_get_stream_decoder_state(const OggFLAC__SeekableStreamDecoder *decoder);
FLAC__SeekableStreamDecoderState OggFLAC__seekable_stream_decoder_get_FLAC_seekable_stream_decoder_state(const OggFLAC__SeekableStreamDecoder *decoder);
/** Get the "MD5 signature checking" flag.
* This is the value of the setting, not whether or not the decoder is
* currently checking the MD5 (remember, it can be turned off automatically
* by a seek). When the decoder is reset the flag will be restored to the
* value returned by this function.
/** Get the state of the underlying FLAC seekable stream decoder's stream decoder.
* Useful when the seekable stream decoder state is
* \c OggFLAC__SEEKABLE_STREAM_DECODER_FLAC_SEEKABLE_STREAM_DECODER_ERROR and the
* FLAC seekable stream decoder state is \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR
*
* \param decoder An decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__StreamDecoderState
* The FLAC stream decoder state.
*/
FLAC__StreamDecoderState OggFLAC__seekable_stream_decoder_get_FLAC_stream_decoder_state(const OggFLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_md5_checking().
*
* \param decoder A decoder instance to query.
* \assert
@ -606,8 +455,8 @@ OggFLAC__StreamDecoderState OggFLAC__seekable_stream_decoder_get_stream_decoder_
*/
FLAC__bool OggFLAC__seekable_stream_decoder_get_md5_checking(const OggFLAC__SeekableStreamDecoder *decoder);
/** This is inherited from OggFLAC__StreamDecoder; see
* OggFLAC__stream_decoder_get_channels().
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_channels().
*
* \param decoder A decoder instance to query.
* \assert
@ -617,8 +466,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_get_md5_checking(const OggFLAC__Seek
*/
unsigned OggFLAC__seekable_stream_decoder_get_channels(const OggFLAC__SeekableStreamDecoder *decoder);
/** This is inherited from OggFLAC__StreamDecoder; see
* OggFLAC__stream_decoder_get_channel_assignment().
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_channel_assignment().
*
* \param decoder A decoder instance to query.
* \assert
@ -628,8 +477,8 @@ unsigned OggFLAC__seekable_stream_decoder_get_channels(const OggFLAC__SeekableSt
*/
OggFLAC__ChannelAssignment OggFLAC__seekable_stream_decoder_get_channel_assignment(const OggFLAC__SeekableStreamDecoder *decoder);
/** This is inherited from OggFLAC__StreamDecoder; see
* OggFLAC__stream_decoder_get_bits_per_sample().
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_bits_per_sample().
*
* \param decoder A decoder instance to query.
* \assert
@ -639,8 +488,8 @@ OggFLAC__ChannelAssignment OggFLAC__seekable_stream_decoder_get_channel_assignme
*/
unsigned OggFLAC__seekable_stream_decoder_get_bits_per_sample(const OggFLAC__SeekableStreamDecoder *decoder);
/** This is inherited from OggFLAC__StreamDecoder; see
* OggFLAC__stream_decoder_get_sample_rate().
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_sample_rate().
*
* \param decoder A decoder instance to query.
* \assert
@ -650,8 +499,8 @@ unsigned OggFLAC__seekable_stream_decoder_get_bits_per_sample(const OggFLAC__See
*/
unsigned OggFLAC__seekable_stream_decoder_get_sample_rate(const OggFLAC__SeekableStreamDecoder *decoder);
/** This is inherited from OggFLAC__StreamDecoder; see
* OggFLAC__stream_decoder_get_blocksize().
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_blocksize().
*
* \param decoder A decoder instance to query.
* \assert
@ -700,10 +549,8 @@ OggFLAC__SeekableStreamDecoderState OggFLAC__seekable_stream_decoder_init(OggFLA
*/
FLAC__bool OggFLAC__seekable_stream_decoder_finish(OggFLAC__SeekableStreamDecoder *decoder);
/** Flush the stream input.
* The decoder's input buffer will be cleared and the state set to
* \c OggFLAC__SEEKABLE_STREAM_DECODER_OK. This will also turn off MD5
* checking.
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_flush().
*
* \param decoder A decoder instance.
* \assert
@ -714,13 +561,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_finish(OggFLAC__SeekableStreamDecode
*/
FLAC__bool OggFLAC__seekable_stream_decoder_flush(OggFLAC__SeekableStreamDecoder *decoder);
/** Reset the decoding process.
* The decoder's input buffer will be cleared and the state set to
* \c OggFLAC__SEEKABLE_STREAM_DECODER_OK. This is similar to
* OggFLAC__seekable_stream_decoder_finish() except that the settings are
* preserved; there is no need to call OggFLAC__seekable_stream_decoder_init()
* before decoding again. MD5 checking will be restored to its original
* setting.
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_reset().
*
* \param decoder A decoder instance.
* \assert
@ -731,8 +573,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_flush(OggFLAC__SeekableStreamDecoder
*/
FLAC__bool OggFLAC__seekable_stream_decoder_reset(OggFLAC__SeekableStreamDecoder *decoder);
/** This is inherited from OggFLAC__StreamDecoder; see
* OggFLAC__stream_decoder_process_single().
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_process_single().
*
* \param decoder A decoder instance.
* \assert
@ -742,8 +584,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_reset(OggFLAC__SeekableStreamDecoder
*/
FLAC__bool OggFLAC__seekable_stream_decoder_process_single(OggFLAC__SeekableStreamDecoder *decoder);
/** This is inherited from OggFLAC__StreamDecoder; see
* OggFLAC__stream_decoder_process_until_end_of_metadata().
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_process_until_end_of_metadata().
*
* \param decoder A decoder instance.
* \assert
@ -753,8 +595,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_process_single(OggFLAC__SeekableStre
*/
FLAC__bool OggFLAC__seekable_stream_decoder_process_until_end_of_metadata(OggFLAC__SeekableStreamDecoder *decoder);
/** This is inherited from OggFLAC__StreamDecoder; see
* OggFLAC__stream_decoder_process_until_end_of_stream().
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_process_until_end_of_stream().
*
* \param decoder A decoder instance.
* \assert
@ -764,9 +606,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_process_until_end_of_metadata(OggFLA
*/
FLAC__bool OggFLAC__seekable_stream_decoder_process_until_end_of_stream(OggFLAC__SeekableStreamDecoder *decoder);
/** Flush the input and seek to an absolute sample.
* Decoding will resume at the given sample. Note that because of
* this, the next write callback may contain a partial block.
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_seek_absolute().
*
* \param decoder A decoder instance.
* \param sample The target sample number to seek to.

250
include/OggFLAC/seekable_stream_encoder.h
View File

@ -44,31 +44,15 @@ extern "C" {
* This module contains the functions which implement the seekable stream
* encoder.
*
* XXX (import)
*
* The seekable stream encoder is a wrapper around the
* \link oggflac_stream_encoder stream encoder \endlink which (XXXimport)
*
* Make sure to read the detailed description of the
* \link oggflac_stream_encoder stream encoder module \endlink since the
* seekable stream encoder inherits much of its behavior.
*
* \note
* The "set" functions may only be called when the encoder is in the
* state OggFLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED, i.e. after
* OggFLAC__seekable_stream_encoder_new() or OggFLAC__seekable_stream_encoder_finish(), but
* before OggFLAC__seekable_stream_encoder_init(). If this is the case they will
* return \c true, otherwise \c false.
*
* \note
* OggFLAC__seekable_stream_encoder_finish() resets all settings to the constructor
* defaults, including the callbacks.
* The interface here is identical to FLAC's seekable stream encoder. See the
* defaults, including the callbacks. See the \link flac_seekable_stream_encoder
* FLAC seekable stream encoder module \endlink for full documentation.
*
* \{
*/
/** State values for a OggFLAC__SeekableStreamEncoder
/** State values for an OggFLAC__SeekableStreamEncoder
*
* The encoder's state can be obtained by calling OggFLAC__seekable_stream_encoder_get_state().
*/
@ -77,47 +61,31 @@ typedef enum {
OggFLAC__SEEKABLE_STREAM_ENCODER_OK = 0,
/**< The encoder is in the normal OK state. */
OggFLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR,
/**< An error occurred in the underlying stream encoder;
* check OggFLAC__seekable_stream_encoder_get_stream_encoder_state().
OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_SEEKABLE_STREAM_ENCODER_ERROR,
/**< An error occurred in the underlying FLAC seekable stream encoder;
* check OggFLAC__seekable_stream_encoder_get_FLAC_seekable_stream_encoder_state().
*/
OggFLAC__SEEKABLE_STREAM_ENCODER_INVALID_CALLBACK,
/**< The encoder was initialized before setting all the required callbacks. */
OggFLAC__SEEKABLE_STREAM_ENCODER_MEMORY_ALLOCATION_ERROR,
/**< Memory allocation failed. */
OggFLAC__SEEKABLE_STREAM_ENCODER_WRITE_ERROR,
/**< The write callback returned an error. */
OggFLAC__SEEKABLE_STREAM_ENCODER_READ_ERROR,
/**< The read callback returned an error. */
OggFLAC__SEEKABLE_STREAM_ENCODER_SEEK_ERROR,
/**< The seek callback returned an error. */
OggFLAC__SEEKABLE_STREAM_ENCODER_ALREADY_INITIALIZED,
/**< OggFLAC__seekable_stream_encoder_init() was called when the encoder was
* already initialized, usually because
* OggFLAC__seekable_stream_encoder_finish() was not called.
*/
OggFLAC__SEEKABLE_STREAM_ENCODER_INVALID_CALLBACK,
/**< OggFLAC__seekable_stream_encoder_init() was called without all
* callbacks being set.
*/
OggFLAC__SEEKABLE_STREAM_ENCODER_INVALID_SEEKTABLE,
/**< An invalid seek table was passed is the metadata to
* OggFLAC__seekable_stream_encoder_set_metadata().
*/
OggFLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED
/**< The encoder is in the uninitialized state. */
} OggFLAC__SeekableStreamEncoderState;
/** Maps a OggFLAC__SeekableStreamEncoderState to a C string.
/** Maps an OggFLAC__SeekableStreamEncoderState to a C string.
*
* Using a OggFLAC__SeekableStreamEncoderState as the index to this array
* Using an OggFLAC__SeekableStreamEncoderState as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
/* @@@@ double-check mapping */
@ -136,9 +104,9 @@ typedef enum {
} OggFLAC__SeekableStreamEncoderSeekStatus;
/** Maps a OggFLAC__SeekableStreamEncoderSeekStatus to a C string.
/** Maps an OggFLAC__SeekableStreamEncoderSeekStatus to a C string.
*
* Using a OggFLAC__SeekableStreamEncoderSeekStatus as the index to this array
* Using an OggFLAC__SeekableStreamEncoderSeekStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern const char * const OggFLAC__SeekableStreamEncoderSeekStatusString[];
@ -195,8 +163,8 @@ void OggFLAC__seekable_stream_encoder_delete(OggFLAC__SeekableStreamEncoder *enc
*
***********************************************************************/
/** This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_set_verify().
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_verify().
*
* \default \c true
* \param encoder An encoder instance to set.
@ -208,8 +176,8 @@ void OggFLAC__seekable_stream_encoder_delete(OggFLAC__SeekableStreamEncoder *enc
*/
FLAC__bool OggFLAC__seekable_stream_encoder_set_verify(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
/** This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_set_streamable_subset().
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_streamable_subset().
*
* \default \c true
* \param encoder An encoder instance to set.
@ -221,8 +189,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_verify(OggFLAC__SeekableStreamEn
*/
FLAC__bool OggFLAC__seekable_stream_encoder_set_streamable_subset(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
/** This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_set_do_mid_side_stereo().
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_do_mid_side_stereo().
*
* \default \c false
* \param encoder An encoder instance to set.
@ -234,8 +202,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_streamable_subset(OggFLAC__Seeka
*/
FLAC__bool OggFLAC__seekable_stream_encoder_set_do_mid_side_stereo(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
/** This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_set_loose_mid_side_stereo().
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_loose_mid_side_stereo().
*
* \default \c false
* \param encoder An encoder instance to set.
@ -247,8 +215,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_do_mid_side_stereo(OggFLAC__Seek
*/
FLAC__bool OggFLAC__seekable_stream_encoder_set_loose_mid_side_stereo(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
/** This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_set_channels().
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_channels().
*
* \default \c 2
* \param encoder An encoder instance to set.
@ -260,8 +228,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_loose_mid_side_stereo(OggFLAC__S
*/
FLAC__bool OggFLAC__seekable_stream_encoder_set_channels(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
/** This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_set_bits_per_sample().
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_bits_per_sample().
*
* \warning
* Do not feed the encoder data that is wider than the value you
@ -277,8 +245,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_channels(OggFLAC__SeekableStream
*/
FLAC__bool OggFLAC__seekable_stream_encoder_set_bits_per_sample(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
/** This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_set_sample_rate().
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_sample_rate().
*
* \default \c 44100
* \param encoder An encoder instance to set.
@ -290,8 +258,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_bits_per_sample(OggFLAC__Seekabl
*/
FLAC__bool OggFLAC__seekable_stream_encoder_set_sample_rate(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
/** This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_set_blocksize().
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_blocksize().
*
* \default \c 1152
* \param encoder An encoder instance to set.
@ -303,8 +271,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_sample_rate(OggFLAC__SeekableStr
*/
FLAC__bool OggFLAC__seekable_stream_encoder_set_blocksize(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
/** This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_set_max_lpc_order().
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_max_lpc_order().
*
* \default \c 0
* \param encoder An encoder instance to set.
@ -316,8 +284,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_blocksize(OggFLAC__SeekableStrea
*/
FLAC__bool OggFLAC__seekable_stream_encoder_set_max_lpc_order(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
/** This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_set_qlp_coeff_precision().
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_qlp_coeff_precision().
*
* \note
* In the current implementation, qlp_coeff_precision + bits_per_sample must
@ -333,8 +301,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_max_lpc_order(OggFLAC__SeekableS
*/
FLAC__bool OggFLAC__seekable_stream_encoder_set_qlp_coeff_precision(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
/** This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_set_do_qlp_coeff_prec_search().
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search().
*
* \default \c false
* \param encoder An encoder instance to set.
@ -346,8 +314,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_qlp_coeff_precision(OggFLAC__See
*/
FLAC__bool OggFLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
/** This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_set_do_escape_coding().
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_do_escape_coding().
*
* \default \c false
* \param encoder An encoder instance to set.
@ -359,8 +327,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search(OggFLAC
*/
FLAC__bool OggFLAC__seekable_stream_encoder_set_do_escape_coding(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
/** This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_set_do_exhaustive_model_search().
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_do_exhaustive_model_search().
*
* \default \c false
* \param encoder An encoder instance to set.
@ -372,8 +340,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_do_escape_coding(OggFLAC__Seekab
*/
FLAC__bool OggFLAC__seekable_stream_encoder_set_do_exhaustive_model_search(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
/** This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_set_min_residual_partition_order().
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_min_residual_partition_order().
*
* \default \c 0
* \param encoder An encoder instance to set.
@ -385,8 +353,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_do_exhaustive_model_search(OggFL
*/
FLAC__bool OggFLAC__seekable_stream_encoder_set_min_residual_partition_order(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
/** This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_set_max_residual_partition_order().
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_max_residual_partition_order().
*
* \default \c 0
* \param encoder An encoder instance to set.
@ -398,8 +366,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_min_residual_partition_order(Ogg
*/
FLAC__bool OggFLAC__seekable_stream_encoder_set_max_residual_partition_order(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
/** This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_set_rice_parameter_search_dist().
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_rice_parameter_search_dist().
*
* \default \c 0
* \param encoder An encoder instance to set.
@ -411,8 +379,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_max_residual_partition_order(Ogg
*/
FLAC__bool OggFLAC__seekable_stream_encoder_set_rice_parameter_search_dist(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
/** This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_set_total_samples_estimate().
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_total_samples_estimate().
*
* \default \c 0
* \param encoder An encoder instance to set.
@ -424,8 +392,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_rice_parameter_search_dist(OggFL
*/
FLAC__bool OggFLAC__seekable_stream_encoder_set_total_samples_estimate(OggFLAC__SeekableStreamEncoder *encoder, FLAC__uint64 value);
/** This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_set_metadata().
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_metadata().
*
* \note
* The decoder instance \b will modify the first \c SEEKTABLE block
@ -464,8 +432,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_metadata(OggFLAC__SeekableStream
FLAC__bool OggFLAC__seekable_stream_encoder_set_seek_callback(OggFLAC__SeekableStreamEncoder *encoder, OggFLAC__SeekableStreamEncoderSeekCallback value);
/** Set the write callback.
* This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_set_write_callback().
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_write_callback().
*
* \note
* The callback is mandatory and must be set before initialization.
@ -505,34 +473,48 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_client_data(OggFLAC__SeekableStr
*/
OggFLAC__SeekableStreamEncoderState OggFLAC__seekable_stream_encoder_get_state(const OggFLAC__SeekableStreamEncoder *encoder);
/** Get the state of the underlying stream encoder.
/** Get the state of the underlying FLAC seekable stream encoder.
* Useful when the seekable stream encoder state is
* \c OggFLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR.
* \c OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_SEEKABLE_STREAM_ENCODER_ERROR.
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval OggFLAC__StreamEncoderState
* The stream encoder state.
* \retval FLAC__SeekableStreamEncoderState
* The FLAC seekable stream encoder state.
*/
OggFLAC__StreamEncoderState OggFLAC__seekable_stream_encoder_get_stream_encoder_state(const OggFLAC__SeekableStreamEncoder *encoder);
FLAC__SeekableStreamEncoderState OggFLAC__seekable_stream_encoder_get_FLAC_seekable_stream_encoder_state(const OggFLAC__SeekableStreamEncoder *encoder);
/** Get the state of the underlying stream encoder's verify decoder.
/** Get the state of the underlying FLAC seekable stream encoder's stream encoder.
* Useful when the seekable stream encoder state is
* \c OggFLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and the
* stream encoder state is \c OggFLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
* \c OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_SEEKABLE_STREAM_ENCODER_ERROR and the
* FLAC seekable stream encoder state is \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval OggFLAC__StreamEncoderState
* The stream encoder state.
* \retval FLAC__StreamEncoderState
* The FLAC stream encoder state.
*/
OggFLAC__StreamDecoderState OggFLAC__seekable_stream_encoder_get_verify_decoder_state(const OggFLAC__SeekableStreamEncoder *encoder);
FLAC__StreamEncoderState OggFLAC__seekable_stream_encoder_get_FLAC_stream_encoder_state(const OggFLAC__SeekableStreamEncoder *encoder);
/** Get the state of the underlying FLAC seekable stream encoder's verify decoder.
* Useful when the seekable stream encoder state is
* \c OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_SEEKABLE_STREAM_ENCODER_ERROR and the
* FLAC seekable stream encoder state is \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR
* and the stream encoder state is \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval OggFLAC__StreamDecoderState
* The FLAC verify decoder state.
*/
FLAC__StreamDecoderState OggFLAC__seekable_stream_encoder_get_verify_decoder_state(const OggFLAC__SeekableStreamEncoder *encoder);
/** Get the "verify" flag.
* This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_get_verify().
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_verify().
*
* \param encoder An encoder instance to query.
* \assert
@ -543,8 +525,8 @@ OggFLAC__StreamDecoderState OggFLAC__seekable_stream_encoder_get_verify_decoder_
FLAC__bool OggFLAC__seekable_stream_encoder_get_verify(const OggFLAC__SeekableStreamEncoder *encoder);
/** Get the "streamable subset" flag.
* This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_get_streamable_subset().
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_streamable_subset().
*
* \param encoder An encoder instance to query.
* \assert
@ -555,8 +537,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_get_verify(const OggFLAC__SeekableSt
FLAC__bool OggFLAC__seekable_stream_encoder_get_streamable_subset(const OggFLAC__SeekableStreamEncoder *encoder);
/** Get the "mid/side stereo coding" flag.
* This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_get_do_mid_side_stereo().
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_do_mid_side_stereo().
*
* \param encoder An encoder instance to query.
* \assert
@ -567,8 +549,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_get_streamable_subset(const OggFLAC_
FLAC__bool OggFLAC__seekable_stream_encoder_get_do_mid_side_stereo(const OggFLAC__SeekableStreamEncoder *encoder);
/** Get the "adaptive mid/side switching" flag.
* This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_get_loose_mid_side_stereo().
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_loose_mid_side_stereo().
*
* \param encoder An encoder instance to query.
* \assert
@ -579,8 +561,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_get_do_mid_side_stereo(const OggFLAC
FLAC__bool OggFLAC__seekable_stream_encoder_get_loose_mid_side_stereo(const OggFLAC__SeekableStreamEncoder *encoder);
/** Get the number of input channels being processed.
* This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_get_channels().
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_channels().
*
* \param encoder An encoder instance to query.
* \assert
@ -591,8 +573,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_get_loose_mid_side_stereo(const OggF
unsigned OggFLAC__seekable_stream_encoder_get_channels(const OggFLAC__SeekableStreamEncoder *encoder);
/** Get the input sample resolution setting.
* This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_get_bits_per_sample().
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_bits_per_sample().
*
* \param encoder An encoder instance to query.
* \assert
@ -603,8 +585,8 @@ unsigned OggFLAC__seekable_stream_encoder_get_channels(const OggFLAC__SeekableSt
unsigned OggFLAC__seekable_stream_encoder_get_bits_per_sample(const OggFLAC__SeekableStreamEncoder *encoder);
/** Get the input sample rate setting.
* This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_get_sample_rate().
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_sample_rate().
*
* \param encoder An encoder instance to query.
* \assert
@ -615,8 +597,8 @@ unsigned OggFLAC__seekable_stream_encoder_get_bits_per_sample(const OggFLAC__See
unsigned OggFLAC__seekable_stream_encoder_get_sample_rate(const OggFLAC__SeekableStreamEncoder *encoder);
/** Get the blocksize setting.
* This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_get_blocksize().
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_blocksize().
*
* \param encoder An encoder instance to query.
* \assert
@ -627,8 +609,8 @@ unsigned OggFLAC__seekable_stream_encoder_get_sample_rate(const OggFLAC__Seekabl
unsigned OggFLAC__seekable_stream_encoder_get_blocksize(const OggFLAC__SeekableStreamEncoder *encoder);
/** Get the maximum LPC order setting.
* This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_get_max_lpc_order().
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_max_lpc_order().
*
* \param encoder An encoder instance to query.
* \assert
@ -639,8 +621,8 @@ unsigned OggFLAC__seekable_stream_encoder_get_blocksize(const OggFLAC__SeekableS
unsigned OggFLAC__seekable_stream_encoder_get_max_lpc_order(const OggFLAC__SeekableStreamEncoder *encoder);
/** Get the quantized linear predictor coefficient precision setting.
* This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_get_qlp_coeff_precision().
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_qlp_coeff_precision().
*
* \param encoder An encoder instance to query.
* \assert
@ -651,8 +633,8 @@ unsigned OggFLAC__seekable_stream_encoder_get_max_lpc_order(const OggFLAC__Seeka
unsigned OggFLAC__seekable_stream_encoder_get_qlp_coeff_precision(const OggFLAC__SeekableStreamEncoder *encoder);
/** Get the qlp coefficient precision search flag.
* This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_get_do_qlp_coeff_prec_search().
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search().
*
* \param encoder An encoder instance to query.
* \assert
@ -663,8 +645,8 @@ unsigned OggFLAC__seekable_stream_encoder_get_qlp_coeff_precision(const OggFLAC_
FLAC__bool OggFLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search(const OggFLAC__SeekableStreamEncoder *encoder);
/** Get the "escape coding" flag.
* This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_get_do_escape_coding().
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_do_escape_coding().
*
* \param encoder An encoder instance to query.
* \assert
@ -675,8 +657,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search(const O
FLAC__bool OggFLAC__seekable_stream_encoder_get_do_escape_coding(const OggFLAC__SeekableStreamEncoder *encoder);
/** Get the exhaustive model search flag.
* This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_get_do_exhaustive_model_search().
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_do_exhaustive_model_search().
*
* \param encoder An encoder instance to query.
* \assert
@ -687,8 +669,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_get_do_escape_coding(const OggFLAC__
FLAC__bool OggFLAC__seekable_stream_encoder_get_do_exhaustive_model_search(const OggFLAC__SeekableStreamEncoder *encoder);
/** Get the minimum residual partition order setting.
* This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_get_min_residual_partition_order().
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_min_residual_partition_order().
*
* \param encoder An encoder instance to query.
* \assert
@ -699,8 +681,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_get_do_exhaustive_model_search(const
unsigned OggFLAC__seekable_stream_encoder_get_min_residual_partition_order(const OggFLAC__SeekableStreamEncoder *encoder);
/** Get maximum residual partition order setting.
* This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_get_max_residual_partition_order().
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_max_residual_partition_order().
*
* \param encoder An encoder instance to query.
* \assert
@ -711,8 +693,8 @@ unsigned OggFLAC__seekable_stream_encoder_get_min_residual_partition_order(const
unsigned OggFLAC__seekable_stream_encoder_get_max_residual_partition_order(const OggFLAC__SeekableStreamEncoder *encoder);
/** Get the Rice parameter search distance setting.
* This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_get_rice_parameter_search_dist().
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_rice_parameter_search_dist().
*
* \param encoder An encoder instance to query.
* \assert
@ -723,8 +705,8 @@ unsigned OggFLAC__seekable_stream_encoder_get_max_residual_partition_order(const
unsigned OggFLAC__seekable_stream_encoder_get_rice_parameter_search_dist(const OggFLAC__SeekableStreamEncoder *encoder);
/** Get the previously set estimate of the total samples to be encoded.
* This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_get_total_samples_estimate().
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_total_samples_estimate().
*
* \param encoder An encoder instance to query.
* \assert
@ -762,7 +744,7 @@ OggFLAC__SeekableStreamEncoderState OggFLAC__seekable_stream_encoder_init(OggFLA
* In the event of a prematurely-terminated encode, it is not strictly
* necessary to call this immediately before OggFLAC__seekable_stream_encoder_delete()
* but it is good practice to match every OggFLAC__seekable_stream_encoder_init()
* with a OggFLAC__seekable_stream_encoder_finish().
* with an OggFLAC__seekable_stream_encoder_finish().
*
* \param encoder An uninitialized encoder instance.
* \assert
@ -771,8 +753,8 @@ OggFLAC__SeekableStreamEncoderState OggFLAC__seekable_stream_encoder_init(OggFLA
void OggFLAC__seekable_stream_encoder_finish(OggFLAC__SeekableStreamEncoder *encoder);
/** Submit data for encoding.
* This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_process().
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_process().
*
* \param encoder An initialized encoder instance in the OK state.
* \param buffer An array of pointers to each channel's signal.
@ -788,8 +770,8 @@ void OggFLAC__seekable_stream_encoder_finish(OggFLAC__SeekableStreamEncoder *enc
FLAC__bool OggFLAC__seekable_stream_encoder_process(OggFLAC__SeekableStreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
/** Submit data for encoding.
* This is inherited from OggFLAC__StreamEncoder; see
* OggFLAC__stream_encoder_process_interleaved().
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_process_interleaved().
*
* \param encoder An initialized encoder instance in the OK state.
* \param buffer An array of channel-interleaved data (see above).

364
include/OggFLAC/stream_decoder.h
View File

@ -43,22 +43,9 @@ extern "C" {
* \brief
* This module describes the three decoder layers provided by libOggFLAC.
*
* For decoding OggFLAC streams, libOggFLAC provides three layers of access. The
* lowest layer is non-seekable stream-level decoding, the next is seekable
* stream-level decoding, and the highest layer is file-level decoding. The
* interfaces are described in the \link oggflac_stream_decoder stream decoder
* \endlink, \link oggflac_seekable_stream_decoder seekable stream decoder
* \endlink, and \link oggflac_file_decoder file decoder \endlink modules
* respectively. Typically you will choose the highest layer that your input
* source will support.
*
* The stream decoder relies on callbacks for all input and output and has no
* provisions for seeking. The seekable stream decoder wraps the stream
* decoder and exposes functions for seeking. However, you must provide
* extra callbacks for seek-related operations on your stream, like seek and
* tell. The file decoder wraps the seekable stream decoder and supplies
* most of the callbacks internally, simplifying the processing of standard
* files.
* libOggFLAC provides the same three layers of access as libFLAC and the
* interface is identical. See the \link flac_decoder FLAC decoder module
* \endlink for full documentation.
*/
/** \defgroup oggflac_stream_decoder OggFLAC/stream_decoder.h: stream decoder interface
@ -68,143 +55,33 @@ extern "C" {
* This module contains the functions which implement the stream
* decoder.
*
* The basic usage of this decoder is as follows:
* - The program creates an instance of a decoder using
* OggFLAC__stream_decoder_new().
* - The program overrides the default settings and sets callbacks for
* reading, writing, error reporting, and metadata reporting using
* OggFLAC__stream_decoder_set_*() functions.
* - The program initializes the instance to validate the settings and
* prepare for decoding using OggFLAC__stream_decoder_init().
* - The program calls the OggFLAC__stream_decoder_process_*() functions
* to decode data, which subsequently calls the callbacks.
* - The program finishes the decoding with OggFLAC__stream_decoder_finish(),
* which flushes the input and output and resets the decoder to the
* uninitialized state.
* - The instance may be used again or deleted with
* OggFLAC__stream_decoder_delete().
*
* In more detail, the program will create a new instance by calling
* OggFLAC__stream_decoder_new(), then call OggFLAC__stream_decoder_set_*()
* functions to set the callbacks and client data, and call
* OggFLAC__stream_decoder_init(). The required callbacks are:
*
* - Read callback - This function will be called when the decoder needs
* more input data. The address of the buffer to be filled is supplied,
* along with the number of bytes the buffer can hold. The callback may
* choose to supply less data and modify the byte count but must be careful
* not to overflow the buffer. The callback then returns a status code
* chosen from OggFLAC__StreamDecoderReadStatus.
* - Write callback - This function will be called when the decoder has
* decoded a single frame of data. The decoder will pass the frame
* metadata as well as an array of pointers (one for each channel)
* pointing to the decoded audio.
* - Metadata callback - This function will be called when the decoder has
* decoded a metadata block. There will always be one STREAMINFO block
* per stream, followed by zero or more other metadata blocks. These will
* be supplied by the decoder in the same order as they appear in the
* stream and always before the first audio frame (i.e. write callback).
* The metadata block that is passed in must not be modified, and it
* doesn't live beyond the callback, so you should make a copy of it with
* OggFLAC__metadata_object_clone() if you will need it elsewhere. Since
* metadata blocks can potentially be large, by default the decoder only
* calls the metadata callback for the STREAMINFO block; you can instruct
* the decoder to pass or filter other blocks with
* OggFLAC__stream_decoder_set_metadata_*() calls.
* - Error callback - This function will be called whenever an error occurs
* during decoding.
*
* Once the decoder is initialized, your program will call one of several
* functions to start the decoding process:
*
* - OggFLAC__stream_decoder_process_single() - Tells the decoder to process at
* most one metadata block or audio frame and return, calling either the
* metadata callback or write callback, respectively, once. If the decoder
* loses sync it will return with only the error callback being called.
* - OggFLAC__stream_decoder_process_until_end_of_metadata() - Tells the decoder
* to process the stream from the current location and stop upon reaching
* the first audio frame. The user will get one metadata, write, or error
* callback per metadata block, audio frame, or sync error, respectively.
* - OggFLAC__stream_decoder_process_until_end_of_stream() - Tells the decoder
* to process the stream from the current location until the read callback
* returns OggFLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM or
* OggFLAC__STREAM_DECODER_READ_STATUS_ABORT. The user will get one metadata,
* write, or error callback per metadata block, audio frame, or sync error,
* respectively.
*
* When the decoder has finished decoding (normally or through an abort),
* the instance is finished by calling OggFLAC__stream_decoder_finish(), which
* ensures the decoder is in the correct state and frees memory. Then the
* instance may be deleted with OggFLAC__stream_decoder_delete() or initialized
* again to decode another stream.
*
* Note that the stream decoder has no real concept of stream position, it
* just converts data. To seek within a stream the callbacks have only to
* flush the decoder using OggFLAC__stream_decoder_flush() and start feeding
* data from the new position through the read callback. The seekable
* stream decoder does just this.
*
* The OggFLAC__stream_decoder_set_metadata_*() functions deserve special
* attention. By default, the decoder only calls the metadata_callback for
* the STREAMINFO block. These functions allow you to tell the decoder
* explicitly which blocks to parse and return via the metadata_callback
* and/or which to skip. Use a OggFLAC__stream_decoder_respond_all(),
* OggFLAC__stream_decoder_ignore() ... or OggFLAC__stream_decoder_ignore_all(),
* OggFLAC__stream_decoder_respond() ... sequence to exactly specify which
* blocks to return. Remember that some metadata blocks can be big so
* filtering out the ones you don't use can reduce the memory requirements
* of the decoder. Also note the special forms
* OggFLAC__stream_decoder_respond_application(id) and
* OggFLAC__stream_decoder_ignore_application(id) for filtering APPLICATION
* blocks based on the application ID.
*
* STREAMINFO and SEEKTABLE blocks are always parsed and used internally, but
* they still can legally be filtered from the metadata_callback.
*
* \note
* The "set" functions may only be called when the decoder is in the
* state OggFLAC__STREAM_DECODER_UNINITIALIZED, i.e. after
* OggFLAC__stream_decoder_new() or OggFLAC__stream_decoder_finish(), but
* before OggFLAC__stream_decoder_init(). If this is the case they will
* return \c true, otherwise \c false.
*
* \note
* OggFLAC__stream_decoder_finish() resets all settings to the constructor
* defaults, including the callbacks.
* The interface here is identical to FLAC's stream decoder. See the
* defaults, including the callbacks. See the \link flac_stream_decoder
* FLAC stream decoder module \endlink for full documentation.
*
* \{
*/
/** State values for a OggFLAC__StreamDecoder
/** State values for an OggFLAC__StreamDecoder
*
* The decoder's state can be obtained by calling OggFLAC__stream_decoder_get_state().
*/
typedef enum {
OggFLAC__STREAM_DECODER_SEARCH_FOR_METADATA = 0,
/**< The decoder is ready to search for metadata. */
OggFLAC__STREAM_DECODER_OK = 0,
/**< The decoder is in the normal OK state. */
OggFLAC__STREAM_DECODER_READ_METADATA,
/**< The decoder is ready to or is in the process of reading metadata. */
OggFLAC__STREAM_DECODER_FLAC_STREAM_DECODER_ERROR,
/**< An error occurred in the underlying FLAC stream decoder;
* check OggFLAC__stream_decoder_get_FLAC_stream_decoder_state().
*/
OggFLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC,
/**< The decoder is ready to or is in the process of searching for the frame sync code. */
OggFLAC__STREAM_DECODER_READ_FRAME,
/**< The decoder is ready to or is in the process of reading a frame. */
OggFLAC__STREAM_DECODER_END_OF_STREAM,
/**< The decoder has reached the end of the stream. */
OggFLAC__STREAM_DECODER_ABORTED,
/**< The decoder was aborted by the read callback. */
OggFLAC__STREAM_DECODER_UNPARSEABLE_STREAM,
/**< The decoder encountered reserved fields in use in the stream. */
OggFLAC__STREAM_DECODER_INVALID_CALLBACK,
/**< The decoder was initialized before setting all the required callbacks. */
OggFLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
/**< An error occurred allocating memory. */
/**< Memory allocation failed. */
OggFLAC__STREAM_DECODER_ALREADY_INITIALIZED,
/**< OggFLAC__stream_decoder_init() was called when the decoder was
@ -212,88 +89,19 @@ typedef enum {
* OggFLAC__stream_decoder_finish() was not called.
*/
OggFLAC__STREAM_DECODER_INVALID_CALLBACK,
/**< OggFLAC__stream_decoder_init() was called without all callbacks being set. */
OggFLAC__STREAM_DECODER_UNINITIALIZED
/**< The decoder is in the uninitialized state. */
} OggFLAC__StreamDecoderState;
/** Maps a OggFLAC__StreamDecoderState to a C string.
/** Maps an OggFLAC__StreamDecoderState to a C string.
*
* Using a OggFLAC__StreamDecoderState as the index to this array
* Using an OggFLAC__StreamDecoderState as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern const char * const OggFLAC__StreamDecoderStateString[];
/** Return values for the OggFLAC__StreamDecoder read callback.
*/
typedef enum {
OggFLAC__STREAM_DECODER_READ_STATUS_CONTINUE,
/**< The read was OK and decoding can continue. */
OggFLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM,
/**< The read was attempted at the end of the stream. */
OggFLAC__STREAM_DECODER_READ_STATUS_ABORT
/**< An unrecoverable error occurred. The decoder will return from the process call. */
} OggFLAC__StreamDecoderReadStatus;
/** Maps a OggFLAC__StreamDecoderReadStatus to a C string.
*
* Using a OggFLAC__StreamDecoderReadStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern const char * const OggFLAC__StreamDecoderReadStatusString[];
/** Return values for the OggFLAC__StreamDecoder write callback.
*/
typedef enum {
OggFLAC__STREAM_DECODER_WRITE_STATUS_CONTINUE,
/**< The write was OK and decoding can continue. */
OggFLAC__STREAM_DECODER_WRITE_STATUS_ABORT
/**< An unrecoverable error occurred. The decoder will return from the process call. */
} OggFLAC__StreamDecoderWriteStatus;
/** Maps a OggFLAC__StreamDecoderWriteStatus to a C string.
*
* Using a OggFLAC__StreamDecoderWriteStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern const char * const OggFLAC__StreamDecoderWriteStatusString[];
/** Possible values passed in to the OggFLAC__StreamDecoder error callback.
*/
typedef enum {
OggFLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC,
/**< An error in the stream caused the decoder to lose synchronization. */
OggFLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER,
/**< The decoder encountered a corrupted frame header. */
OggFLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH
/**< The frame's data did not match the CRC in the footer. */
} OggFLAC__StreamDecoderErrorStatus;
/** Maps a OggFLAC__StreamDecoderErrorStatus to a C string.
*
* Using a OggFLAC__StreamDecoderErrorStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern const char * const OggFLAC__StreamDecoderErrorStatusString[];
/***********************************************************************
*
* class OggFLAC__StreamDecoder
@ -311,10 +119,10 @@ typedef struct {
struct OggFLAC__StreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
} OggFLAC__StreamDecoder;
typedef OggFLAC__StreamDecoderReadStatus (*OggFLAC__StreamDecoderReadCallback)(const OggFLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
typedef OggFLAC__StreamDecoderWriteStatus (*OggFLAC__StreamDecoderWriteCallback)(const OggFLAC__StreamDecoder *decoder, const OggFLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
typedef void (*OggFLAC__StreamDecoderMetadataCallback)(const OggFLAC__StreamDecoder *decoder, const OggFLAC__StreamMetadata *metadata, void *client_data);
typedef void (*OggFLAC__StreamDecoderErrorCallback)(const OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderErrorStatus status, void *client_data);
typedef FLAC__StreamDecoderReadStatus (*OggFLAC__StreamDecoderReadCallback)(const OggFLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
typedef FLAC__StreamDecoderWriteStatus (*OggFLAC__StreamDecoderWriteCallback)(const OggFLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
typedef void (*OggFLAC__StreamDecoderMetadataCallback)(const OggFLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
typedef void (*OggFLAC__StreamDecoderErrorCallback)(const OggFLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
/***********************************************************************
@ -348,12 +156,7 @@ void OggFLAC__stream_decoder_delete(OggFLAC__StreamDecoder *decoder);
***********************************************************************/
/** Set the read callback.
* The supplied function will be called when the decoder needs more input
* data. The address of the buffer to be filled is supplied, along with
* the number of bytes the buffer can hold. The callback may choose to
* supply less data and modify the byte count but must be careful not to
* overflow the buffer. The callback then returns a status code chosen
* from OggFLAC__StreamDecoderReadStatus.
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_read_callback()
*
* \note
* The callback is mandatory and must be set before initialization.
@ -370,10 +173,7 @@ void OggFLAC__stream_decoder_delete(OggFLAC__StreamDecoder *decoder);
FLAC__bool OggFLAC__stream_decoder_set_read_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderReadCallback);
/** Set the write callback.
* The supplied function will be called when the decoder has decoded a
* single frame of data. The decoder will pass the frame metadata as
* well as an array of pointers (one for each channel) pointing to the
* decoded audio.
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_write_callback()
*
* \note
* The callback is mandatory and must be set before initialization.
@ -390,18 +190,7 @@ FLAC__bool OggFLAC__stream_decoder_set_read_callback(OggFLAC__StreamDecoder *dec
FLAC__bool OggFLAC__stream_decoder_set_write_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderWriteCallback);
/** Set the metadata callback.
* The supplied function will be called when the decoder has decoded a
* metadata block. There will always be one STREAMINFO block per stream,
* followed by zero or more other metadata blocks. These will be supplied
* by the decoder in the same order as they appear in the stream and always
* before the first audio frame (i.e. write callback). The metadata block
* that is passed in must not be modified, and it doesn't live beyond the
* callback, so you should make a copy of it with
* OggFLAC__metadata_object_clone() if you will need it elsewhere. Since
* metadata blocks can potentially be large, by default the decoder only
* calls the metadata callback for the STREAMINFO block; you can instruct
* the decoder to pass or filter other blocks with
* OggFLAC__stream_decoder_set_metadata_*() calls.
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_callback()
*
* \note
* The callback is mandatory and must be set before initialization.
@ -418,8 +207,7 @@ FLAC__bool OggFLAC__stream_decoder_set_write_callback(OggFLAC__StreamDecoder *de
FLAC__bool OggFLAC__stream_decoder_set_metadata_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderMetadataCallback);
/** Set the error callback.
* The supplied function will be called whenever an error occurs during
* decoding.
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_error_callback()
*
* \note
* The callback is mandatory and must be set before initialization.
@ -450,6 +238,7 @@ FLAC__bool OggFLAC__stream_decoder_set_error_callback(OggFLAC__StreamDecoder *de
FLAC__bool OggFLAC__stream_decoder_set_client_data(OggFLAC__StreamDecoder *decoder, void *value);
/** Direct the decoder to pass on all metadata blocks of type \a type.
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_respond()
*
* \default By default, only the \c STREAMINFO block is returned via the
* metadata callback.
@ -465,6 +254,7 @@ FLAC__bool OggFLAC__stream_decoder_set_metadata_respond(OggFLAC__StreamDecoder *
/** Direct the decoder to pass on all APPLICATION metadata blocks of the
* given \a id.
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_respond_application()
*
* \default By default, only the \c STREAMINFO block is returned via the
* metadata callback.
@ -479,6 +269,7 @@ FLAC__bool OggFLAC__stream_decoder_set_metadata_respond(OggFLAC__StreamDecoder *
FLAC__bool OggFLAC__stream_decoder_set_metadata_respond_application(OggFLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
/** Direct the decoder to pass on all metadata blocks of any type.
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_respond_all()
*
* \default By default, only the \c STREAMINFO block is returned via the
* metadata callback.
@ -491,6 +282,7 @@ FLAC__bool OggFLAC__stream_decoder_set_metadata_respond_application(OggFLAC__Str
FLAC__bool OggFLAC__stream_decoder_set_metadata_respond_all(OggFLAC__StreamDecoder *decoder);
/** Direct the decoder to filter out all metadata blocks of type \a type.
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_ignore()
*
* \default By default, only the \c STREAMINFO block is returned via the
* metadata callback.
@ -506,6 +298,7 @@ FLAC__bool OggFLAC__stream_decoder_set_metadata_ignore(OggFLAC__StreamDecoder *d
/** Direct the decoder to filter out all APPLICATION metadata blocks of
* the given \a id.
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_ignore_application()
*
* \default By default, only the \c STREAMINFO block is returned via the
* metadata callback.
@ -520,6 +313,7 @@ FLAC__bool OggFLAC__stream_decoder_set_metadata_ignore(OggFLAC__StreamDecoder *d
FLAC__bool OggFLAC__stream_decoder_set_metadata_ignore_application(OggFLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
/** Direct the decoder to filter out all metadata blocks of any type.
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_ignore_all()
*
* \default By default, only the \c STREAMINFO block is returned via the
* metadata callback.
@ -541,9 +335,19 @@ FLAC__bool OggFLAC__stream_decoder_set_metadata_ignore_all(OggFLAC__StreamDecode
*/
OggFLAC__StreamDecoderState OggFLAC__stream_decoder_get_state(const OggFLAC__StreamDecoder *decoder);
/** Get the current number of channels in the stream being decoded.
* Will only be valid after decoding has started and will contain the
* value from the most recently decoded frame header.
/** Get the state of the underlying FLAC stream decoder.
* Useful when the stream decoder state is
* \c OggFLAC__STREAM_DECODER_FLAC_STREAM_DECODER_ERROR.
*
* \param decoder An decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__StreamDecoderState
* The FLAC stream decoder state.
*/
FLAC__StreamDecoderState OggFLAC__stream_decoder_get_FLAC_stream_decoder_state(const OggFLAC__StreamDecoder *decoder);
/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_channels()
*
* \param decoder A decoder instance to query.
* \assert
@ -553,9 +357,7 @@ OggFLAC__StreamDecoderState OggFLAC__stream_decoder_get_state(const OggFLAC__Str
*/
unsigned OggFLAC__stream_decoder_get_channels(const OggFLAC__StreamDecoder *decoder);
/** Get the current channel assignment in the stream being decoded.
* Will only be valid after decoding has started and will contain the
* value from the most recently decoded frame header.
/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_channel_assignment()
*
* \param decoder A decoder instance to query.
* \assert
@ -565,9 +367,7 @@ unsigned OggFLAC__stream_decoder_get_channels(const OggFLAC__StreamDecoder *deco
*/
OggFLAC__ChannelAssignment OggFLAC__stream_decoder_get_channel_assignment(const OggFLAC__StreamDecoder *decoder);
/** Get the current sample resolution in the stream being decoded.
* Will only be valid after decoding has started and will contain the
* value from the most recently decoded frame header.
/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_bits_per_sample()
*
* \param decoder A decoder instance to query.
* \assert
@ -577,9 +377,7 @@ OggFLAC__ChannelAssignment OggFLAC__stream_decoder_get_channel_assignment(const
*/
unsigned OggFLAC__stream_decoder_get_bits_per_sample(const OggFLAC__StreamDecoder *decoder);
/** Get the current sample rate in Hz of the stream being decoded.
* Will only be valid after decoding has started and will contain the
* value from the most recently decoded frame header.
/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_sample_rate()
*
* \param decoder A decoder instance to query.
* \assert
@ -589,9 +387,7 @@ unsigned OggFLAC__stream_decoder_get_bits_per_sample(const OggFLAC__StreamDecode
*/
unsigned OggFLAC__stream_decoder_get_sample_rate(const OggFLAC__StreamDecoder *decoder);
/** Get the current blocksize of the stream being decoded.
* Will only be valid after decoding has started and will contain the
* value from the most recently decoded frame header.
/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_blocksize()
*
* \param decoder A decoder instance to query.
* \assert
@ -605,14 +401,14 @@ unsigned OggFLAC__stream_decoder_get_blocksize(const OggFLAC__StreamDecoder *dec
* Should be called after OggFLAC__stream_decoder_new() and
* OggFLAC__stream_decoder_set_*() but before any of the
* OggFLAC__stream_decoder_process_*() functions. Will set and return the
* decoder state, which will be OggFLAC__STREAM_DECODER_SEARCH_FOR_METADATA
* decoder state, which will be OggFLAC__STREAM_DECODER_OK
* if initialization succeeded.
*
* \param decoder An uninitialized decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval OggFLAC__StreamDecoderState
* \c OggFLAC__STREAM_DECODER_SEARCH_FOR_MEATADATA if initialization was
* \c OggFLAC__STREAM_DECODER_OK if initialization was
* successful; see OggFLAC__StreamDecoderState for the meanings of other
* return values.
*/
@ -626,7 +422,7 @@ OggFLAC__StreamDecoderState OggFLAC__stream_decoder_init(OggFLAC__StreamDecoder
* In the event of a prematurely-terminated decode, it is not strictly
* necessary to call this immediately before OggFLAC__stream_decoder_delete()
* but it is good practice to match every OggFLAC__stream_decoder_init()
* with a OggFLAC__stream_decoder_finish().
* with an OggFLAC__stream_decoder_finish().
*
* \param decoder An uninitialized decoder instance.
* \assert
@ -634,9 +430,7 @@ OggFLAC__StreamDecoderState OggFLAC__stream_decoder_init(OggFLAC__StreamDecoder
*/
void OggFLAC__stream_decoder_finish(OggFLAC__StreamDecoder *decoder);
/** Flush the stream input.
* The decoder's input buffer will be cleared and the state set to
* \c OggFLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC.
/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_flush()
*
* \param decoder A decoder instance.
* \assert
@ -647,12 +441,7 @@ void OggFLAC__stream_decoder_finish(OggFLAC__StreamDecoder *decoder);
*/
FLAC__bool OggFLAC__stream_decoder_flush(OggFLAC__StreamDecoder *decoder);
/** Reset the decoding process.
* The decoder's input buffer will be cleared and the state set to
* \c OggFLAC__STREAM_DECODER_SEARCH_FOR_METADATA. This is similar to
* OggFLAC__stream_decoder_finish() except that the settings are
* preserved; there is no need to call OggFLAC__stream_decoder_init()
* before decoding again.
/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_reset()
*
* \param decoder A decoder instance.
* \assert
@ -664,25 +453,16 @@ FLAC__bool OggFLAC__stream_decoder_flush(OggFLAC__StreamDecoder *decoder);
FLAC__bool OggFLAC__stream_decoder_reset(OggFLAC__StreamDecoder *decoder);
/** Decode one metadata block or audio frame.
* This version instructs the decoder to decode a either a single metadata
* block or a single frame and stop, unless the callbacks return a fatal
* error or the read callback returns
* \c OggFLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
*
* As the decoder needs more input it will call the read callback.
* Depending on what was decoded, the metadata or write callback will be
* called with the decoded metadata block or audio frame, unless an error
* occurred. If the decoder loses sync it will call the error callback
* instead.
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_process_single()
*
* \param decoder An initialized decoder instance in the state
* \c OggFLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC.
* \c OggFLAC__STREAM_DECODER_OK.
* \assert
* \code decoder != NULL \endcode
* \code OggFLAC__stream_decoder_get_state(decoder) == OggFLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC \endcode
* \code OggFLAC__stream_decoder_get_state(decoder) == OggFLAC__STREAM_DECODER_OK \endcode
* \retval FLAC__bool
* \c false if any read or write error occurred (except
* \c OggFLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c false;
* \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c false;
* in any case, check the decoder state with
* OggFLAC__stream_decoder_get_state() to see what went wrong or to
* check for lost synchronization (a sign of stream corruption).
@ -690,21 +470,13 @@ FLAC__bool OggFLAC__stream_decoder_reset(OggFLAC__StreamDecoder *decoder);
FLAC__bool OggFLAC__stream_decoder_process_single(OggFLAC__StreamDecoder *decoder);
/** Decode until the end of the metadata.
* This version instructs the decoder to decode from the current position
* and continue until all the metadata has been read, or until the
* callbacks return a fatal error or the read callback returns
* \c OggFLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
*
* As the decoder needs more input it will call the read callback.
* As each metadata block is decoded, the metadata callback will be called
* with the decoded metadata. If the decoder loses sync it will call the
* error callback.
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_process_until_end_of_metadata()
*
* \param decoder An initialized decoder instance in the state
* \c OggFLAC__STREAM_DECODER_SEARCH_FOR_METADATA.
* \c OggFLAC__STREAM_DECODER_OK.
* \assert
* \code decoder != NULL \endcode
* \code OggFLAC__stream_decoder_get_state(decoder) == OggFLAC__STREAM_DECODER_SEARCH_FOR_METADATA \endcode
* \code OggFLAC__stream_decoder_get_state(decoder) == OggFLAC__STREAM_DECODER_OK \endcode
* \retval FLAC__bool
* \c false if any read or write error occurred (except
* \c OggFLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c false;
@ -715,21 +487,13 @@ FLAC__bool OggFLAC__stream_decoder_process_single(OggFLAC__StreamDecoder *decode
FLAC__bool OggFLAC__stream_decoder_process_until_end_of_metadata(OggFLAC__StreamDecoder *decoder);
/** Decode until the end of the stream.
* This version instructs the decoder to decode from the current position
* and continue until the end of stream (the read callback returns
* \c OggFLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM), or until the
* callbacks return a fatal error.
*
* As the decoder needs more input it will call the read callback.
* As each metadata block and frame is decoded, the metadata or write
* callback will be called with the decoded metadata or frame. If the
* decoder loses sync it will call the error callback.
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_process_until_end_of_stream()
*
* \param decoder An initialized decoder instance in the state
* \c OggFLAC__STREAM_DECODER_SEARCH_FOR_METADATA.
* \c OggFLAC__STREAM_DECODER_OK.
* \assert
* \code decoder != NULL \endcode
* \code OggFLAC__stream_decoder_get_state(decoder) == OggFLAC__STREAM_DECODER_SEARCH_FOR_METADATA \endcode
* \code OggFLAC__stream_decoder_get_state(decoder) == OggFLAC__STREAM_DECODER_OK \endcode
* \retval FLAC__bool
* \c false if any read or write error occurred (except
* \c OggFLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c false;

465
include/OggFLAC/stream_encoder.h
View File

@ -58,11 +58,12 @@ extern "C" {
* The interface here is identical to FLAC's stream encoder. See the
* defaults, including the callbacks. See the \link flac_stream_encoder
* FLAC stream encoder module \endlink for full documentation.
*
* \{
*/
/** State values for a OggFLAC__StreamEncoder
/** State values for an OggFLAC__StreamEncoder
*
* The encoder's state can be obtained by calling OggFLAC__stream_encoder_get_state().
*/
@ -71,9 +72,9 @@ typedef enum {
OggFLAC__STREAM_ENCODER_OK = 0,
/**< The encoder is in the normal OK state. */
OggFLAC__STREAM_ENCODER_FLAC_ENCODER_ERROR,
OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR,
/**< An error occurred in the underlying FLAC stream encoder;
* check OggFLAC__stream_encoder_get_FLAC_encoder_state().
* check OggFLAC__stream_encoder_get_FLAC_stream_encoder_state().
*/
OggFLAC__STREAM_ENCODER_INVALID_CALLBACK,
@ -95,30 +96,11 @@ typedef enum {
/** Maps an OggFLAC__StreamEncoderState to a C string.
*
* Using a OggFLAC__StreamEncoderState as the index to this array
* Using an OggFLAC__StreamEncoderState as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern const char * const OggFLAC__StreamEncoderStateString[];
/** Return values for the OggFLAC__StreamEncoder write callback.
*/
typedef enum {
OggFLAC__STREAM_ENCODER_WRITE_STATUS_OK = 0,
/**< The write was OK and encoding can continue. */
OggFLAC__STREAM_ENCODER_WRITE_STATUS_FATAL_ERROR
/**< An unrecoverable error occurred. The encoder will return from the process call. */
} OggFLAC__StreamEncoderWriteStatus;
/** Maps an OggFLAC__StreamEncoderWriteStatus to a C string.
*
* Using a OggFLAC__StreamEncoderWriteStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern const char * const OggFLAC__StreamEncoderWriteStatusString[];
/***********************************************************************
*
@ -139,7 +121,6 @@ typedef struct {
/*@@@@ document: */
typedef OggFLAC__StreamEncoderWriteStatus (*OggFLAC__StreamEncoderWriteCallback)(const OggFLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
typedef void (*OggFLAC__StreamEncoderMetadataCallback)(const OggFLAC__StreamEncoder *encoder, const OggFLAC__StreamMetadata *metadata, void *client_data);
/***********************************************************************
@ -165,206 +146,534 @@ OggFLAC__StreamEncoder *OggFLAC__stream_encoder_new();
*/
void OggFLAC__stream_encoder_delete(OggFLAC__StreamEncoder *encoder);
/***********************************************************************
*
* Public class method prototypes
*
***********************************************************************/
/** Inherited from FLAC__stream_encoder_set_verify()
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_verify()
*
* \default \c false
* \param encoder An encoder instance to set.
* \param value Flag value (see above).
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC__bool OggFLAC__stream_encoder_set_verify(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
/** Inherited from FLAC__stream_encoder_set_streamable_subset()
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_streamable_subset()
*
* \default \c true
* \param encoder An encoder instance to set.
* \param value Flag value (see above).
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC__bool OggFLAC__stream_encoder_set_streamable_subset(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
/** Inherited from FLAC__stream_encoder_set_do_mid_side_stereo()
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_mid_side_stereo()
*
* \default \c false
* \param encoder An encoder instance to set.
* \param value Flag value (see above).
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC__bool OggFLAC__stream_encoder_set_do_mid_side_stereo(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
/** Inherited from FLAC__stream_encoder_set_loose_mid_side_stereo()
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_loose_mid_side_stereo()
*
* \default \c false
* \param encoder An encoder instance to set.
* \param value Flag value (see above).
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC__bool OggFLAC__stream_encoder_set_loose_mid_side_stereo(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
/** Inherited from FLAC__stream_encoder_set_channels()
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_channels()
*
* \default \c 2
* \param encoder An encoder instance to set.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC__bool OggFLAC__stream_encoder_set_channels(OggFLAC__StreamEncoder *encoder, unsigned value);
/** Inherited from FLAC__stream_encoder_set_bits_per_sample()
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_bits_per_sample()
*
* \default \c 16
* \param encoder An encoder instance to set.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC__bool OggFLAC__stream_encoder_set_bits_per_sample(OggFLAC__StreamEncoder *encoder, unsigned value);
/** Inherited from FLAC__stream_encoder_set_sample_rate()
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_sample_rate()
*
* \default \c 44100
* \param encoder An encoder instance to set.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC__bool OggFLAC__stream_encoder_set_sample_rate(OggFLAC__StreamEncoder *encoder, unsigned value);
/** Inherited from FLAC__stream_encoder_set_blocksize()
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_blocksize()
*
* \default \c 1152
* \param encoder An encoder instance to set.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC__bool OggFLAC__stream_encoder_set_blocksize(OggFLAC__StreamEncoder *encoder, unsigned value);
/** Inherited from FLAC__stream_encoder_set_max_lpc_order()
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_max_lpc_order()
*
* \default \c 0
* \param encoder An encoder instance to set.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC__bool OggFLAC__stream_encoder_set_max_lpc_order(OggFLAC__StreamEncoder *encoder, unsigned value);
/** Inherited from FLAC__stream_encoder_set_qlp_coeff_precision()
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_qlp_coeff_precision()
*
* \default \c 0
* \param encoder An encoder instance to set.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC__bool OggFLAC__stream_encoder_set_qlp_coeff_precision(OggFLAC__StreamEncoder *encoder, unsigned value);
/** Inherited from FLAC__stream_encoder_set_do_qlp_coeff_prec_search()
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_qlp_coeff_prec_search()
*
* \default \c false
* \param encoder An encoder instance to set.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC__bool OggFLAC__stream_encoder_set_do_qlp_coeff_prec_search(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
/** Inherited from FLAC__stream_encoder_set_do_escape_coding()
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_escape_coding()
*
* \default \c false
* \param encoder An encoder instance to set.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC__bool OggFLAC__stream_encoder_set_do_escape_coding(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
/** Inherited from FLAC__stream_encoder_set_do_exhaustive_model_search()
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_exhaustive_model_search()
*
* \default \c false
* \param encoder An encoder instance to set.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC__bool OggFLAC__stream_encoder_set_do_exhaustive_model_search(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
/** Inherited from FLAC__stream_encoder_set_min_residual_partition_order()
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_min_residual_partition_order()
*
* \default \c 0
* \param encoder An encoder instance to set.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC__bool OggFLAC__stream_encoder_set_min_residual_partition_order(OggFLAC__StreamEncoder *encoder, unsigned value);
/** Inherited from FLAC__stream_encoder_set_max_residual_partition_order()
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_max_residual_partition_order()
*
* \default \c 0
* \param encoder An encoder instance to set.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC__bool OggFLAC__stream_encoder_set_max_residual_partition_order(OggFLAC__StreamEncoder *encoder, unsigned value);
/** Inherited from FLAC__stream_encoder_set_rice_parameter_search_dist()
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_rice_parameter_search_dist()
*
* \default \c 0
* \param encoder An encoder instance to set.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC__bool OggFLAC__stream_encoder_set_rice_parameter_search_dist(OggFLAC__StreamEncoder *encoder, unsigned value);
/** Inherited from FLAC__stream_encoder_set_total_samples_estimate()
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_total_samples_estimate()
*
* \default \c 0
* \param encoder An encoder instance to set.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC__bool OggFLAC__stream_encoder_set_total_samples_estimate(OggFLAC__StreamEncoder *encoder, FLAC__uint64 value);
/** Inherited from FLAC__stream_encoder_set_metadata()
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_metadata()
*
* \default \c NULL, 0
* \param encoder An encoder instance to set.
* \param metadata See above.
* \param num_blocks See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC__bool OggFLAC__stream_encoder_set_metadata(OggFLAC__StreamEncoder *encoder, OggFLAC__StreamMetadata **metadata, unsigned num_blocks);
/** Inherited from FLAC__stream_encoder_set_write_callback()
/** Set the write callback.
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param encoder An encoder instance to set.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC__bool OggFLAC__stream_encoder_set_write_callback(OggFLAC__StreamEncoder *encoder, OggFLAC__StreamEncoderWriteCallback value);
/** Inherited from FLAC__stream_encoder_set_metadata_callback()
*/
FLAC__bool OggFLAC__stream_encoder_set_metadata_callback(OggFLAC__StreamEncoder *encoder, OggFLAC__StreamEncoderMetadataCallback value);
/** Inherited from FLAC__stream_encoder_set_client_data()
/** Set the client data to be passed back to callbacks.
* This value will be supplied to callbacks in their \a client_data
* argument.
*
* \default \c NULL
* \param encoder An encoder instance to set.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC__bool OggFLAC__stream_encoder_set_client_data(OggFLAC__StreamEncoder *encoder, void *value);
/** Inherited from FLAC__stream_encoder_get_state()
/** Get the current encoder state.
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval OggFLAC__StreamEncoderState
* The current encoder state.
*/
OggFLAC__StreamEncoderState OggFLAC__stream_encoder_get_state(const OggFLAC__StreamEncoder *encoder);
/** Get the state of the underlying FLAC encoder.
/** Get the state of the underlying FLAC stream encoder.
* Useful when the stream encoder state is
* \c OggFLAC__STREAM_ENCODER_FLAC_ENCODER_ERROR.
* \c OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR.
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__StreamEncoderState
* The stream encoder state.
* The FLAC stream encoder state.
*/
FLAC__StreamEncoderState OggFLAC__stream_encoder_get_FLAC_encoder_state(const OggFLAC__StreamEncoder *encoder);
FLAC__StreamEncoderState OggFLAC__stream_encoder_get_FLAC_stream_encoder_state(const OggFLAC__StreamEncoder *encoder);
/** Get the state of the FLAC encoder's verify decoder.
/** Get the state of the underlying FLAC stream encoder's verify decoder.
* Useful when the stream encoder state is
* \c OggFLAC__STREAM_ENCODER_FLAC_ENCODER_ERROR and the
* FLAC encoder state is \c OggFLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
* \c OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR and the
* FLAC encoder state is \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__StreamDecoderState
* The stream encoder state.
* The FLAC verify decoder state.
*/
FLAC__StreamDecoderState OggFLAC__stream_encoder_get_verify_decoder_state(const OggFLAC__StreamEncoder *encoder);
/** Inherited from FLAC__stream_encoder_get_verify()
/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_verify()
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See OggFLAC__stream_encoder_set_verify().
*/
FLAC__bool OggFLAC__stream_encoder_get_verify(const OggFLAC__StreamEncoder *encoder);
/** Inherited from FLAC__stream_encoder_get_streamable_subset()
/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_streamable_subset()
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See OggFLAC__stream_encoder_set_streamable_subset().
*/
FLAC__bool OggFLAC__stream_encoder_get_streamable_subset(const OggFLAC__StreamEncoder *encoder);
/** Inherited from FLAC__stream_encoder_get_do_mid_side_stereo()
/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_mid_side_stereo()
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See OggFLAC__stream_encoder_get_do_mid_side_stereo().
*/
FLAC__bool OggFLAC__stream_encoder_get_do_mid_side_stereo(const OggFLAC__StreamEncoder *encoder);
/** Inherited from FLAC__stream_encoder_get_loose_mid_side_stereo()
/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_loose_mid_side_stereo()
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See OggFLAC__stream_encoder_set_loose_mid_side_stereo().
*/
FLAC__bool OggFLAC__stream_encoder_get_loose_mid_side_stereo(const OggFLAC__StreamEncoder *encoder);
/** Inherited from FLAC__stream_encoder_get_channels()
/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_channels()
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See OggFLAC__stream_encoder_set_channels().
*/
unsigned OggFLAC__stream_encoder_get_channels(const OggFLAC__StreamEncoder *encoder);
/** Inherited from FLAC__stream_encoder_get_bits_per_sample()
/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_bits_per_sample()
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See OggFLAC__stream_encoder_set_bits_per_sample().
*/
unsigned OggFLAC__stream_encoder_get_bits_per_sample(const OggFLAC__StreamEncoder *encoder);
/** Inherited from FLAC__stream_encoder_get_sample_rate()
/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_sample_rate()
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See OggFLAC__stream_encoder_set_sample_rate().
*/
unsigned OggFLAC__stream_encoder_get_sample_rate(const OggFLAC__StreamEncoder *encoder);
/** Inherited from FLAC__stream_encoder_get_blocksize()
/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_blocksize()
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See OggFLAC__stream_encoder_set_blocksize().
*/
unsigned OggFLAC__stream_encoder_get_blocksize(const OggFLAC__StreamEncoder *encoder);
/** Inherited from FLAC__stream_encoder_get_max_lpc_order()
/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_max_lpc_order()
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See OggFLAC__stream_encoder_set_max_lpc_order().
*/
unsigned OggFLAC__stream_encoder_get_max_lpc_order(const OggFLAC__StreamEncoder *encoder);
/** Inherited from FLAC__stream_encoder_get_qlp_coeff_precision()
/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_qlp_coeff_precision()
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See OggFLAC__stream_encoder_set_qlp_coeff_precision().
*/
unsigned OggFLAC__stream_encoder_get_qlp_coeff_precision(const OggFLAC__StreamEncoder *encoder);
/** Inherited from FLAC__stream_encoder_get_do_qlp_coeff_prec_search()
/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_qlp_coeff_prec_search()
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See OggFLAC__stream_encoder_set_do_qlp_coeff_prec_search().
*/
FLAC__bool OggFLAC__stream_encoder_get_do_qlp_coeff_prec_search(const OggFLAC__StreamEncoder *encoder);
/** Inherited from FLAC__stream_encoder_get_do_escape_coding()
/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_escape_coding()
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See OggFLAC__stream_encoder_set_do_escape_coding().
*/
FLAC__bool OggFLAC__stream_encoder_get_do_escape_coding(const OggFLAC__StreamEncoder *encoder);
/** Inherited from FLAC__stream_encoder_get_do_exhaustive_model_search()
/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_exhaustive_model_search()
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See OggFLAC__stream_encoder_set_do_exhaustive_model_search().
*/
FLAC__bool OggFLAC__stream_encoder_get_do_exhaustive_model_search(const OggFLAC__StreamEncoder *encoder);
/** Inherited from FLAC__stream_encoder_get_min_residual_partition_order()
/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_min_residual_partition_order()
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See OggFLAC__stream_encoder_set_min_residual_partition_order().
*/
unsigned OggFLAC__stream_encoder_get_min_residual_partition_order(const OggFLAC__StreamEncoder *encoder);
/** Inherited from FLAC__stream_encoder_get_max_residual_partition_order()
/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_man_residual_partition_order()
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See OggFLAC__stream_encoder_set_max_residual_partition_order().
*/
unsigned OggFLAC__stream_encoder_get_max_residual_partition_order(const OggFLAC__StreamEncoder *encoder);
/** Inherited from FLAC__stream_encoder_get_rice_parameter_search_dist()
/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_rice_parameter_search_dist()
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See OggFLAC__stream_encoder_set_rice_parameter_search_dist().
*/
unsigned OggFLAC__stream_encoder_get_rice_parameter_search_dist(const OggFLAC__StreamEncoder *encoder);
/** Inherited from FLAC__stream_encoder_get_total_samples_estimate()
/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_total_samples_estimate()
*
* \param encoder An encoder instance to set.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__uint64
* See OggFLAC__stream_encoder_get_total_samples_estimate().
*/
FLAC__uint64 OggFLAC__stream_encoder_get_total_samples_estimate(const OggFLAC__StreamEncoder *encoder);
/** Inherited from FLAC__stream_encoder_init()
/** Initialize the encoder instance.
* Should be called after OggFLAC__stream_encoder_new() and
* OggFLAC__stream_encoder_set_*() but before OggFLAC__stream_encoder_process()
* or OggFLAC__stream_encoder_process_interleaved(). Will set and return
* the encoder state, which will be OggFLAC__STREAM_ENCODER_OK if
* initialization succeeded.
*
* The call to OggFLAC__stream_encoder_init() currently will also immediately
* call the write callback several times, once with the \c fLaC signature,
* and once for each encoded metadata block.
*
* \param encoder An uninitialized encoder instance.
* \assert
* \code encoder != NULL \endcode
* \retval OggFLAC__StreamEncoderState
* \c OggFLAC__STREAM_ENCODER_OK if initialization was successful; see
* OggFLAC__StreamEncoderState for the meanings of other return values.
*/
OggFLAC__StreamEncoderState OggFLAC__stream_encoder_init(OggFLAC__StreamEncoder *encoder);
/** Inherited from FLAC__stream_encoder_finish()
/** Finish the encoding process.
* Flushes the encoding buffer, releases resources, resets the encoder
* settings to their defaults, and returns the encoder state to
* OggFLAC__STREAM_ENCODER_UNINITIALIZED. Note that this can generate
* one or more write callbacks before returning.
*
* In the event of a prematurely-terminated encode, it is not strictly
* necessary to call this immediately before OggFLAC__stream_encoder_delete()
* but it is good practice to match every OggFLAC__stream_encoder_init()
* with an OggFLAC__stream_encoder_finish().
*
* \param encoder An uninitialized encoder instance.
* \assert
* \code encoder != NULL \endcode
*/
void OggFLAC__stream_encoder_finish(OggFLAC__StreamEncoder *encoder);
/** Inherited from FLAC__stream_encoder_process()
/** Submit data for encoding.
* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_process().
*
* \param encoder An initialized encoder instance in the OK state.
* \param buffer An array of pointers to each channel's signal.
* \param samples The number of samples in one channel.
* \assert
* \code encoder != NULL \endcode
* \code OggFLAC__stream_encoder_get_state(encoder) == OggFLAC__STREAM_ENCODER_OK \endcode
* \retval FLAC__bool
* \c true if successful, else \c false; in this case, check the
* encoder state with OggFLAC__stream_encoder_get_state() to see what
* went wrong.
*/
FLAC__bool OggFLAC__stream_encoder_process(OggFLAC__StreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
/** Inherited from FLAC__stream_encoder_process_interleaved()
/** Submit data for encoding.
* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_process_interleaved().
*
* \param encoder An initialized encoder instance in the OK state.
* \param buffer An array of channel-interleaved data (see above).
* \param samples The number of samples in one channel, the same as for
* OggFLAC__stream_encoder_process(). For example, if
* encoding two channels, \c 1000 \a samples corresponds
* to a \a buffer of 2000 values.
* \assert
* \code encoder != NULL \endcode
* \code OggFLAC__stream_encoder_get_state(encoder) == OggFLAC__STREAM_ENCODER_OK \endcode
* \retval FLAC__bool
* \c true if successful, else \c false; in this case, check the
* encoder state with OggFLAC__stream_encoder_get_state() to see what
* went wrong.
*/
FLAC__bool OggFLAC__stream_encoder_process_interleaved(OggFLAC__StreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);